跳转到主要内容
跟踪指南与参考文档的 API 变更和更新。标记为 文档更新 的条目采用文档更新日期。截至 2026 年 7 月 13 日的历史发布条目保留其原始日期。之后的条目以及当前 API 参考文档优先于历史公告。
有关当前计费,请参阅 WhatsApp 定价。

2026-11-10

文档更新

  • 新增了 YCloud Developer Kit 指南,包含 Codex、Claude Code 和 WorkBuddy 的安装说明、提示词示例、支持的功能,以及本地测试和授权真实 API 操作的指导。
  • 扩充了 WhatsApp 消息发送 和 错误处理,包括模板参数、引用回复、抑制过滤器以及提交失败与送达失败的说明。
  • 扩充了 Webhook 接收器指南,增加了原始请求体签名验证、持久化事件存储、重复处理和接收器测试。
  • 记录了 Flow 端点请求与响应契约,包括健康检查、屏幕数据交换、错误通知和完成处理。
  • 更新了关于连接器工具、凭证配置、执行日志、设置、预算和对话轮次的 Meta Business Agent 参考文档。请参阅 Agent 配置 和 Agent 操作。

2026-11-03

文档更新

  • 新增了 按事件分类的 Webhook 参考文档,包含消息、模板、账户、电话号码、Business App、Agent、通话、群组、Flow、支付和联系人事件的有效载荷架构、示例以及字段描述。
  • 记录了 Public REST API Agent 的回显创建、回显状态和交接事件。请参阅 Agent Webhook 示例。

2026-10-21

文档更新

  • 明确了 limited_time_offer 仅适用于带有 type: LIMITED_TIME_OFFER 的模板组件。仅当包含该对象时,其 text 字段才是必需的。其他组件类型不需要该对象。请参阅 模板创建示例。

2026-09-18

文档更新

2026-09-17

文档更新

  • 扩展了 Utility Direct Send 指南,包括使用 useDirectSend 进行现有模板转换、送达生命周期以及生成模板的命名规则。
  • 记录了 WhatsApp 屏蔽用户操作:POST /v2/whatsapp/{businessPhoneNumber}/blockUsers、POST /v2/whatsapp/{businessPhoneNumber}/unblockUsers 和 GET /v2/whatsapp/{businessPhoneNumber}/blockedUsers。
  • 扩展了 Meta Business Agent 连接器和工具参考,涵盖 HTTP 和 MCP 连接器、工具发现与执行、凭据以及日志。

2026-09-16

文档更新

2026-09-14

文档更新

2026-07-13

  • 新增了 WABA 级别的 Automatic Creative Optimizations 查询 API:GET /v2/whatsapp/businessAccounts/{wabaId}/automatic-creative-optimizations。
  • 新增了 WABA 级别的 Automatic Creative Optimizations 部分更新 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。
    • 记录了已知的 Partner Removed 原因:ACCOUNT_DISCONNECTED、BUSINESS_DOWNGRADE、CHANGE_NUMBER、COMPANION_INACTIVITY、PRIMARY_INACTIVITY 和 USER_RE_REGISTERED。
    • 记录了已知的 Partner Removed 发起方:USER 和 SYSTEM。

2026-05-19

历史公告:此记录不代表当前的群组消息 Webhook 可用性。请使用最新的 群组指南 和已发布的 Webhook 目录了解受支持的操作与事件。
  • 支持 WhatsApp Groups 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

  • 在获取退订者列表(List unsubscribers,GET /v2/unsubscribers)端点的响应中新增了 source
  • 在按客户获取所有退订者列表(List all unsubscribers by customer,GET /v2/unsubscribers/{customer})端点的响应中新增了 source
  • 在获取单个退订者(Retrieve an unsubscriber,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

  • 支持更新电话号码显示名称(Update a phone number’s display name)端点
  • 在获取电话号码列表(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})
  • 在 Contact 对象中新增字段,用于跟踪联系人来源信息:
    • 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

  • 在 Contact 对象中新增 lastMessageToPhoneNumber。请参阅获取联系人(GET /v2/contact/contacts/{id})。

2024-07-18

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

2024-05-24

  • 自 2024 年 6 月 1 日起,WhatsApp 将在印度尼西亚和印度推出新的国际身份验证费率。参见 国际身份验证费率。
  • 向 WhatsApp Message 对象添加 pricingCategory。如果身份验证对话按国际身份验证费率计费,则 whatsapp.message.updated Webhook 的 pricingCategory 属性将设置为 authentication_international。
  • 向 WhatsApp 商业账户对象添加 authIntlRateEligibilityCountries 和 primaryBusinessLocation。订阅 国际身份验证费率资格 和 主要业务地点更新 Webhook 以接收通知。

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

  • 为每个响应添加速率限制(Rate Limit)响应头。另请参阅速率限制。

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。参见 请求 ID。
  • 在响应 error 对象中添加 requestId。参见 错误。
  • 新增 WhatsApp 模板类别:AUTHENTICATION 和 UTILITY。另请参阅 定价调整上线时间表