有关当前计费,请参阅 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
文档更新
- 新增了涵盖资格、新手引导、配置、测试、发布和运营的 Meta Business Agent 集成指南。
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
文档更新
- 更新了 Business-Scoped User ID 指南,增加了 API 和 Webhook 身份处理相关内容。
2026-09-14
文档更新
- 记录了用于 WhatsApp Business App 历史记录同步的
phase和progress。参见 历史记录 Webhook 示例。 - 记录了按用户名上报自定义事件的说明。参见 跟踪自定义事件。
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_updatedWebhook 示例。
2026-06-10
更新
- 还原了此前于 2026-05-25 引入并记录的 WhatsApp 商业账户
removed状态。 - 合作伙伴移除事件现在由
whatsapp.business_account.deletedWebhook 负载表示,而不是whatsapp.business_account.updated。 removedReason、removedInitiatedBy和removedTime作为可选的移除元数据,保留在已删除的 WhatsApp 商业账户 Webhook 负载中。
新增
- 在
WhatsappBusinessAccountUpdateEventEnum中新增了PARTNER_APP_UNINSTALLED。
2026-06-08
新增
- WhatsApp 电话号码对象的新字段:
updateEvent
- 在
whatsapp.phone_number.quality_updatedWebhook 负载中新增了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.updatedWebhook 中支持 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。
- 在 WhatsApp 商业账户 Webhook 有效负载中添加了
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 年各记录中的位置予以保留,未推断不同的发布日期。
- 支持 WhatsApp inbound-unsupported-message
UNSUPPORTED_TYPE
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
- 支持 WhatsApp 创建 Gif 模板/发送 Gif 模板消息
2025-12-15
- 支持 WhatsApp 深度链接模板
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 载荷
- 获取 WABA 列表(
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
- 在 Flow 创建 API(
2025-08-28
- 新增 WhatsApp Smb Webhook
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)
- 发起 WhatsApp 外呼通话(
- 新增配置通话设置 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})
- 创建 Webhook 端点(
- 在 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
- 支持 WhatsApp 订单详情消息和 订单状态消息。
- 新增 Webhook 事件类型
whatsapp.payment.updated。另请参阅 WhatsApp 支付更新 Webhook 示例。
2024-09-12
- 支持 WhatsApp Flows。另请参阅 Flow 模板、Flow 模板消息、交互式 Flow 消息 和 入站交互式 Flow 响应消息。
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
- 支持 WhatsApp 交互式位置请求消息。
- 支持 WhatsApp 入站请求欢迎消息。
- 若从未设置(即
messageSendTtlSeconds为-1),将身份验证模板消息的生存时间从 24 小时更改为 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
- 支持 WhatsApp 目录模板和 目录模板消息。
- 支持 WhatsApp 多商品消息模板和 MPM 模板消息。
- 支持 WhatsApp 交互式目录消息。
- 添加更新商业设置 (
PATCH /v2/whatsapp/phoneNumbers/{wabaId}/{phoneNumber}/whatsappCommerceSettings) 端点,用于启用或禁用特定商业电话号码的购物车或商品目录。
2023-11-02
- 支持 WhatsApp 零点击身份验证模板。
- 为身份验证模板添加消息生存时间。新创建的身份验证模板默认值为 600 秒。
2023-10-27
2023-10-18
- 支持 WhatsApp 交互式 CTA URL 按钮消息。另请参阅交互式 CTA URL 消息示例。
2023-10-12
- 新增 Webhook 事件类型 whatsapp.business_account.deleted 和 whatsapp.phone_number.deleted。
- 支持 WhatsApp 优惠券模板。更多示例请参阅优惠券模板和优惠券模板消息。
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
- 新增 Webhook 事件类型
whatsapp.template.quality_updated,以帮助您跟踪 WhatsApp 模板质量评级的更新。请参阅Webhook 事件与有效载荷。 - 在 WhatsApp Template 对象中新增
qualityRating。
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。另请参阅 定价调整上线时间表

