Sign inGet started

从 Twilio 迁移 SMS

本页将 Twilio 的 Programmable Messaging API、Messaging Services 和状态回调映射到 Bird。按顺序遵循主迁移指南,并在步骤 3、4 和 5 中使用这些映射。
整个迁移由两个差异决定。Twilio 的 POST /2010-04-01/Accounts/{AccountSid}/Messages.json 接受表单编码的 PascalCase 参数,使用 Account SID 和 Auth Token 进行身份验证;POST /v1/sms/messages 接受 JSON,使用 bearer API 密钥对区域主机进行身份验证。此外,Twilio Messaging Service 可以将发送方选择、退订处理和回调配置打包在一起。请将每种行为分别映射到 Bird 所有者;仅将 SID 重命名为发送方值并不能保留整个服务。

将此交给你的代理

在编码代理中使用此简报。它从发现阶段开始,在进行任何生产变更之前生成一份可审查的迁移计划。
代码示例
Help me migrate my SMS integration from Twilio to Bird.
1. Inspect this repository's sends, senders, callbacks, schedules, templates, opt-outs and tests. List the traffic and behavior that must survive the migration.
2. Read https://bird.com/docs/guides/sms/migrate/twilio.md and https://bird.com/docs/guides/sms/migrate.md. Use an existing authenticated Bird MCP or CLI connection. If neither is available, follow https://bird.com/docs/ai/set-up-your-agent.md. Discover the actual operations; do not invent commands or ask me to paste credentials into chat.
3. Prepare the code changes, sender/destination requirements, consent migration, webhook verification and rollout/rollback plan. Preserve the scope of each customer's preferences, including requests outside SMS replies. Separate API batches from audience broadcasts and preserve any behavior that has no direct endpoint equivalent.
4. Show me the exact affected resources, destinations, test volume and known costs before an action that sends messages, spends money, registers or changes a sender, or moves production traffic. Require explicit human authorization for each paid submission or production change. Name one-off 10DLC registration and resubmission fees before requesting approval. An existing explicit approval for that exact action is sufficient; broad migration approval is not. Simulated SMS destinations are billable and still require authorization.
5. If I am keeping Twilio numbers, prepare the human support port request and obtain authorization to send it. Read bird support-tickets create --help, then use the available CLI or MCP support operation with the reviewed number list and requirements. Return the ticket ID and follow the reply; support arranges the port on its own schedule, separately from the code cutover.
6. Run local and intercepted tests first. When authorized, perform the agreed bounded integration tests, inspect accepted and final outcomes separately, and report failures or uncertainty. Do not claim a delivery receipt proves reading or that request idempotency guarantees exactly-once delivery.
7. Keep production cutover and retiring the old provider as explicit steps in the approved rollout. Finish with the diff, evidence, unresolved requirements and the next action.

映射发送调用

功能TwilioBird
接收方Toto(每个请求一个)
发送方FromMessagingServiceSidfrom
正文Bodytext
内容模板ContentSid + ContentVariables需单独审查内容;Bird 系统模板并非 Twilio Content 的导入
意图(无)category,自由文本时必填
可筛选标签(无)tags: {name, value} 键值对
往返上下文自行存储,以 SID 为键metadata: 任意 JSON,在每个事件中回传
投递报告StatusCallback订阅了以下投递事件的工作区 webhook
字符转写SmartEncodedoptions.smart_encoding(默认 false
安全重试(Messages 无此功能)Idempotency-Key 请求头
定时发送ScheduleType + SendAt无对应功能:scheduled_at 会被拒绝
媒体MediaUrl无对应功能:media_urls 会被拒绝
有效期ValidityPeriod无对应功能:validity_period 会被拒绝
链接缩短ShortenUrls无对应功能
上述三个被拒绝的字段属于保留字段,用于回答 422 SMSUnsupportedFeature。定时发送和媒体处理暂时保留在原处。
迁移注意事项:
  • 单独处理 Messaging Service 的各项行为。 Twilio 在 SID 背后解析发送方池、粘性发送方和地理匹配。Bird 在 from 中直接接收发送方本身,因此需要逐次选择发送方,或使用模板发送,它会为目标选择有效的发送方并拒绝 from
  • 字符限制变为分段上限 对于 GSM-7 文本,长度结果相近,但失败方式不同:Bird 不会截断内容,超长正文会被拒绝并返回 422,而非被裁剪。
  • Messages API 上没有与 category 对应的内容。 根据消息类型决定它是 transactionalmarketingauthentication 还是 service。特别是身份验证流量,应明确标注为相应类型,而非保留在营销默认值中。
  • Twilio 的测试凭据映射到模拟目的地。 你已经在测试中使用的魔法号码(包括 +15005550006+15005550001)在这里也能产生合成结果,但有两个区别:没有单独的测试凭据,并且发送会被计费。具体结果列在主指南中。

迁移退订记录

Twilio 可以将退订限定在某个号码或 Messaging Service。一个服务级请求可以覆盖多个发送方。导入到 Bird 的发送方-订阅者屏蔽列表时,请保留该覆盖范围;如果确实需要工作区级别的退订,可使用相应的工作区偏好设置。
Twilio 的 Advanced Opt-Out 文档指出,被屏蔽号码的报告不会通过其 Console 或 REST API 暴露。请通过可用的支持流程请求导出,并与你自己的偏好记录、入站日志和支持请求进行核对。仅凭关键词日志可能不完整。
通过屏蔽工作流导入审查后的结果。手动屏蔽会为该配对阻止所有类别,因此请检查预期范围,避免无声地缩小或扩大范围。
Twilio 的 21610 表示接收方已退订。在 Bird 中,被屏蔽的配对在接纳阶段就会被拒绝,返回 E12077 SMSRecipientSuppressed,此时消息尚未创建。投递错误 recipient_opted_out 则报告的是下游退订。在停用现有处理程序之前,请检查 Bird 的关键词覆盖范围,并保留内置目录之外的退订机制。

转换投递状态

使用此表比较生命周期概念,而不是机械地重命名事件。Bird 根据报告的状态和原因选择失败事件。被拒绝的 API 请求不会创建消息;接受后的拒绝可能产生 sms.rejected,包括运营商拒绝。缺失的投递证据保持为未知。请在你的标准化结果旁边保留原始提供商状态和代码。
结果Twilio MessageStatusBird
API 已接受消息queued, acceptedsms.accepted
已移交运营商sending, sentsms.sent
运营商确认投递deliveredsms.delivered
运营商报告未投递undeliveredsms.undelivered
永久失败failedsms.failed
请求在接纳阶段被拒绝请求错误HTTP 错误;无消息或事件
有效期窗口已过(无)sms.expired
已定时或已取消scheduled, canceled暂无对应功能
三项机制随名称一起变化:
  • 端点取代回调 URL。 Twilio 将回调发送到消息或 Messaging Service 上的 StatusCallback。Bird 投递到你的工作区注册的端点,每个端点订阅它所需的事件类型,因此新增消费者只需新增订阅,而非重新部署。
  • 签名的 JSON 取代表单编码的 POST 请求。 Twilio 发送带有 X-Twilio-Signature 请求头的 application/x-www-form-urlencoded;Bird 发送按照 Standard Webhooks 签名的 JSON。将验证方式替换为 Webhooks & events 中的方法。
  • 入站消息以事件形式到达。 Twilio 的按号码 "A message comes in" webhook 期望一个 TwiML 响应,你的应用可以用它来自动回复。Bird 向与其他所有内容相同的订阅端点发出 sms.received,且没有可用于发送回复的响应体:请调用发送端点来回复,或让关键词规则为你回复。
注册端点时只需一次,指定处理程序所需的事件类型:上表中的 sms.* 事件就是要订阅的列表,没有通配符可以代替它们。创建端点包含相关命令、为什么必须逐项列举目录,以及首次调用时最重要的一件事:保存响应中仅显示一次的签名密钥。
Twilio 的数字错误码没有一一对应的映射。Bird 使用标准化的 error 代码报告失败,例如 invalid_destinationcontent_rejectedprovider_unavailablerecipient_opted_out;完整列表在事件页面。请将你的告警映射到这些代码,而不是 30000 系列的代码。

切换

目的地发送方流量递增与提供商无关,在主指南中有介绍。两个 Twilio 特定事项需要纳入切换计划:你的 10DLC 品牌和活动通过 Twilio 在 The Campaign Registry 注册,不会自动成为 Bird 注册。在提交付费工作之前,请确认适用的迁移或注册流程。你在 Twilio 拥有的号码需要由支持团队安排的号码移植,按他们的时间表进行,而非你的。
关于 Bird 侧的要求,请从注册 10DLC 开始:它介绍了每个字段的含义、注册机构认可的实体类型,以及在创建品牌(即收费步骤)之前告诉你需要提供什么的需求调用。

后续步骤

相关资源

继续查阅此主题的文档、指南和示例。资源为英文。