Sign inGet started

从 Infobip 迁移 SMS

本页将 Infobip 的 SMS API、Blocklist 和投递报告映射到 Bird。按顺序遵循主迁移指南,并在步骤 3、4 和 5 中使用这些映射。
两个差异完成了大部分工作。Infobip 的载荷为批量场景设计,因此向一个人发送一条消息需要一个消息数组,每条消息包含一个目标数组,正文在 content.text 中位于两层嵌套之下;POST /v1/sms/messagesfromtotext 放在顶层。此外,你的 Infobip base URL 是按账户个性化的,格式为 xxxxx.api.infobip.com,通过 Authorization: App <key> 进行认证。Bird 使用区域主机和 bearer key 发送,因此你代码中保存的主机与载荷结构同时变更。

将此交给你的 agent

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

映射发送调用

重命名表很短,因为结构变更才是主要工作:
功能InfobipBird
接收方messages[].destinations[].toto(每个请求一个)
发送方messages[].senderfrom
正文messages[].content.texttext
意图(无)category,自由文本时必填
投递报告webhooks.delivery,按消息配置订阅下方投递事件的工作区 webhook
往返上下文webhooks.callbackDatametadata,但请参阅下方大小说明
活动分组options.campaignReferenceIdtags,仅用于筛选;见下方
Flashoptions.flash无对应项
有效期options.validityPeriod无对应项:validity_period 会被拒绝
投递窗口options.deliveryTimeWindow无对应项
安全重试(其生成的客户端中无此功能)Idempotency-Key 请求头
移植说明:
  • 三层嵌套变为零层。 嵌套存在是为了在一个请求中承载多条消息和多个目标。向一个人发送一条消息时,Bird 将三个字段放在顶层,因此组装数组的构建器应当删除而非翻译。
  • callbackDatametadata 更大。 Infobip 接受最多 4000 个字符并在投递报告中返回。Bird 的 metadata 上限为序列化后 2 KB,且会在该消息的每个事件中回传,而不仅是终态事件。回传更有价值;容量上限则不然,因此接近限制的内容必须裁剪为一个可查找的键,而不是整体携带。
  • campaignReferenceId 是报告上下文,不是活动迁移。 Bird 的 tags{name, value} 对,会成为查询维度,让你可以像以前一样按活动切分分析数据。但它们不附带活动对象:标签不会创建或配置广播。在迁移受众活动时,请单独评估活动工作流
  • campaignReferenceId 不是幂等键。 Infobip 将其定义为跟踪活动效果的 ID,因此它用于分组但不去重。如果你依赖它来使重试安全,那你并未得到保护;Idempotency-Key 请求头才是此处实现该功能的方式。
  • 没有字段对应 category Infobip 的消息选项涵盖有效期、投递窗口、flash 和区域设置,但没有一个声明消息发送的目的。请按消息类型决定它是 transactionalmarketingauthentication 还是 service
  • 两个选项字段无处安放。 validityPeriod保留的,对应 422 SMSUnsupportedFeaturedeliveryTimeWindow 没有对应项,因此调度窗口需移入你自己的调度器。

迁移退订记录

Infobip 维护一个 Blocklist:一个已退订你通信的接收方列表,通过 Blocklist API 或在 Web 界面的 People 中管理,向其中任何人发送消息会被拒绝。关键词触发器会自动将号码加入其中,因此订阅者发送 STOP 后无需你的应用做任何操作即可进入该列表。
这使得导出在本系列供应商中最简单,而扩展量最大。一条 Blocklist 记录对应整个账户的一个订阅者;一条 Bird 抑制记录对应一个发送方-订阅者配对。 因此每条记录会变成与你的发送方数量相同的抑制记录:一千条 Blocklist 记录和六个发送方就是六千条记录。在开始之前先算好倍数,因为这决定了导入是一分钟完成,还是需要分批处理和进度日志。
保留 Blocklist 的原始范围。不要仅因为新的技术模型能表达更窄的配对,就在迁移时缩小撤回范围。工作区级别的偏好可以代表更广泛的请求;它与发送方抑制是不同的所有者。在判定发送资格时需同时检查两者。
通过抑制循环导入。读取和管理抑制记录包含具体命令,以及手动抑制为何会阻止包括事务性在内的所有类别。
到达此步后,Bird 会根据每个国家自有的目录自动响应停止关键词,因此你之前配置的关键词触发器无需重建,任何自定义触发器则变为关键词规则。原因是叠加而非合并的,因此你以 manual 导入的配对如果后来发送了 STOP,会持有两条记录,消息将保持停止状态直到两者均已结束。

转换投递状态

使用此表比较生命周期概念,而非机械地重命名事件。Bird 根据报告的状态和原因选择失败事件。被拒绝的 API 请求不会创建消息;接受后的拒绝可能产生 sms.rejected,包括运营商拒绝。缺少投递证据的状态保持为未知。在你的标准化结果旁保留原始供应商状态和代码。
Infobip 在每条投递报告中报告一个状态组和一个状态名,而 Bird 发出一个事件类型:
结果Infobip 状态组Bird
API 已接受消息PENDINGsms.accepted
已移交运营商PENDINGsms.sent
运营商确认投递DELIVEREDsms.delivered
运营商报告未投递UNDELIVERABLEsms.undelivered
永久失败REJECTEDsms.failed
发送前被拒绝REJECTEDsms.rejected
有效期窗口已过EXPIREDsms.expired
EXPIRED 是需要仔细阅读的行,因为它在 Infobip 侧涵盖两种不同情况,而在此处只有一种存在。Infobip 在两种情况下使消息过期:一是其平台自身的有效期到期(默认 48 小时),二是运营商返回过期作为最终状态。Bird 不设置自己的有效期窗口,也不运行结束消息的计时器,因此 sms.expired 只会来自运营商的投递回执。运营商报告的那一半可以映射过来;平台计时器的那一半没有对应项,在 Infobip 时钟上本会过期的消息在此处会继续投递中,直到运营商做出决定。
REJECTED 出现两次是有意为之。Infobip 将其同时用于自身拒绝的消息和运营商返回为已拒绝的消息,这对应 Bird 根据处理或运营商结果及其原因选择的事件;运营商拒绝可能产生 sms.rejected。状态组内的状态名才是区分二者的关键,因此仅根据状态组分支的处理器到了这里需要用到状态名。PENDING 也覆盖了两行,因为它是消息从被接受到终态报告到达之间所处的状态组。
三个机制随名称一起变化:
  • 订阅替代按消息配置的 webhook。 Infobip 在每条消息上指定一个 webhook,因此目标由编写调用的人选择,内容类型也随之选择。Bird 将 JSON 投递到你的工作区注册的端点,每个端点订阅其所需的事件类型,因此增加一个消费者只需增加一个订阅,而非在每个调用处修改。
  • 你会失去按消息选择的能力,包括 XML。 Infobip 允许消息选择 JSON 或 XML 并附加最多 4000 个字符的回调数据。Bird 仅发送 JSON,callbackData 变为 metadata,后者会在该消息的每个事件中回传,而不仅是报告中。
  • 拉取变为推送。 Infobip 允许你从报告端点获取报告,也可以接收推送。Bird 没有对应的事件轮询方式;请订阅事件,需要按需查询时通过 API 读取消息状态。
注册端点只需一次,指定你的处理器需要的事件类型:上方的 sms.* 事件就是需要订阅的列表,没有通配符可以代替它们。Bird 发送按 Standard Webhooks 签名的 JSON;创建端点包含具体命令,以及首次调用时需要做对的一件事:存储响应中仅显示一次的签名密钥。
Bird 使用标准化的 error 代码报告失败,如 invalid_destinationcontent_rejectedprovider_unavailablerecipient_opted_out;完整列表见事件页面。将你的告警映射到这些代码,而非 Infobip 的数字组和名称对。

切换

目标号码发送方流量爬坡与供应商无关,已在主指南中涵盖。三个 Infobip 特有的事项需要纳入切换计划。
主机会变,且这是配置而非代码。 你的 Infobip base URL 按账户发放;Bird 从创建工作区时选择的区域主机发送。在切换前找到该主机设置的每个位置,包括环境变量、密钥管理器和部署清单,因为遗漏的位置会在运行时而非构建时失败。
你的 10DLC 品牌和活动通过 Infobip 的号码注册 API 在 The Campaign Registry 注册,不会自动成为 Bird 注册。在提交付费工作之前,确认适用的迁移或注册流程。从注册 10DLC 开始:它涵盖了每个字段的含义、注册表认可的实体类型,以及在创建品牌(即收费步骤)之前告知你需提供哪些内容的需求调用。
你在 Infobip 持有的号码需要由支持团队安排的号码移植,按他们的时间表而非你的。

后续步骤

相关资源

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