Sign inGet started

从 Plivo 迁移 SMS

本页将 Plivo 的 Message API、Powerpack 和投递回调映射到 Bird。按顺序遵循主迁移指南,并在步骤 3、4 和 5 中使用这些映射。
发送是最简单的部分。两者都接收字段名为小写的 JSON,且都将 10DLC 注册放在发送旁边而非单独的主机上。有两点不同。Plivo 的 POST https://api.plivo.com/v1/Account/{auth_id}/Message/ 通过 Auth ID 和 Auth Token 使用 HTTP Basic 进行身份验证;POST /v1/sms/messages 使用 bearer API 密钥对接你的区域主机,路径中没有 account 段。此外,Plivo 的 Powerpack 将号码池、粘性发送方行为和退订状态捆绑为一个对象;Bird 将它们分散到发送方、屏蔽和关键词规则中,因此无需以 Powerpack 的形式重建任何内容。

将此交给你的 Agent

将此摘要交给你的编码 Agent 使用。它从发现阶段开始,在进行任何生产变更之前生成可审查的迁移计划。
代码示例
Help me migrate my SMS integration from Plivo 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/plivo.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 Plivo 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.

映射发送调用

功能PlivoBird
收件人dstto(每次请求一个)
发送方srcpowerpack_uuidfrom
正文texttext
通道选择器type: smsmmswhatsapp端点本身;/v1/sms/messages 为 SMS
意图(无)category,自由文本必填
投递报告url + method,按消息工作区 webhook;仅 JSON POST,见下文
往返上下文你自己的存储,以 UUID 为键metadata:任意 JSON,在每个事件中回传
可过滤标签(无)tags{name, value}
安全重试(无文档记录)Idempotency-Key 请求头
媒体media_urls无对应项:media_urls 会被拒绝
迁移注意事项:
  • Powerpack UUID 变为普通的发送方值。 Plivo 在 UUID 背后解析号码池、粘性发送方和本地呈现。Bird 在 from 中直接接收发送方本身,因此逐次发送时自行选择,或使用模板发送,它会为目标选择有效的发送方并拒绝 from
  • type 没有对应项,因为端点本身就承载了它。 Plivo 逐请求选择通道;Bird 的 SMS、WhatsApp 以及其他通道是独立的端点。在运行时切换 type 的代码需要拆分为对不同端点的调用。
  • Message API 上没有与 category 对应的字段。 根据消息类型决定它是 transactionalmarketingauthentication 还是 service。尤其是身份验证流量应明确标记,而不是留在 marketing 默认值中。
  • 单独审查重试语义。 Plivo 的发送参考文档未记录幂等键或去重机制,因此超时时你只能猜测。从第一次迁移开始就发送 Idempotency-Key 请求头,以在三小时重放窗口内降低重复请求的风险;这不是精确一次投递保证。

迁移退订记录

Plivo 的 DND 服务在目标号码回复退订关键词后,阻止从一个 Plivo 号码向该目标发送出站消息。被阻止的发送会返回带有 Plivo 错误码 200 的标记,这是它们的消息错误码之一,而非 HTTP 状态码,尽管看起来很像。这种配对方式也正是 Bird 屏蔽的工作原理:一个发送方和一个订阅者,因此导入的范围必须覆盖该用户请求中包含的每个发送方和项目。
有一点会扩展,这也是导入前需要先计数的原因。 在美国 10DLC 活动中,Plivo 将来自任何一个号码的退订视为对该活动关联的所有号码的退订。Bird 存储的是配对,因此一个退订了四号码活动的订阅者会变成四条屏蔽记录而非一条。在开始之前先计算你的列表会产生多少配对,因为这决定了导入是几十次循环还是几千次。
导出列表需要通过控制台导出而非 API 调用:在 Plivo 控制台中筛选号码,选中它们,然后从 Choose Action 菜单使用 Export CSV。通过屏蔽循环导入结果。读取和管理屏蔽记录包含相关命令,以及手动屏蔽会阻止包括事务性在内的所有类别的原因。
Bird 通过其国家/地区特定目录处理受支持的停止关键词。向已屏蔽配对发送消息会在准入时被拒绝,返回 E12077 SMSRecipientSuppressed。运营商报告的退订是一个单独的 recipient_opted_out 投递结果。将 Plivo 错误码 200 的处理替换为相应的准入和投递路径,并将任何自定义回复重建为关键词规则
流量运行后这一点再次变得重要。原因是叠加而非合并的:一个以 manual 导入的配对如果随后发送了 STOP,会新增一条原因为 keyword_stop 的记录,消息将保持阻止状态直到该配对的所有记录都已结束。因此恢复你曾导入的订阅者意味着移除两条记录,而仅清除关键词记录的恢复操作看起来成功了但实际不会改变任何东西。

转换投递状态

使用此表比较生命周期概念,而非机械地重命名事件。Bird 根据报告的状态和原因选择失败事件。被拒绝的 API 请求不会创建消息;接受后的拒绝可能产生 sms.rejected,包括运营商拒绝。缺少投递证据的消息保持为未知。保留原始提供商状态和代码,与你归一化的结果一起保存。
结果Plivo message_stateBird
API 已接受消息queuedsms.accepted
已移交运营商sentsms.sent
运营商确认已投递deliveredsms.delivered
运营商报告未投递undeliveredsms.undelivered
永久失败failedsms.failed
发送前被拒绝rejectedsms.rejected
有效窗口已过期(无)sms.expired
除了名称变化外,还有两项机制发生了改变:
  • 端点取代了按消息的回调 URL。 Plivo 在每次发送时接收一个 url,因此目标由编写调用的人选定。Bird 投递到你的工作区注册的端点,每个端点订阅其所需的事件类型,因此新增消费者意味着新增订阅,而非在每个调用处修改。
  • 签名的 JSON 投递取代了 GET 回调(如果你之前选择了这种方式)。 Plivo 的 method 为投递报告选择 GETPOST;Bird POST 一个 JSON 事件且不提供 GET。如果你设置了 method=GET,你的处理程序从查询字符串参数中读取结果,该处理程序需要重写而非重新注册。同样的情况也适用于隔壁指南的 Connectivity Platform 路径。
  • 一种签名方案取代了三个请求头。 Plivo 使用 X-Plivo-Signature-V2X-Plivo-Signature-Ma-V2X-Plivo-Signature-V2-Nonce 签署回调。Bird 发送按 Standard Webhooks 签名的 JSON,因此验证器是替换而非调整:将其换成 Webhooks 与事件中的方法。
注册端点时只需一次,指定你的处理程序所需的事件类型:上面的 sms.* 事件就是要订阅的列表,没有通配符可以代替它们。创建端点包含相关命令,以及首次调用时需要做对的一件事:保存响应中仅显示一次的签名密钥。
Plivo 的数字 error_code 值没有一一对应的映射。Bird 使用标准化的 error 代码报告失败,例如 invalid_destinationcontent_rejectedprovider_unavailablerecipient_opted_out;完整列表在事件页面上。将你的告警映射到这些代码。

切换

目标号码发送方流量爬坡与提供商无关,已在主指南中涵盖。有两项 Plivo 特有的事项需要纳入切换计划。
你的 10DLC 品牌和活动是通过 Plivo 向 The Campaign Registry 注册的,不会自动成为 Bird 注册。在提交付费工作之前,确认适用的迁移或注册流程。这里的链路更短。 Plivo 先注册一个 profile,然后在其下注册一个 brand,归属于 /v1/Account/{auth_id}/10dlc/;Bird 没有 profile 对象,因此 Plivo 保存在 profile 上的业务详情直接提供在 brand 本身上。从注册 10DLC 开始:它涵盖了每个字段的含义、注册机构认可的实体类型,以及在创建 brand(即收费步骤)之前告知你需要提供什么的 requirements 调用。
你在 Plivo 拥有的号码需要由支持团队安排号码携转,按他们的时间表而非你的。尽早启动,它可以与代码变更并行进行。

后续步骤

相关资源

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