Bird Verify

预览版

无需存储的验证 API。

集成时间：

通过邮件、SMS 或 WhatsApp 发送一次性验证码，然后按接收方进行验证，两次调用之间无需保留验证 ID。渠道顺序、发送方和验证码规则按国家/地区配置，无需重新构建。与所有其他 Bird 渠道共享相同的认证和幂等机制，因为它们都由同一个团队打造。语音渠道即将推出。

verify.ts

200 · pending

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Send the code, then check it by recipient.
await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: userInput,
}).safe();

verify.ts

200 · pending

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Send the code, then check it by recipient.
await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: userInput,
}).safe();

从安装到用户验证，仅需两次调用

用您已熟悉的语言发送并验证验证码。

Create-or-retry 发送验证码；check 按接收方确认验证码。两次调用，无需在它们之间传递验证 ID。

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: "482917",
}).safe();

十项您无需自行构建的功能
——当验证就是 API。

具体的基础组件，命名清晰、可配置。绝不含糊。

01
一次调用即可创建或重试。
重新提交相同的接收方，我们会恢复当前会话，并在冷却时间过后重新发送。无需单独的重发端点，不会产生重复验证。
02
按目标检查，无需存储。
提交接收方和验证码；我们通过配置与接收方的组合解析会话。发送和检查之间无需持久化验证 ID。
03
首发支持邮件、SMS 和 WhatsApp。
您传入的收件人决定了使用哪个通道：电子邮件地址通过邮件验证，电话号码通过 SMS 或 WhatsApp 验证。切换通道只需更改一个字段，无需重新集成。语音通道即将上线，通道间自动降级回退也在规划中。
04
按国家/地区配置渠道顺序。
将渠道顺序、发送方以及启用的渠道按国家/地区设置为一等配置资源，而非提交支持工单。
05
您永远看不到的验证码。
验证码通过加密随机源生成，仅以 HMAC 形式存储，并在恒定时间内进行比较。明文验证码不会触及您的技术栈或我们的日志。
06
可配置的验证码、TTL 和尝试次数。
默认 6 位验证码，可配置 4–10 位；10 分钟有效期；5 次尝试机会；60 秒重发冷却时间，均可按配置设定。验证码长度也可按请求单独覆盖。
07
每个验证码在会话结束前始终有效。
延迟送达的消息和重新发送的验证码都可用于验证，因为我们不会在发送新验证码时使旧验证码失效。
08
错误的验证码返回 200，而非异常。
通过布尔结果校验答案——该验证码是否通过验证，是或否——并附带原因说明失败情况：无效、已过期、已验证或尝试次数用尽。您只需根据字段值进行分支判断，无需捕获抛出的异常。
09
内置速率限制和配额。
按接收者的发送上限、按验证的猜测次数限制、按工作空间的每日配额——每项超限均返回 429 及 Retry-After，让暴力攻击在耗尽您的资源之前先耗尽自身。
10
与 Bird 其他产品相同的接口契约。
Bearer 认证、幂等键、带类型的 vrf_ ID、统一错误信封。您为邮件编写的处理逻辑同样适用于验证。

探索 Verify 平台

每项能力的深度解析。一套 API，一组密钥。

SMS OTP通过 SMS 发送一次性验证码，覆盖全球并内置速率限制。Email OTP在已承载您事务性邮件的网络上通过邮件验证。WhatsApp OTP在同一方案中将 WhatsApp 作为可排序的渠道发送验证码。Voice OTP即将推出：为固定电话、无障碍需求及难以触达的用户提供语音验证码。渠道编排按国家配置渠道顺序、发送者和启用/禁用，作为一等配置资源。防滥用与验证码安全哈希验证码、按接收者上限、尝试锁定以及反欺诈路线图。

在发送和验证之间无需存储任何内容。

大多数验证 API 会返回一个 ID，需要您持久化、查询并提交验证码进行校验。Bird 通过接收者解析会话，因此您无需维护任何按验证的状态。

大多数验证 API

创建请求返回一个您需要存储的 ID，然后查找该验证记录以校验验证码。

id-keyed.ts

const { id } = await api.verifications.create({
  to: "+15551234567",
});
// persist id somewhere, then later…
await api.verifications.check({ id, code });

Bird Verify

按接收者校验。两次调用之间无需传递任何内容。

by-target.ts

await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();
// no id to store; check by the same recipient
await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" }, code,
}).safe();

按国家路由即配置。

按国家设置渠道顺序、发送者以及启用哪些渠道——在一个市场优先使用 WhatsApp，在另一个市场仅用 SMS。这是一等配置资源，会解析到每次验证的方案中。参见渠道编排。

per-country.ts

200

await bird.verify.verifications.configurations.countries.upsert(
  "vfc_login",
  "BR",
  { channels: [
    { channel: "whatsapp", state: "enabled" },
    { channel: "sms", state: "enabled" },
  ] },
).safe();

验证也是一项产品决策：同一 API 支持双因素认证和无密码登录。需要先验证号码？搭配 Lookup 使用。静默网络认证和 TOTP 认证器应用已在路线图中。

我们为何构建 Verify

因为让用户登录的验证码不应该需要一张专属数据库表。

阅读 Verify 文档

OTP 是这样一种渠道：验证码送达失败意味着注册流程中断。Bird 已大规模运行邮件和 SMS，因此 Verify 就是在此投递能力之上加上验证码生成、会话管理、按国家渠道方案和速率限制——仅需两个端点，您无需存储任何内容，响应格式与所有其他 Bird 渠道一致。

verify.ts

200 · pending

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Send the code, then check it by recipient.
await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: userInput,
}).safe();

verify.ts

200 · pending

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Send the code, then check it by recipient.
await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: userInput,
}).safe();

如果您已集成 SMS，就等于已集成 Verify。

相同的认证模型、相同的幂等契约、相同的错误信封。区别在于 Verify 会生成验证码、选择渠道并执行速率限制——您无需操心。

Verify

一次调用发送验证码，一次调用按接收者校验。验证码、会话和频率限制均由我们管理。

verify.ts

await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
});

SMS

原始发送模式，适用于您希望自行控制验证码生成和重试策略的场景。

notify.ts

await bird.sms.send({
  from: "Bird",
  to:   "+15551234567",
  text: `Your code is ${code}.`,
});

Verify API 常见问题

如何在我的应用中添加验证功能？+

只需两次调用：为收件人创建一个验证，然后校验他们输入的验证码。校验基于收件人进行，因此无需在两次调用之间存储验证 ID——您只需要配置 ID（一个常量）和地址即可。

可以通过哪些渠道进行验证？+

目前支持邮件、SMS 和 WhatsApp。语音作为附加渠道正在逐步推出，渠道顺序、发送方以及启用的渠道均可按国家/地区配置——无需更改代码。

我需要存储验证 ID 吗？+

不需要。重发与创建是同一个调用（create-or-retry），检查基于接收方地址进行，因此验证无需在您这边保存任何请求级状态。如果您需要稍后查询状态，会返回一个 ID，但这是可选的。

当用户输入错误的验证码时会怎样？+

检查接口返回 200 并附带结果——在尝试次数未用完时返回 invalid，用完后返回 failed，超过时间窗口后返回 expired。错误的验证码是您可以在逻辑中分支处理的正常结果，而非 HTTP 错误。

验证码如何生成和存储？+

验证码通过加密随机源生成，仅以 HMAC-SHA256 哈希形式存储，并在恒定时间内进行比较。明文验证码永远不会返回，也不会写入您的系统或我们的日志。长度（4–10 位数字）、有效期和尝试次数限制均可配置。

费用是多少？+

Verify 目前处于预览阶段，尚未列入公开价格表。请联系我们，我们将根据您的渠道和用量为您详细说明定价。

我的用户看到验证码来自谁？+

Authifly，Bird 的验证品牌。它是您的用户收到的每个验证码上显示的身份标识：邮件来自 otp@verify.authifly.com 或您自己的已验证域名，SMS 和 WhatsApp 则以 Authifly 品牌发送。authifly.com 是一个公开页面，向收件人说明 Authifly 代表企业发送合法的一次性验证码。Bird 是您构建产品的平台；Authifly 是接收方看到的品牌。

您的用户看到的发送者：Authifly

您的终端用户将通过 Authifly（Bird 的验证品牌）接收验证码。在共享发送者模式下，OTP 邮件来自 otp@verify.authifly.com，SMS 消息中标注 Authifly 名称，确保验证码始终以统一身份送达，无需您自行运营。如果收件人收到意外的验证码，authifly.com 会向他们确认 Authifly 是代表企业发送合法一次性验证码的服务。Authifly 由 Bird B.V. 运营。

访问 authifly.com

验证服务与您的其他消息服务在同一平台上。

Verify 目前处于预览阶段。立即开始构建，或与我们沟通您所需的渠道、用量和定价方案。

立即开始联系我们

无需存储的验证 API。

从安装到用户验证，仅需两次调用

用您已熟悉的语言发送并验证验证码。

十项您无需自行构建的功能 ——当验证就是 API。

探索 Verify 平台

在发送和验证之间无需存储任何内容。

按国家路由即配置。

因为让用户登录的验证码不应该需要一张专属数据库表。

如果您已集成 SMS，就等于已集成 Verify。

Verify API 常见问题

您的用户看到的发送者：Authifly

验证服务与您的其他消息服务在同一平台上。

从一个渠道开始。准备好后，再添加其他渠道。

十项您无需自行构建的功能
——当验证就是 API。

从一个渠道开始。
准备好后，再添加其他渠道。