Sign inGet started

从 Bandwidth 迁移 SMS

本页将 Bandwidth 的 Messages API、Applications 和消息回调映射到 Bird。按顺序参照主迁移指南,并在第 3、4、5 步使用这些映射。
两个差异贯穿整个迁移。Bandwidth 将通道分布在两个主机上:发送位于消息主机的账户路径下,通过 HTTP Basic 认证;而 10DLC 注册位于主 API 主机上。Bird 将发送、注册和投递事件统一在一个基础 URL 和一个 bearer 密钥下。每次 Bandwidth 发送时携带的 applicationId 承载回调配置;Bird 没有对应对象,因为回调是工作区订阅而非消息的属性。

将以下内容交给你的 agent

在你的编码 agent 中使用这份简报。它从发现阶段开始,在进行任何生产变更之前生成可供审查的迁移计划。
代码示例
Help me migrate my SMS integration from Bandwidth 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/bandwidth.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 Bandwidth 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.

映射发送调用

功能BandwidthBird
接收方to(数组)to(每个请求一个)
发送方fromfrom
消息体texttext
回调路由applicationId订阅了下方投递事件的工作区 webhook
意图(无)category,自由文本必填
自由格式标签tag(单个字符串)metadata;仅在能命名时使用 tags
往返上下文自有存储,以 ID 为键metadata:任意 JSON,在每个事件中回传
投递优先级priority无对应项
安全重试(其规范中无此项)Idempotency-Key 请求头
媒体media无对应项:media_urls 会被拒绝
迁移说明:
  • to 从数组折叠为单个接收方。 Bandwidth 接受列表;Bird 每个请求发送一条消息。用循环替代数组,每次调用可以携带自己的 Idempotency-Key
  • applicationId 被移除而非迁移。 它的作用是告诉 Bandwidth 向哪里发送回调。在 Bird 上这是工作区订阅,因此发送时无需指定它。
  • tagtags 不是同一个字段。 Bandwidth 的 tag 是一个自由格式字符串;Bird 的 tags{name, value} 键值对,用于查询维度。单个不透明字符串通常更适合放在 metadata 中。
  • Messages API 中没有与 category 对应的内容。 根据消息类型判断它是 transactionalmarketingauthentication 还是 service

迁移退订记录

没有可导出的列表,这本身就是结论,而非本指南的遗漏。
除免费号码外,Bandwidth 不会为你维护订阅或退订列表。他们自己的指南明确指出:遵守指令和维护列表的责任在于客户。免费号码是例外,STOP 及其变体在网络层强制执行,不受你的配置影响;长号码和短号码则没有此类处理。
因此在本次迁移中,权威列表已经在你手中。它可能是一张表、联系人记录上的一个标志,或者发送路径在调用 API 之前执行的一项检查。首要任务是确定哪个来源具有权威性,而不是向任何人请求导出。你自己的入站消息日志是备选方案:部分退订源自入站消息,其余则来自客服、表单或其他偏好渠道。
然后通过屏蔽流程导入。一条 Bird 屏蔽记录是一个发送方-订阅者对,因此你在三个发送方上停止的一个订阅者对应三条记录。读取和管理屏蔽记录包含操作命令,并说明了手动屏蔽为何会阻止所有类别(包括事务性消息)。
在切换后确定谁拥有该列表,因为这正是你获得新能力但也容易失控的地方。 Bird 根据各国自有的关键词目录自动响应停止关键词,所以一旦你在此平台发送消息,平台就会为你维护屏蔽记录:订阅者发送 STOP 时会自动生成原因为 keyword_stop 的记录,无需你的应用程序执行任何操作。如果你的代码继续维护并执行自己的列表,两边就会产生偏差,常见症状是订阅者在一侧恢复订阅但另一侧没有。请明确受众偏好的所有者,并有意识地同步相关变更。仅靠发送方屏蔽不能覆盖工作区范围的偏好或关键词目录之外的请求。原因是叠加而非合并的,因此你以 manual 导入的一对如果后来发送了 STOP,则会持有两条记录,消息在两条记录都结束之前保持停止状态。

转换投递状态

使用此表对比生命周期概念,而非机械地重命名事件。Bird 根据上报的状态和原因选择失败事件。被拒绝的 API 请求不会创建消息;接受后的拒绝可能产生 sms.rejected,包括运营商拒绝。缺少投递证据时状态保持未知。在你的归一化结果旁保留原始提供商状态和代码。
结果Bandwidth 回调类型Bird
API 已接受消息202 响应,无事件sms.accepted
已交给运营商message-sentsms.sent
运营商确认已送达message-deliveredsms.delivered
未到达运营商message-failedsms.rejected
运营商拒绝message-failedsms.failed
运营商报告未送达message-failedsms.undelivered
运营商放弃message-failedsms.expired
请求在准入时被拒绝请求错误HTTP 错误;无消息或事件
该表中有两点值得采取行动,而非一读而过。
围绕 Bird 的消息记录和事件时间戳重建终态处理逻辑。Webhook 投递可能重复或乱序到达;你的消费者不能假设只收到一次最终回调。被拒绝状态和投递失败状态即使都来自下游,也可能选择不同的 Bird 事件。
message-sending 没有对应行,因为它仅限 MMS;message-read 仅限 RBM;两者都不会为 SMS 触发。
两项机制随名称一起改变:
  • 订阅替代了 Application。 Bandwidth 根据消息中指定的 applicationId 路由回调。Bird 投递到工作区注册的端点,每个端点订阅其所需的事件类型,因此新增消费者是新增订阅,而非新增 Application 并重新部署。
  • Standard Webhooks 替代了其回调认证机制。 Bird 发送按 Standard Webhooks 签名的 JSON;将原有验证替换为 Webhooks & events 中的方法。
只需注册一次端点,指定处理程序所需的事件类型:上面的 sms.* 事件就是要订阅的列表,没有可替代它们的通配符。创建端点包含操作命令,以及首次调用时唯一需要注意的事项:保存响应中仅显示一次的签名密钥。

执行切换

目的地发送方流量阶梯与提供商无关,已在主指南中介绍。有两个 Bandwidth 特有事项需加入切换计划:你的 10DLC 品牌和活动是通过 Bandwidth 在 The Campaign Registry 注册的,不会自动变为 Bird 注册。在提交付费工作之前,确认适用的迁移或注册流程。你在 Bandwidth 拥有的号码需要由支持团队安排号码移植,按其排期而非你的排期进行。
关于 Bird 端的要求,请从注册 10DLC 开始:它涵盖每个字段的含义、注册机构认可的实体类型,以及在创建品牌(即收费步骤)之前告诉你需要提供哪些内容的需求调用。

后续步骤

相关资源

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