从 Telnyx 迁移 SMS
本页将 Telnyx 的 Messages API、messaging profile 和投递 webhook 映射到 Bird。请按顺序参照主迁移指南,并在步骤 3、4 和 5 中使用这些映射。
发送调用在所有供应商中与 Bird 最为接近:JSON、一个 bearer 密钥,以及相同的字段名。POST https://api.telnyx.com/v2/messages 接受 from、to 和 text,POST /v1/sms/messages 也一样。无法直接沿用的是 messaging profile。Telnyx 将它作为几乎所有功能的核心单元:发送号码池、webhook URL、退订范围和关键字配置。Bird 将这些拆分到发送者、webhook 订阅和屏蔽列表中。本次迁移的大部分工作就是拆解这个对象。
将以下内容交给你的代理
在你的编码代理中使用此简报。它从发现阶段开始,在任何生产变更之前生成一份可审核的迁移计划。
代码示例
Help me migrate my SMS integration from Telnyx 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 the Markdown guides at https://bird.com/docs/guides/sms/migrate/telnyx.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 Telnyx 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.映射发送调用
| 功能 | Telnyx | Bird |
|---|---|---|
| 收件人 | to | to(每次请求一个) |
| 发送者 | from 或 messaging_profile_id | from |
| 正文 | text | text |
| 意图 | (无) | category,自由文本时为必填项 |
| 投递报告 | profile 的 webhook URL | 订阅了以下投递事件的工作区 webhook |
| 往返上下文 | 自行存储,以 ID 为键 | metadata:任意 JSON,在每个事件中回传 |
| 可筛选标签 | (无) | tags:{name, value} 键值对 |
| 安全重试 | (无文档记录) | Idempotency-Key 请求头 |
| 媒体 | media_urls | 无对应项:media_urls 会被拒绝 |
移植注意事项:
- messaging profile ID 变为一个普通的发送者值。 Telnyx 通过 profile 在后台解析号码池及其发送规则。Bird 在 from 中直接接受发送者本身,因此每次发送时自行选择,或使用模板发送,它会为目标选择有效的发送者并拒绝 from。
- Messages API 上没有与 category 对应的内容。 针对每种消息类型决定它是 transactional、marketing、authentication 还是 service。身份验证流量尤其应明确标注,而不是留在营销默认值中。
- 单独审查重试语义。 Telnyx 的发送参考文档未记录幂等键,因此超时时只能靠猜测。从第一次移植开始就发送 Idempotency-Key 请求头。
迁移退订记录
这一步最容易出人意料,首先要算清的数字是你的列表会变成多少条屏蔽记录。
Telnyx 将退订限定在整个 messaging profile 范围内:订阅者向 profile 上的任何一个号码发送 STOP,就会被该 profile 上所有号码屏蔽,向其发送消息会返回错误 40300,"Blocked due to STOP message"。要为不同项目维护独立的退订列表,只能使用独立的 profile。
Bird 将屏蔽限定在发送者与订阅者的配对上。因此,一条 Telnyx 退订记录对应一个包含 12 个号码的 profile 时,会变成 12 条 Bird 屏蔽记录;包含 100 个号码的 profile 则变成 100 条。导入前先计算:乘数就是你从该 profile 迁移过来的发送者数量,它决定了导入是几百次循环还是数万次循环。
在所有相关发送者上保留 profile 级别的撤回。发送者级别的存储并不意味着可以用另一个号码恢复某个项目。检查工作区级别的偏好设置是否能准确反映用户的实际请求。
将通过 autoresp_configs 配置的自定义关键字和自动回复重建为 Bird 关键字规则。向已屏蔽的配对发送消息会在准入阶段被拒绝,返回 E12077 SMSRecipientSuppressed;下游退订是一个单独的 recipient_opted_out 投递结果。替换 Telnyx 错误 40300 时需处理这两条路径。
原因会叠加而非合并,这在流量运行后很重要:你以 manual 导入的配对如果随后发送了 STOP,会新增一条原因为 keyword_stop 的记录,消息将持续被阻止,直到该配对的所有记录都结束。恢复曾经导入的订阅者意味着需要同时移除两条记录。
转换投递状态
使用此表比较生命周期概念,而非机械地重命名事件。Bird 根据报告的状态和原因选择失败事件。被拒绝的 API 请求不会创建消息;接受后的拒绝可能产生 sms.rejected,包括运营商拒绝。缺少投递证据的消息保持未知状态。在标准化结果旁保留原始供应商状态和代码。
| 结果 | Telnyx | Bird |
|---|---|---|
| API 已接受消息 | queued | sms.accepted |
| 已交给运营商 | sent,在 message.sent 上 | sms.sent |
| 运营商确认投递 | delivered,在 message.finalized 上 | sms.delivered |
| 投递失败 | delivery_failed | sms.undelivered |
| 永久失败 | sending_failed | sms.failed |
| 请求在准入阶段被拒绝 | 请求错误 | HTTP 错误;无消息或事件 |
| 有效期窗口已过 | (无) | sms.expired |
事件结构变了,不只是名称。 Telnyx 发送一个 message.finalized webhook,在 status 字段中携带终态,因此你的处理程序在单个事件类型内部按值分支。Bird 改为发出不同的事件类型,你只订阅所需的类型,分支从代码移到了订阅中。这就是为什么上表左列同时列出事件和状态,而右列只列出事件。
名称之外还有两个机制发生了变化:
- 订阅替代了 profile 的 webhook URL。 Telnyx 将投递更新发送到 messaging profile 上的 URL,因此目标是每条消息发送所通过的 profile 的属性。Bird 将事件投递到你的工作区注册的端点,每个端点订阅它所需的事件类型,因此增加一个消费者只需增加一个订阅,而无需修改共享对象。
- Standard Webhooks 替代了 Telnyx 的签名方案。 Bird 发送按 Standard Webhooks 签名的 JSON;将验证替换为 Webhooks & events 中的方法。
只需注册一次端点,指定你的处理程序所需的事件类型:上述 sms.* 事件就是要订阅的列表,没有通配符可以代替它们。创建端点包含相关命令,以及首次调用时唯一需要注意的事项:保存响应中仅显示一次的签名密钥。
Bird 使用标准化的 error 代码报告失败,例如 invalid_destination、content_rejected、provider_unavailable 或 recipient_opted_out;完整列表在事件页面。将你的告警映射到这些代码。
正式切换
目标地址、发送者和流量爬坡与供应商无关,已在主迁移指南中说明。切换计划中有两项 Telnyx 特有事项:你的 10DLC 品牌和活动是通过 Telnyx 在 The Campaign Registry 注册的,不会自动变为 Bird 注册。在提交付费工作之前,确认适用的迁移或注册流程。你在 Telnyx 拥有的号码需要由客服安排携号转网,按其排期而非你的排期进行。
关于 Bird 端的要求,从注册 10DLC 开始:它说明了每个字段的含义、注册机构认可的实体类型,以及在创建品牌(即收费步骤)之前需要提供哪些信息的要求查询。
后续步骤
-
比较 Bird 与 Telnyx 的 SMS:产品评估和迁移注意事项
-
发送 SMS:你要迁移到的完整载荷
-
退订和关键字:各国关键字覆盖范围和屏蔽管理
-
SMS 事件:你的 webhook 处理程序要迁移到的事件词汇表
-
Webhooks & events:端点设置和 Standard Webhooks 验证
相关资源
继续查阅此主题的文档、指南和示例。资源为英文。