弃用
Bird 会弃用三种不同的东西，它们的行为各不相同。请求字段被重命名，旧名称与新名称并行工作。查询参数被更好的过滤器取代，但保持原样工作。请求体结构被新结构取代，旧结构继续被接受。在所有情况下，使用了被弃用项的请求都会在响应中带有一个 Deprecation 请求头来告知你。
请求头
对携带了已弃用字段、参数或请求体结构的请求，响应中会包含：
| 请求头 | 值 |
|---|---|
| Deprecation | 弃用公告的日期，例如 @1786579200 |
| Link | <https://bird.com/docs/api/deprecations>; rel="deprecation" |
Deprecation 的值记录了旧名称何时被弃用，遵循 RFC 9745。它不会公告移除日期。
仅使用当前名称的请求的响应不会携带任何一个请求头，因此请求头的出现就是信号：如果你从未看到它，说明你发送的内容没有被弃用。
无移除日期
Bird 不会发送 Sunset 请求头，因为目前没有可用的移除日期。被取代的名称只有在使用量降为零后才会被移除。Bird 会在移除前联系受影响的客户。
将 Deprecation 请求头视为按你自己的节奏迁移的提示。它不会启动移除倒计时。
重命名的请求字段
被取代的字段名称行为与之前完全相同：
- 它仍然在请求中被接受，仍然写入相同的值。
- 它仍然在响应中返回，与替代它的名称一同出现。
- 如果你同时发送两者，当前名称优先，因此你可以逐个调用点迁移，而不用担心旧名称覆盖新名称。
重命名的字段名称从本参考中省略，官方 SDK 仅暴露当前名称。因此，升级你的 SDK 会将请求迁移到当前字段名称。
已弃用的查询参数
当更好的过滤器取代一个查询参数时，该参数即被弃用。它与重命名字段在以下三个方面表现不同：
- 它仍在所有位置发布。 从参考文档和 SDK 中移除它会破坏已在发送它的调用方，因此它保留在本参考文档中的行、每个 SDK 上的字段、CLI 上的标志以及 MCP 工具架构中的条目。升级你的 SDK 不会自动为你完成迁移。
- 没有响应侧。 查询参数只出现在请求中，因此响应体不会有任何变化，也没有可供读取的新名称。
- 替代项可能不止一个参数。 过滤器有时会被一对参数取代，因此该参数自身的描述会指明应使用什么，而非指向单一的后继者。
由于升级不会为你完成迁移，Deprecation 请求头是你会收到的唯一信号。请查看本参考中该参数的描述：已弃用的参数会以 Deprecated: 开头并注明其替代项。
被取代的请求体结构
批量发送端点 POST /v1/sms/batches 和 POST /v1/email/batches 曾将批次作为裸顶层 JSON 数组接收。现在它们接收一个对象，其 messages 数组包含相同的项，这就是本参考所记录的结构。如果请求体仍然是裸数组，它会像以前一样正常工作，并在响应中带有 Deprecation 请求头。官方 SDK 发送 messages 对象，因此升级你的 SDK 会将请求迁移到当前结构。
迁移
- 留意响应中的 Deprecation 请求头。
- 找到产生该请求头的请求，并在本参考中查阅对应操作以了解当前名称和请求结构。
- 迁移到当前名称或结构。完成后只发送当前形式。
当前弃用项
| 操作 | 已弃用 | 替代方案 |
|---|---|---|
| WhatsApp：列出消息 | phone_number 查询参数 | to 或 from |
| SMS 和 email：创建一批消息 | 裸数组请求体 | 包含 messages 的对象 |
当前没有字段重命名被弃用。联系人的电话号码是 phone_number，验证接收方的邮箱地址是 to 中的 email；任何其他拼写都会被作为验证错误拒绝，适用于所有接受它们的操作。
WhatsApp 消息列表上的 to 和 from 各匹配消息的一端，各自接受电话号码或业务范围的用户 ID。phone_number 匹配任一方向的联系人，因此不关心方向的搜索需要两个过滤器，每个一次请求。