Sign inGet Started

从 Twilio 迁移 Verify

本页将 Twilio Verify v2 映射到 Bird Verify。请按顺序参考主迁移指南,并在步骤 1 和步骤 3 中使用这些映射。

Service 是没有对应概念的部分。Twilio 的地址格式为 POST https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications,Service 中保存了验证码长度、TTL、号码查询、固话处理和请求速率限制等配置。Bird 的地址格式为 POST /v1/verify/verifications,不含 service 路径段:这些设置属于你的工作区,而不是路径中的某个 ID。多个 Service ID 在一个工作区中没有对应机制,你也无法按请求选择不同的配置。

交给你的 agent

将以下内容粘贴到 Claude Code、Cursor 或 Codex 中。agent 会根据你的代码仓库逐步执行本页内容,使用它已有的任何 Bird 接口:已连接的 MCP 服务器,或已安装并登录的 CLI。

代码示例
I am moving a phone verification integration from Twilio Verify to Bird Verify. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/verify/migrate/twilio.md for the create, check and status mapping, and https://bird.com/docs/guides/verify/migrate.md for the order the steps go in.
3. Find and list my Twilio Verify usage in this repository before you change anything: the Verifications and VerificationCheck call sites, every Service SID they name and what each Service is configured with, and any place I read a verification status. Bird has no Service segment and no per-request configuration selection, so tell me if I use more than one Service and what differs between them.
4. Tell me early which of these I depend on. Bird Verify has no voice channel and no silent or network-based authentication. It generates the code itself and never returns it, so I cannot supply my own. It accepts `options.language` but no per-request template or message body. Bird can use an existing SMS Sender ID or a connected WhatsApp number with an approved authentication template, configured per channel or country rather than per request; tell me whether my current sender can be kept. Twilio's Service holds code length, TTL, lookup, landline handling and rate limits; on Bird those belong to the workspace rather than to an ID in the path, so tell me which of my Service settings have no home.
5. Configure my channels and destinations following https://bird.com/docs/guides/verify/countries.md and https://bird.com/docs/guides/verify/senders.md. While you are there, disable every country I do not actually verify into. An enabled destination I never send to is not reach, it is exposure to SMS pumping, so ask me which countries I serve rather than leaving the defaults.
6. Port the create and check calls using the mapping tables on the provider page, and move my status handling to Bird's events: https://bird.com/docs/guides/verify/sending-verifications.md and https://bird.com/docs/guides/verify/events.md.
7. Cut over at the create call, not all at once, because a code issued by Twilio Verify cannot be checked by Bird and a code issued by Bird cannot be checked by Twilio Verify. From the moment I say go, send every NEW verification to Bird, and keep routing each check to whichever provider issued that verification. Keep both paths live for one full code lifetime plus margin, then retire the old one. Tell me how you will decide which provider issued a given verification before you write any of it.
8. Test before any real traffic. Bird Verify has no simulated recipients, so do not look for a sandbox: the thing worth testing is the code arriving. Run the integration against a phone number and a mailbox I control, on each channel I enabled, and show me what arrived on each one.
9. Stop and ask me wherever a step needs a decision. Do not start routing new verifications to Bird until I have seen those test results and replied with the words cut over to Bird. Retiring the Twilio Verify path is a separate step: ask me again and wait for me to reply with the words retire the Twilio Verify path, and do not retire it while any code it issued could still be checked. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.

映射 create 调用

功能Twilio VerifyBird
接收方Toto.phone_number 或 to.email
渠道Channeloptions.channels,否则使用该国家/地区配置的顺序
验证码长度Service CodeLengthoptions.code_length,否则使用工作区默认值
验证码有效期Service TTL工作区的 Duration 设置
尝试次数限制Service max attempts工作区的 Maximum Retries 设置
关联Tagsmetadata
安全重试(无)Idempotency-Key 请求头
自定义验证码CustomCode无对应项
本地化Localeoptions.language
消息内容TemplateSid、CustomFriendlyName、ChannelConfiguration无逐请求对应项;在 Verify 配置中选择一个已审批的 WhatsApp 身份验证模板
按密钥限流RateLimits固定的平台防护限制
反欺诈控制RiskCheck、Fraud Guard、DeviceIp未在 API 上公开
SMS 自动填充AppHash无对应项
PSD2Amount、Payee无对应项

渠道也不是一一对应的:

Twilio ChannelBird
smssms
emailemail
whatsappwhatsapp
call无对应功能
sna、auto无对应功能
rcs无对应功能
(无)telegram,适用于在 Telegram 注册的号码

如果流程使用 call 作为无障碍回退方案,或使用 sna 和 auto 作为免验证码路径,你需要在确定日期之前重新规划。其余部分只是在 Countries 页面上调整渠道顺序,而非逐请求设置参数。

映射 check 调用

Twilio 的 POST /v2/Services/{ServiceSid}/VerificationCheck 接受 To 或 VerificationSid,加上 Code。Bird 的 POST /v1/verify/verifications/check 只需要接收方和验证码,因此 VerificationSid 路径以及你为其存储的列都可以移除。请提供与创建验证时完全相同的地址集。

返回结果的结构在最关键的地方有所不同:

  • Twilio 返回一个 status 字段;Bird 返回一个布尔值。 success: true 表示已验证。success: false 包含一个 reason,值为 incorrect_code、expired 或 attempts_exhausted,还有 attempts_remaining,因此你可能一直自行计数的 "how many tries left" 值会直接在响应中返回。
  • 两者在验证结束后都会进入 404 状态。 Twilio 在验证被批准、过期或用完尝试次数后删除验证记录;Bird 在任何终态下停止接受检查。请存储首次确定性结果,而不是反复检查。

转换状态

Twilio 状态Bird 状态Bird 原因
pendingpending无
approvedverified无
max_attempts_reachedfailedattempts_exhausted
expiredexpiredttl_elapsed
canceled无对应:验证不可取消

没有 update 端点,因此 Twilio 中从后端将验证强制设为 approved 或 canceled 的做法没有对应操作。验证在用户完成验证、用尽尝试次数或过期时结束。

迁移事件流

Twilio Verify 通过 Event Streams 报告活动:一个接收端加一个对验证状态事件的订阅,配置在 Verify API 之外。Bird 使用与所有其他渠道相同的 webhook 机制。订阅一个端点到你需要的事件类型,逐个指定:verify.verification.created、verify.verification.verified 和 verify.verification.failed 用于会话事件,verify.attempt.sent、verify.attempt.delivered 和 verify.attempt.undelivered 用于单条验证码投递。没有可以替代它们的通配符。按照 Standard Webhooks 验证签名。参见验证事件。

迁移仪表盘时需要关注两个维度。Twilio 的验证状态事件对应 Bird 的会话事件,Bird 的尝试事件则在同一会话上增加了逐次发送的投递结果,包括重新发送或渠道故障转移产生的发送。

切换

主指南中的切换规则是你需要围绕它来规划的核心:Twilio 签发的验证码无法由 Bird 来校验,因此在 create 调用处切换,并继续将 check 请求路由到签发该验证的提供方,直到最后一个 Twilio 验证码过期。

切换前检查发送者。你可以选择 Bird Verify 或 Authifly,使用你已验证的电子邮件域名,选择已有的 SMS Sender ID,或将你已连接的 WhatsApp 号码与已审批的身份验证模板配对。Bird 不会在发送者池中选择。如果你将 SMS Sender ID 保留为默认配置,Verify 仅在该 ID 不适用于目标地区时才回退到 Bird Verify;显式的国家/地区选择则不会回退。确认用户在每个国家/地区看到的内容,并在发生变化时更新客服脚本。

后续步骤