从其他服务商迁移 SMS

1. 启用目的地国家
2. 设置发送方
3. 映射发送调用到 POST /v1/sms/messages
4. 迁移退订列表
5. 将投递报告切换到 webhook
6. 在正式切换前对模拟目的地进行测试

1. 启用目的地国家

2. 设置发送方

• 字母数字发送方 ID 在 SMS > Senders 下自行创建。如果目的地国家要求注册发送方 ID，请在该处提交注册并等待批准后再路由流量。
• 通过本地长号码发送的美国商业流量需要相应的 10DLC 品牌和活动，在 SMS > 10DLC 下设置，而免费号码和专用短代码有各自的验证或申请流程。美国完全不接受字母数字发送方 ID，因此在其他地方通用的欧洲发送方 ID 在美国没有对应方案。
• 号码通过 Numbers 工作流获取，可用性和托管配置取决于号码类型和目的地。查看 SMS numbers 了解正确的获取路径；添加字母数字发送方不会获取号码。
• 保留你当前的号码不支持自助操作：Bird 没有你可以从控制台发起的号码转入流程。如果你的订阅者会回复你当前拥有的号码，请在安排切换日期之前联系支持团队发起号码转入，并将号码转入和代码变更作为两个独立事件来规划。

3. 映射发送调用

• 每个请求只有一个收件人。 Bird 没有收件人数组。如果你当前的服务商将一次调用扇出到多个号码，这里需要改为每个收件人一次调用，或在一个请求中使用一个批量发送独立消息。
• 自由文本中必须指定 category，可选值为 transactional、marketing、authentication 或 service。大多数服务商从活动或发送方推断意图；这里你需要逐条消息声明。如果目的地国家要求注册发送方，该注册是针对特定类别批准的，超出该类别的发送会被 422 SenderCategoryNotPermitted 拒绝。注意，发送方的 active 状态无法提前告知这一点，因为它的报告不涉及任何类别；请改为查阅各国要求。在移植时就设置正确，而不是将所有内容默认为同一个值。
• 消息正文受分段上限限制，Bird 不会截断。 过长的正文会被 422 拒绝。非 GSM-7 字符会使每个分段的容量减少一半以上，因此如果你当前的服务商静默地将弯引号和破折号转写为基本字符，请设置 options.smart_encoding 以保持你习惯的分段计数。该选项默认关闭，因为它会修改你编写的正文。
• 使用 tags 作为筛选维度，使用 metadata 存放上下文信息。 标签是 {name, value} 键值对，可用于筛选和分析切片；元数据是任意的 JSON，由 Bird 存储、在读取时返回，并在每个 webhook 事件中回传。旧服务商的单个客户端引用字段通常映射到 metadata。
• 单条发送的定时调度和出站 MMS 需要单独规划。 scheduled_at、media_urls、validity_period 和每收件人的 personalization 是保留字段，会被 422 SMSUnsupportedFeature 拒绝。这部分集成不随其余内容一起迁移：在你自己的队列中保留定时发送，并在预定提交时间调用发送端点。对于受众活动，请单独评估 Broadcasts；广播不是端点字段的简单重命名。
• 使用 Idempotency-Key 进行有限次重试。 为每条逻辑消息发送唯一的密钥，并在三小时重放窗口内对相同请求的重试复用该密钥。重放可减少重复请求，但不是精确一次投递保证。参阅幂等性。

4. 迁移退订列表

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

• 发送方特定的抑制要求两端都填写。 工作区范围的退订属于单独的偏好所有者。该调用是幂等的：201 记录一条新的抑制，200 返回已存在的手动抑制，因此重新运行未完成的导入是安全的。
• 导入的配对会获得 reason: manual，这会阻止所有类别包括事务性消息。 这比 Bird 根据停止关键词自行记录的抑制更严格。如果订阅者仅退订了营销类消息，请慎重决定是否导入该配对。

5. 将投递报告切换到 webhook

• 投递使用 Standard Webhooks 签名，通过 webhook-id、webhook-timestamp 和 webhook-signature 请求头，对 {id}.{timestamp}.{raw body} 进行 HMAC-SHA256 签名。使用自有签名方案的服务商需要替换验签逻辑；具体方法在 Webhooks & events 中。
• 投递是至少一次且无序的。 使用 webhook-id 去重，按载荷中的 timestamp 排序，切勿按到达顺序排序。

6. 对模拟目的地进行测试

• 这些是美国号码，因此必须在 Destinations 下启用美国，并且 from 必须是对美国有效的发送方。字母数字发送方 ID 在美国会被拒绝。
• 模拟发送会按目的地的正常费率计费。 虽然不会到达真实手机，但钱包扣费是真实的，因此请控制冒烟测试的规模。
• 结果完全由目的地决定。没有单独的测试凭据，也没有需要关闭的测试模式。

从特定服务商迁移

• Twilio：表单编码的 PascalCase 迁移到 JSON，Messaging Services 迁移到发送方，StatusCallback 迁移到订阅式 webhook
• Plivo：src 和 dst 迁移到 from 和 to，Powerpacks 迁移到发送方，DND 配对迁移到抑制
• Telnyx：与 Bird 最接近的发送方式，messaging profiles 拆分为发送方和订阅，profile 级别的退订迁移到配对
• Bandwidth：两个主机合并为一个，applicationId 回调迁移到工作区 webhook，退订列表由你自己的应用已持有
• Sinch：批量发送迁移到单条发送，body 迁移到 text，群组成员关系重建为抑制
• Infobip：三层载荷扁平化，每账户 base URL 迁移到区域主机，Blocklist 展开为配对
• Bird Connectivity Platform：rest.messagebird.com API、originator 和 recipients 迁移到 from 和 to，reportUrl GET 回调迁移到签名 webhook

后续步骤

• 比较 SMS 服务商：评估产品工作流和迁移注意事项
• 发送 SMS：完整的发送载荷、发送方、分段以及异步 202 模型
• 退订与关键词：Bird 为你自动回复的内容，以及如何管理抑制
• SMS events：事件词汇表和每个事件的载荷
• Webhooks & events：端点设置、签名验证、重试和重放