跳转到主要内容
本归档保留了截至 2026 年 7 月 13 日早期 API 文档中的带日期记录。历史公告仅描述当时的接口约定；后续记录以及当前的 API 参考文档具有更高优先级。
有关当前计费信息，请参阅 WhatsApp 定价。

​
2026-07-13

  • 新增了 WABA 级别的自动广告创意优化查询 API：GET /v2/whatsapp/businessAccounts/{wabaId}/automatic-creative-optimizations。
  • 新增了 WABA 级别的自动广告创意优化部分更新 API：PATCH /v2/whatsapp/businessAccounts/{wabaId}/automatic-creative-optimizations。

​
2026-07-07

​
更新

  • 更新了 WhatsApp 商业用户名状态文档，对于已被 Meta 保留且可能仍在审核中的商业用户名请求，使用 reserved。
  • 将 pending_review 标记为旧版兼容值。新的商业用户名写入操作请使用 reserved。

​
新增

  • 在 WhatsApp 商业用户名状态枚举中新增了 reserved。
  • 新增了 businessUsernameStatus 设置为 reserved 的 whatsapp.phone_number.business_username_updated Webhook 示例。

​
2026-06-10

​
更新

  • 还原了先前文档中记录的于 2026-05-25 引入的 WhatsApp 商业账户 removed 状态。
  • 合作伙伴移除事件现在由 whatsapp.business_account.deleted Webhook 载荷表示，不再使用 whatsapp.business_account.updated。
  • removedReason、removedInitiatedBy 和 removedTime 作为可选的移除元数据保留在已删除 WhatsApp 商业账户的 Webhook 载荷中。

​
新增

  • 在 WhatsappBusinessAccountUpdateEventEnum 中新增了 PARTNER_APP_UNINSTALLED。

​
2026-06-08

​
新增

  • WhatsApp 电话号码对象上的新增字段：
    • updateEvent
  • 在 whatsapp.phone_number.quality_updated Webhook 载荷中新增了 updateEvent，用于标识触发电话号码状态变更的账户更新事件，例如 ACCOUNT_OFFBOARDED 或 ACCOUNT_RECONNECTED。

​
2026-06-01

​
新增

  • 新增了用于查询、更新、删除和获取 WhatsApp 商业用户名建议的 API。
  • WhatsApp 电话号码对象上的新增字段：
    • businessUsername
    • businessUsernameStatus
    • requestedBusinessUsername
    • businessUsernameUpdatedAt
  • 新增 Webhook 事件类型：whatsapp.phone_number.business_username_updated。

​
2026-05-25

  • 在 whatsapp.business_account.updated Webhook 中支持 WhatsApp 商业账户“合作伙伴已移除”更新。
    • 在 WhatsApp 商业账户 Webhook 载荷中新增了 removed、removedReason、removedInitiatedBy 和 removedTime。
    • 在 WhatsApp 商业账户 updateEvent 中新增了 PARTNER_REMOVED。
    • 记录了已知的“合作伙伴已移除”原因：ACCOUNT_DISCONNECTED、BUSINESS_DOWNGRADE、CHANGE_NUMBER、COMPANION_INACTIVITY、PRIMARY_INACTIVITY 和 USER_RE_REGISTERED。
    • 记录了已知的“合作伙伴已移除”发起方：USER 和 SYSTEM。

​
2026-05-19

历史公告：此记录不代表当前群组消息 Webhook 的可用性。请参阅当前的 群组指南 及已发布的 Webhook 目录，以了解支持的操作和事件。
  • 支持 WhatsApp 群组 API。
  • 支持 WhatsApp 群组邀请链接、加入申请、群成员以及设置等相关操作。
  • 在 WhatsApp 模板组件参数中新增了 group_id。
  • 新增了 WhatsApp 群组 Webhook 事件类型及 whatsappGroup 载荷。另请参阅 Webhook 事件与载荷 和 Webhook 载荷示例。
  • 在群组消息的 WhatsApp 入站消息载荷中新增了 groupId。

​
2025-05-08

原始更新日志记录的日期为 2025-05-08。其在 2026 年各条目中的相对位置予以保留，不对实际发布日期做额外推断。

​
2026-04-29

  • 在 WhatsApp 模板 status 中新增了 ARCHIVED。
  • 在 WhatsApp 模板 statusUpdateEvent 中新增了 ARCHIVED 和 UNARCHIVED。
  • 新增了 WhatsApp 模板归档与取消归档事件的 Webhook 示例。另请参阅 WhatsApp 模板审核 Webhook 示例。
  • 在获取模板列表 (GET /v2/whatsapp/templates) 端点中新增了 filter.status，用于按状态筛选模板（包括 ARCHIVED）。

​
2026-03-13

  • 为支持 Meta 自 2026 年 3 月 31 日起推行的 BSUID，YCloud 已更新与消息和用户身份相关的若干 Webhook 载荷。请参阅 BSUID 相关的 Webhook 更新

​
2026-03-04

​
2026-01-28

​
2025-12-15

​
2025-12-03

  • 支持 WhatsApp interactive-media-carousel-messages。
  • contact-retrieve (GET /v2/contact/contacts/{id})/contact-update (PATCH /v2/contact/contacts/{id})/contact-delete (DELETE /v2/contact/contacts/{id}) 支持电话号码。

​
2025-11-06

  • 新增 Webhook 事件类型： whatsapp.user.preferences

​
2025-10-22

  • 在获取退订者列表 (GET /v2/unsubscribers) 端点的响应中新增了 source
  • 在按客户获取所有退订者列表 (GET /v2/unsubscribers/{customer}) 端点的响应中新增了 source
  • 在获取单个退订者 (GET /v2/unsubscribers/{customer}/{channel}) 端点的响应中新增了 source
  • 新增 Webhook 事件类型： contact.unsubscribe.created、 contact.unsubscribe.deleted ，另请参阅：

​
2025-10-20

  • 在多个端点中添加了 whatsappBusinessManagerMessagingLimit 字段：
    • 获取 WABA 列表 (GET /v2/whatsapp/businessAccounts) 和获取单个 WABA (GET /v2/whatsapp/businessAccounts/{id}) 端点
    • 获取电话号码列表 (GET /v2/whatsapp/phoneNumbers) 和获取单个电话号码 (GET /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}) 端点
    • whatsapp.phone_number.quality_updated Webhook 有效载荷

​
2025-10-10

  • 在获取 WABA 列表 (GET /v2/whatsapp/businessAccounts) 端点和获取单个 WABA (GET /v2/whatsapp/businessAccounts/{id}) 端点的响应中添加了 businessId、businessStatus 以及 businessName

​
2025-09-24

  • 支持 更新电话号码的显示名称 端点
  • 在获取电话号码列表 (GET /v2/whatsapp/phoneNumbers) 端点和获取单个电话号码 (GET /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}) 端点的响应中添加了 newName。
  • 在获取电话号码资料 (GET /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/profile) 的响应中添加了 verifiedName、nameStatus 以及 newName
  • 在 whatsapp.phone_number.quality_updated Webhook 的有效载荷中添加了 whatsappBusinessManagerMessagingLimit 字段

​
2025-09-01

  • 新增对 WhatsApp Flow 端点重定向功能的支持
    • 在创建 Flow API (POST /v2/whatsapp/flows) 中添加 endpointUri 参数，用于指定 Flow 端点 URI
    • 在更新 Flow 元数据 API (PATCH /v2/whatsapp/flows/{flowId}/metadata) 中添加 endpointUri 参数，用于端点配置
    • 在 Flow 详情 API (GET /v2/whatsapp/flows/{flowId}) 的返回内容中添加 endpointUrl 资源

​
2025-08-28

​
2025-08-20

  • 新增 WhatsApp 通话 API
    • 发起 WhatsApp 外呼通话 (POST /v2/whatsapp/calls/connect)
    • 预接听 WhatsApp 呼入通话 (POST /v2/whatsapp/calls/preAccept)
    • 接听 WhatsApp 呼入通话 (POST /v2/whatsapp/calls/accept)
    • 终止 WhatsApp 通话 (POST /v2/whatsapp/calls/terminate)
    • 拒接 WhatsApp 呼入通话 (POST /v2/whatsapp/calls/reject)
  • 新增配置通话设置 API
    • 获取商业电话号码通话设置 (GET /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings)
    • 配置商业电话号码通话设置 (POST /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/settings)
  • 新增 WhatsApp 通话 Webhook
  • WhatsApp 通话使用指南：whatsapp-calling-examples

​
2025-08-04

  • 新增 WhatsApp Flow 预览 (GET /v2/whatsapp/flows/{flowId}/preview) 网页支持

​
2025-07-24

  • 在创建模板 (POST /v2/whatsapp/templates) 中添加了新的 supported_apps 数组字段，用于在一个 OTP 模板（One-tap / Zero-tap）中定义多个应用包名和签名密钥哈希（最多 5 个应用）。
    • 弃用了现有的 package_name 和 signature_hash 字段，改用新的 supported_apps 数组结构

​
2025-07-10

  • 新增获取联系人属性列表 (GET /v2/contact/contacts/attributes) 支持，用于查询所有已定义的联系人属性。
  • 新增了 Webhook 事件类型：contact.created、contact.deleted 和 contact.attributes_changed。另请参阅：
  • 在以下 Webhook 端点 API 中添加了新属性 eventProperties：
    • 创建 Webhook 端点 (POST /v2/webhookEndpoints)
    • 更新 Webhook 端点 (PATCH /v2/webhookEndpoints/{id})
    • 获取 Webhook 端点列表 (GET /v2/webhookEndpoints)
    • 获取单个 Webhook 端点 (GET /v2/webhookEndpoints/{id})
  • 在联系人对象中添加了新字段，用于跟踪联系人来源信息：
    • sourceType：联系人来源类型枚举（WHATSAPP、GROWTH_TOOL、MANUALLY_ADDED、FILE_IMPORT、SHOPIFY、API、AD、POST、CALLING、SMB、UNKNOWN）
    • sourceId：用于跟踪联系人创建来源的来源标识符
    • sourceUrl：创建联系人的来源 URL

​
2025-07-01

  • 新增 WhatsApp Flow API (POST /v2/whatsapp/flows) 支持，包含以下端点：
    • 创建 flow、获取 flow 列表、更新 flow 元数据、更新 flow 结构、删除 flow、获取单个 flow、发布 flow、弃用 flow

​
2024-10-10

​
2024-09-12

​
2024-08-22

  • 新增 自定义事件 API。请参阅发送事件 (POST /v2/event/events)。

​
2024-08-02

  • 在联系人对象中添加了 lastMessageToPhoneNumber。请参阅获取单个联系人 (GET /v2/contact/contacts/{id})。

​
2024-07-18

  • 在将 WhatsApp 消息加入发送队列 (POST /v2/whatsapp/messages) 端点中添加了 filterBlocked。如果设置为 true，我们将不会向黑名单中的用户发送消息。

​
2024-05-24

​
2024-04-03

  • 向 WhatsApp Message 对象添加 regionCode。

​
2024-02-22

  • 添加 WhatsApp 将消息标记为已读（POST /v2/whatsapp/inboundMessages/{id}/markAsRead）端点。

​
2024-01-30

​
2024-01-17

  • 向发起验证（POST /v2/verify/verifications）端点添加参数 externalId。

​
2024-01-05

  • 添加注册电话号码（POST /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/register）端点。
  • 向 WhatsApp Phone Number 对象添加 id。
  • 向 WhatsApp 商业账户对象添加 paymentMethodAttached。

​
2023-12-21

​
2023-12-13

  • 向将 WhatsApp 消息加入发送队列（POST /v2/whatsapp/messages）端点添加请求参数 filterUnsubscribed。如果设置为 true，消息将不会发送给已退订您账户的用户。

​
2023-11-24

​
2023-11-02

  • 支持 WhatsApp 零点击身份验证模板。
  • 为身份验证模板添加消息生存时间。新创建的身份验证模板默认为 600 秒。

​
2023-10-27

​
2023-10-18

​
2023-10-12

​
2023-09-07

  • 添加联系人 API /v2/contact/contacts。使用它来创建、更新或删除您的联系人。

​
2023-07-05

  • 向 WhatsApp Message 对象添加 conversation.type。如果存在，可能的值为 FREE_ENTRY、FREE_TIER 和 REGULAR。
  • 向 WhatsApp Phone Number 对象添加 isOfficialBusinessAccount。

​
2023-06-01

  • 向每个响应添加速率限制请求头。另请参阅速率限制。

​
2023-05-26

​
2023-05-16

  • 添加 WhatsApp 消息发送 API /v2/whatsapp/messages/sendDirectly。有关错误处理，另请参阅 WhatsApp 错误。
  • 添加 WhatsApp 模板删除 API DELETE /v2/whatsapp/templates/{wabaId}/{name}/{language}。
  • 向响应体 error 对象添加 whatsappApiError。
  • 向 WhatsApp Phone Number 对象添加 qualityUpdateEvent。
  • 向 WhatsApp Message 对象添加 sendTime、deliverTime 和 readTime。
  • 向 WhatsApp Phone Number messagingLimit 添加新的枚举值 TIER_NOT_SET。

​
2023-03-24

  • WhatsApp 会话在会话的第一条消息被delivered而非sent时收取费用。 因此，在消息送达之前，WhatsApp 消息对象的 totalPrice 字段仅为预估价格，当 status 为 delivered 或 read 时，它才会成为最终价格。已发送但尚未送达的消息所占用的余额在消息被丢弃前将不可用（已发送但超过 30 天未送达的消息会被丢弃）。在会话的第一条消息变为 delivered 或 read 之前，conversation.expireTime 也只是一个预估的过期时间。
  • 添加 Webhook 事件类型 whatsapp.template.category_updated，以帮助您跟踪 WhatsApp 模板类别的变更。请参阅 WhatsApp 模板类别更新有效载荷。有关模板类别迁移的更多信息，另请参阅 首次模板类别迁移。
  • 新增 WhatsApp 会话发起类型：authentication、marketing、utility 和 service。切换至新定价模式将于 2023 年 6 月 1 日执行。另请参阅自 2023 年 6 月 1 日起生效的新会话费率。
  • 支持创建带有一次性密码按钮的身份验证模板，该功能将于 2023 年 5 月 1 日起提供，并将于 2023 年 5 月 29 日起强制执行。

​
2023-03-09

  • 为每个请求添加响应头 YCloud-Request-ID。请参阅 Request ID。
  • 在响应 error 对象中添加 requestId。请参阅 错误。
  • 新增 WhatsApp 模板类别：AUTHENTICATION 和 UTILITY。另请参阅价格变动上线时间表