从 Sinch 迁移 SMS

本页将 Sinch 的 SMS API、群组和投递报告映射到 Bird。按照主迁移指南的顺序操作，在第 3、4 和 5 步使用这些映射。

两个结构性差异决定了迁移的难度，二者的成本都高于字段重命名。Sinch 在 URL 路径中通过 service plan 标识发送，并以批次形式发送，因此向一个人发一条消息仍然是数组；Bird 的 POST /v1/sms/messages 在您的区域主机上接受单个收件人，使用 bearer 密钥且无 plan 路径段。此外，您无法跳过的美国注册位于与发送不同的主机上，使用不同的凭据体系，因此同时访问 Sinch 两个功能的代码库实际上是在访问两个地方。

将此交给您的代理

在您的编程代理中使用此简报。它从发现阶段开始，在任何生产变更之前生成可供审查的迁移计划。

代码示例

Help me migrate my SMS integration from Sinch 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/sinch.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 Sinch 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.

映射发送调用

功能	Sinch	Bird
收件人	to（数组，或群组 ID）	to（每次请求一个）
发送方	from	from
正文	body	text
账户路由	service plan，在 URL 路径中	bearer 密钥；无路径段
意图	（无）	category，自由文本必填
投递报告	delivery_report + callback_url，按批次	工作区 webhook；无逐条发送控制
关联	client_reference	metadata，在每个事件中回传
可过滤标签	（无）	tags: {name, value} 键值对
安全重试	（无文档记录）	Idempotency-Key 请求头
闪信	flash_message	无对应功能

迁移注意事项：

刻意选择单条发送、批量发送还是群发。 to 在 Sinch 中是数组，在这里是单个号码，因此请使用单条发送或批量端点发送最多 100 条独立消息。面向受众的营销活动属于群发工作流。指定了群组的批次需要先解析成员关系；参阅退订部分，因为这是同一个问题。
body 变为 text。 这是唯一一个需要在每个调用点修改的重命名。
client_reference 不是幂等键。 Sinch 将其定义为附加到批次投递报告上的标识符，因此它只起关联作用，不能去重。如果您之前依赖它来使重试安全，那并没有生效；Idempotency-Key 才是这里实现该功能的方式。
没有字段对应 category。 按消息类型决定它属于 transactional、marketing、authentication 还是 service。

迁移退订记录

Sinch 记录谁已订阅，而 Bird 需要知道谁已退订。 这种反转就是工作量所在。

Sinch 以群组方式管理收件人，群组可以通过关键词触发器自动更新，因此发送 STOP 的订阅者会被移出群组，发送 SUBSCRIBE 的订阅者会被加入群组。因此，退订被编码为列表中的缺席而非存在，而缺席是无法导出的：群组中缺少某个号码，可能是已退订，可能从未加入，也可能在六个月前被某次导入移除。

因此应重建而非导出。您自己的入站消息日志才是可靠来源，因为部分退订始于入站消息，而其他退订来自客服、表单或其他偏好渠道，这些消息无论群组成员关系现在怎样都存在。如果您在群组之外另行维护了退订标记，该标记比成员关系更可靠。将重建后的列表导入抑制流程，并在导入前将列表交给账户负责人审核：此处的错误条目会静默阻止您原本打算发送的消息。

Bird 的抑制记录是一对发送方与订阅者的组合，因此对三个发送方停止同一订阅者就是三条记录。读取和管理抑制记录包含具体命令，以及手动抑制为何会阻止所有类别（包括事务性消息）的原因。

迁移完成后，Bird 会根据自己按国家维护的关键词目录自动响应停止关键词，因此群组自动更新行为没有需要重建的对应功能：订阅者发送 STOP 时会自动产生抑制记录，无需您的应用做任何事。原因是叠加而非合并的，因此您以 manual 导入的配对如果之后发送了 STOP，则持有两条记录，消息在两条记录都结束之前保持停止。

转换投递状态

使用此表比较生命周期概念，而不是机械地重命名事件。Bird 根据报告的状态和原因选择失败事件。被拒绝的 API 请求不会创建消息；接受后的拒绝可能产生 sms.rejected，包括运营商拒绝。缺少投递证据的消息保持未知状态。将原始提供商状态和代码与您的标准化结果一起保留。

Sinch 的投递报告参考文档包含 queued、dispatched、delivered 和几种不同的最终失败状态。转换报告时，保留收件人级别的代码和状态。

Sinch 概念	Bird 集成决策
Queued / Dispatched	使用 sms.accepted 和 sms.sent 分别跟踪接受和运营商提交。
Delivered	通过 sms.delivered 记录网络结果；它不能证明已阅读。
Failed / Rejected / Deleted	检查报告的原因。Bird 的失败事件不是通过简单的名称替换来选择的。
Aborted / Expired / Cancelled	保留原因和阶段。Bird 的单条发送 API 没有调度或有效期计时器来重建这些控制。
Unknown	保持结果为不确定；不要将缺少可解读回执视为已投递。

Bird 的 sms.expired 跟随运营商的过期报告。请将您现有的过期和取消行为与该事件分开审查，而不是将每个超时都映射到它。

还需注意，中间状态只在批次请求了 per_recipient 报告时才会上报，这也是下面要改变的内容之一。

您将失去逐条发送的投递报告控制，这值得明确说明。 Sinch 的批次可以选择自己的报告粒度，并可为该次发送单独覆盖 service plan 的回调 URL。Bird 不具备这两项能力：报告是工作区级别的订阅，每个已订阅的事件都会被投递，且没有逐条消息的覆盖选项。如果您之前使用 delivery_report 来使高频营销活动保持静默，该过滤逻辑需移入您的处理程序。如果您之前将某个营销活动的报告路由到不同的端点，则变为一个端点加一个分支，或第二个订阅。

只需注册一次端点，指定处理程序所需的事件类型：上述 sms.* 事件就是要订阅的列表，没有可以替代它们的通配符。Bird 按照 Standard Webhooks 规范发送签名的 JSON；创建端点包含具体命令，以及首次调用时唯一要做对的事：存储响应中仅显示一次的签名密钥。

Bird 使用标准化的 error 代码报告失败，例如 invalid_destination、content_rejected、provider_unavailable 或 recipient_opted_out；完整列表在事件页面。

正式切换

目的地、发送方和流量爬坡是与提供商无关的内容，已在主迁移指南中介绍。有两项 Sinch 特有的内容需要列入切换计划。

您的 10DLC 品牌和营销活动是通过 Sinch 在 The Campaign Registry 注册的，不会自动变成 Bird 的注册。在提交付费工作之前，请确认适用的迁移或注册流程。这也是集成得到简化的地方。 在 Sinch 上，注册 API 位于与发送不同的主机上，使用项目凭据而非 service plan 令牌，并且 Sinch 自己的文档说明 HTTP Basic 仅供测试用途且受到严格的请求速率限制，因此生产环境集成需要为其构建 OAuth 令牌流程。在 Bird 上，/v1/sms/10dlc/* 和 /v1/sms/messages 在同一个基础 URL 和同一个密钥下，因此该令牌生命周期是被淘汰而非迁移。从注册 10DLC 开始，其中介绍了每个字段的含义，以及在创建品牌（即收费步骤）之前需要调用的 requirements 接口来确定需要提供哪些信息。

您在 Sinch 拥有的号码需要由技术支持安排号码携转，按照他们的时间表而非您的。

后续步骤

比较 Bird 和 Sinch 的 SMS：产品评估和迁移注意事项
发送 SMS：您要迁移到的完整载荷
退订和关键词：按国家的关键词覆盖范围和抑制管理
SMS 事件：您的报告处理程序要迁移到的事件词汇表
Webhooks 与事件：端点设置和 Standard Webhooks 验签