# 从 Bird Connectivity Platform 迁移 SMS

本页将 Bird Connectivity Platform API（位于 `rest.messagebird.com`，即你可能仍熟知的 MessageBird API）映射到 Bird。请按顺序遵循[主迁移指南](/docs/guides/sms/migrate)，并在第 3、4、5 步中使用这些映射。

两个平台都属于 Bird，变化的部分是 API。三个差异影响每次调用。请求发送到你的区域主机 `https://us1.platform.bird.com` 或 `https://eu1.platform.bird.com`，而非单一全局主机。认证方式是 bearer API 密钥（`Authorization: Bearer bk_us1_…`），而非 `Authorization: AccessKey`。发送是异步的：[`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) 返回 `202 Accepted`，表示消息已排队；而 Connectivity Platform 返回的消息对象中已附带每个接收方的状态。

## 将以下内容交给你的 agent

将此简报用于你的编码 agent。它从发现阶段开始，在任何生产变更之前生成可审查的迁移计划。

```text
Help me migrate my SMS integration from Bird Connectivity Platform 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/connectivity-platform.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 Connectivity Platform 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.
```

## 映射发送调用

| 功能         | Connectivity Platform      | Bird                                     |
| ------------ | -------------------------- | ---------------------------------------- |
| 接收方       | `recipients`（最多 50 个） | `to`，每次请求一个                       |
| 发送方       | `originator`               | `from`                                   |
| 正文         | `body`                     | `text`                                   |
| 意图         | （无）                     | `category`，自由文本时必填               |
| 编码         | `datacoding`               | 自动检测                                 |
| 音译         | （无）                     | `options.smart_encoding`（默认 `false`） |
| 客户端引用   | `reference`                | `metadata`，或在需要筛选时使用 `tags`    |
| 状态报告     | `reportUrl`                | 订阅了以下投递事件的工作区 webhook       |
| 安全重试     | （无）                     | `Idempotency-Key` 请求头                 |
| 定时发送     | `scheduledDatetime`        | 无对应项：`scheduled_at` 会被拒绝        |
| 有效期       | `validity`                 | 无对应项：`validity_period` 会被拒绝     |
| 路由选择     | `gateway`                  | Bird 选择路由                            |
| 消息类别     | `mclass`                   | 无对应项                                 |
| 二进制和闪信 | `type`、`typeDetails`      | 仅支持文本                               |

两个被拒绝的字段均为[保留字段](/docs/guides/sms/sending-sms#reserved-fields)，并回复 `422 SMSUnsupportedFeature`。

迁移说明：

- **收件人数组变为每个收件人一次调用。** Connectivity Platform 中一次包含 50 个收件人的调用变为 50 次发送，或一个由独立消息组成的[批量请求](/docs/guides/sms/sending-sms#batch-sending)。批量请求不是对同一正文的群发：每条记录都携带自己的接收方、发送方和文本。
- **`datacoding` 没有对应项，这是有意为之。** Bird 从正文自动检测编码并在消息上报告分段数。如果你将 `datacoding: auto` 设为保持消息在 GSM-7 范围内，最接近的行为是 `options.smart_encoding`，它会应用 Bird 文档中的替换表。它不是通用音译工具；不支持的字符仍可能需要 Unicode 编码。
- **`reference` 拆分为两个字段。** 将内部标识符放入 `metadata`，该字段会在每个 webhook 事件中回传；使用 `tags` 存放你希望用于筛选和切片分析的低基数标签。
- **闪信、二进制载荷和 UDH 级联无法迁移。** 如果你依赖 `mclass` 或 `typeDetails`，请在规划切换之前而非之后向支持团队提出。
- **也在使用 Connectivity Platform Verify API？** 该迁移是一项独立工作，有自己的指南：参阅[从其他提供商迁移 Verify](/docs/guides/verify/migrate)。

## 迁移退订记录

Connectivity Platform 将停止关键词处理留给了你，无论你是在 Flows 中构建还是在自己的应用中通过入站消息实现。Bird 自行完成此工作：它在受支持国家/地区识别你号码上的 stop、start 和 help 关键词，记录抑制状态，并在每次发送时强制执行。只有在确认 Bird 的目录覆盖了原有行为且你更广泛的偏好流程仍然有效后，才可停用旧处理程序。

不应停用的是列表本身。导出你当前保留的数据，以订阅者号码和其退订的发送方号码为配对，并在首次生产发送之前通过[抑制流程](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list)导入。如果你之前只保留了一份全局退订订阅者列表，请为你仍在使用的每个发送方逐一导入每个订阅者。

## 转换状态报告

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

| 结果               | Connectivity Platform | Bird                    |
| ------------------ | --------------------- | ----------------------- |
| 被 API 接受        | （同步）              | `sms.accepted`          |
| 已移交运营商       | `sent`、`buffered`    | `sms.sent`              |
| 运营商确认送达     | `delivered`           | `sms.delivered`         |
| 投递失败           | `delivery_failed`     | `sms.failed`            |
| 有效期已过         | `expired`             | `sms.expired`           |
| 请求在准入时被拒绝 | 请求错误              | HTTP 错误；无消息或事件 |
| 等待发送           | `scheduled`           | 暂无对应项              |

投递机制的变化不仅仅是术语：

- **签名 JSON POST 请求取代 `reportUrl` GET 回调。** 状态报告以 `GET` 请求的形式到达，结果包含在查询字符串中（`status`、`statusReason`、`statusErrorCode`、`mccmnc`、`price[amount]`）。Bird 向你工作区注册的端点 `POST` 一个 JSON 事件，按 [Standard Webhooks](https://www.standardwebhooks.com) 签名。处理程序需要重写，而非仅更改 URL。
- **关联不再依赖 `reference`。** 状态报告只有在你设置了引用后才有用；Bird 事件始终携带 `sms_id`、双方号码，以及你回传的 `metadata` 和 `tags`。
- **重试语义不同。** Connectivity Platform 对失败的报告最多重试 10 次。Bird 的投递是至少一次且无序的，因此请根据 `webhook-id` 请求头去重，并按载荷中的 `timestamp` 排序。
- **通过消息和账单所有者核对费用。** Connectivity Platform 报告携带了 `price[amount]` 和 `price[currency]`。使用 [`GET /v1/sms/messages/{id}`](/docs/api/reference/get-sms-message) 读取消息的记录费用，并与账单核对。[Stats API](/docs/guides/sms/stats-api) 用于投递指标，不是权威的账单总额。

入站消息的工作方式相同：为工作区订阅一次 `sms.received`，而非为每个号码分别指定 URL。

## 执行切换

[目标市场](/docs/guides/sms/migrate#1-enable-your-destination-countries)、[发送方](/docs/guides/sms/migrate#2-set-up-a-sender)和[流量渐增](/docs/guides/sms/migrate#6-test-against-simulated-destinations)与提供商无关，已在主迁移指南中涵盖。需要尽早提出的事项是你的发送方标识：字母数字发送方 ID 需要重新创建，在国家/地区有要求时需重新注册；你在 Connectivity Platform 上持有的号码需要通过支持团队安排的号码携转来迁移，而非你自行切换设置。

## 后续步骤

- [探索 Bird SMS](/products/sms)：产品工作流和实施路径

- [发送 SMS](/docs/guides/sms/sending-sms)：你要迁移到的完整载荷
- [退订与关键词](/docs/guides/sms/opt-outs-and-keywords)：Bird 为你自动处理的内容，以及如何管理抑制记录
- [SMS 事件](/docs/guides/sms/events)：你的状态处理程序迁移到的事件词汇表
- [Webhooks 与事件](/docs/guides/webhooks)：端点设置和 Standard Webhooks 验证

## Related resources

- [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer)
- [Check your message segments](/tools/sms-segment-calculator) (tool)
- [Compare SMS providers](/products/sms/compare) (product)