通道可用性、发送方规则和法规因国家/地区而异，要做到正确需要多年积累。Bird 将其作为按国家/地区的基础配置提供：哪些通道在哪里可用、允许使用哪些发送方，以及合理的验证码默认值。您的设置叠加在其上。您只需为某个国家/地区更改一项内容；未更改的部分自动回退到下一层。这就是作为一等 API 资源的按国家/地区路由——大多数验证 API 无法提供的控制能力。
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();
您继承 Bird 的默认值，然后在此基础上构建。
Bird Verify API 上的每次验证都通过级联机制解析其设置。最底层是 Bird 基于多年电子邮件和 SMS 运营经验维护的按国家/地区基础配置，因此在您进行任何配置之前，验证请求已经能在每个国家/地区合理路由。您的配置和按国家/地区的覆盖设置叠加在其之上，而单次请求的选项可以微调单个调用。您永远不必从零开始，只需掌控您真正想做的决策。
值级联机制。
设置了值的最高层级优先生效；未设置的部分回退到下一层。
- 01
单次请求选项。
创建调用中的字段（验证码长度、通道偏好、语言区域）仅对该次验证生效。最轻量、最局部的覆盖。
- 02
您的按国家/地区覆盖。
为某个国家/地区更改通道顺序或发送方。覆盖以合并方式生效：仅修改您设置的字段，该国家/地区的其余部分仍从下层继承。
- 03
您的配置默认值。
您的应用级方案和验证码规则：渠道顺序、验证码长度、有效期和尝试次数——适用于您未设置国家/地区覆盖的所有场景。
- 04
Bird 的按国家/地区基础配置。
最底层：Bird 基于大规模邮件和 SMS 运营经验得出的按国家/地区默认值。未设置的部分都会回退到此层，因此验证始终能解析为合理的方案。
覆盖某个国家/地区，其余继承。
只需设置一次方案，然后仅调整需要特殊处理的国家/地区。这里巴西优先使用 WhatsApp，其次是 SMS；其他所有国家/地区继续回退到您的默认值和 Bird 的基础配置。
// Your app-wide default plan.
await bird.verify.verifications.configurations.update("vfc_login", {
channels: [
{ channel: "email", state: "enabled" },
{ channel: "sms", state: "enabled" },
],
}).safe();
// Override one country; the rest inherits.
await bird.verify.verifications.configurations.countries.upsert("vfc_login", "BR", {
channels: [
{ channel: "whatsapp", state: "enabled" },
{ channel: "sms", state: "enabled" },
],
}).safe();
验证解析的结果。
在此配置下，巴西号码通过级联解析。BR 覆盖将通道排序为先 WhatsApp 后 SMS，两者均可用，验证会返回其将使用的有序方案及带类型的 vrf_ id。
const { data } = await bird.verify.verifications.create({
configuration_id: "vfc_login",
to: { phone_number: "+5511998765432" }, // Brazil
}).safe();
// Resolved through the cascade + availability/kill-switch ceilings:
// {
// id: "vrf_01k2m9q8e7fh3v0b7m4d2a9xzt",
// status: "pending",
// channels: [{ channel: "whatsapp" }, { channel: "sms" }],
// last_channel: "whatsapp"
// }
级联之上有两道上限。
级联决定默认值。两道门控决定允许范围。它们对解析后的方案设置上限，而非提供可向下传递的值：
按国家/地区的可用性。您只能启用 Bird 在该国家/地区实际提供的渠道。启用一个我们在当地不支持的渠道不会生效，但也不会静默失败：可用性取交集，而非覆盖。
全局紧急开关。当服务提供商出现故障时，Bird 可以一次性在所有地区关闭某个通道。您的配置不受影响；解析后的方案会自动回退到下一个通道，开关恢复后即自动复原。
您配置的路由，而非您提交的工单。
每次验证独立解析，随响应返回。
- 01
按号码确定的国家/地区路由。
国家/地区根据收件人的 E.164 号码自动推导，无需您传入。为某个国家/地区设置路由后，它将覆盖该地区的渠道顺序和发送者。
- 02
开启和关闭通道。
每个通道都有启用/禁用状态，因此您可以为某个国家/地区关闭某个通道，而不影响其在方案中的位置。
- 03
解析后的方案随响应返回。
每次验证都会报告其解析的有序通道列表，因此级联的决策结果一目了然。
- 04
自动故障转移正在推出中。
基于投递状态的方案推进（当某个通道未送达时自动尝试下一个）正随投递状态功能逐步推出。方案已在当前版本中解析并返回。