弃用

Bird 会弃用三类不同的内容，它们的行为各不相同。请求字段会被重命名，旧名称与新名称同时可用。查询参数会被更好的过滤器取代，但仍按原样工作。请求体结构会被新结构取代，旧结构仍会被接受。无论哪种情况，使用了已弃用项的请求都会在响应中带有 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 响应头。
• 找到产生该响应头的请求，并在本参考中查阅对应操作，了解当前名称和请求结构。
• 迁移到当前名称或结构。迁移完成后，只发送当前形式。

当前弃用项

当前没有字段重命名被弃用。联系人的电话号码是 phone_number，验证接收方的邮箱地址是 to 中的 email；任何其他拼写都会被作为验证错误拒绝，适用于所有接受它们的操作。

WhatsApp 消息列表上的 to 和 from 各自匹配消息的一端，且都接受电话号码或业务范围内的用户 ID。phone_number 曾匹配任一方向的联系人，因此不区分方向的搜索需要分别使用这两个过滤器，各发送一次请求。