如需查看完整的基于 Schema 的目录,请参阅所有示例。
功能概述
处理商业账户审核、更新和删除事件,以及电话号码删除、显示名称审核、质量和商业用户名(Business Username)更新。根据其确切的事件type 路由各个有效载荷:账户事件使用 whatsappBusinessAccount,而电话号码事件使用 whatsappPhoneNumber。
准备工作
- 在您的应用程序中创建一个公开的 HTTPS 端点。
- 为您需要的事件类型配置 YCloud Webhook 端点。
- 安全存储端点签名密钥。
- 确保事件处理具备幂等性。
工作原理
当事件发生时,YCloud 会发送 HTTPPOST 请求。验证签名,持久化记录事件,返回 2xx 响应,并异步处理耗时任务。
请求
以下场景显示了发送到您的 Webhook URL 的请求。将事件id 视为投递标识符,并使用 type 路由有效载荷。
响应
接收事件后返回2xx 状态。
有关端点设置、签名验证和重试机制,请参阅配置 Webhook。
账户删除
使用whatsapp.business_account.deleted 处理 WhatsApp 商业账户删除事件。读取 whatsappBusinessAccount.id 以识别受影响的 WABA。
请求
响应
在持久化接收事件后确认投递。说明
移除字段在可用时会直接出现在whatsappBusinessAccount 中。
已知的
removedReason 值包括:
保留未知的 reason 和 initiator 值。使用事件
id 对投递进行去重,并允许忽略缺省的移除字段。
国际验证费率资格
自 2024 年 6 月 1 日起,我们将推出新的国际验证费率。该费率将适用于以下国家:- 2024 年 6 月 1 日 – 印度尼西亚(国家/地区呼叫代码 +62,国家/地区代码
ID) - 2024 年 7 月 1 日 – 印度(国家/地区呼叫代码 +91,国家/地区代码
IN)
whatsapp.business_account.updated Webhook。该 Webhook 将包含实行国际验证费率的每个国家/地区的生效时间。
请求
响应
在持久化接收事件后确认投递。whatsappMessage.pricingCategory 将设置为 authentication_international。
示例如下:
说明
根据type 路由事件,根据 id 进行去重,并将耗时或容易失败的任务移至异步处理器。
主要业务所在国家/地区更新
您的主要业务所在国家/地区是您企业所在的国家/地区。自 2024 年 5 月 1 日起,它将显示在 Business Manager 的“Primary Business Location”字段下。 如果 Meta 能够确定您企业所在的国家/地区,我们将触发带有该国家/地区两位代码的whatsapp.business_account.updated Webhook。
示例如下:
请求
响应
在持久化接收事件后确认投递。说明
根据type 路由事件,根据 id 进行去重,并将耗时或容易失败的任务移至异步处理器。
电话号码注册上限更新
当对应的 Business Portfolio 或 WABA 电话号码注册上限发生变更时,Meta 会发送 WABA 的业务功能更新。YCloud 将其作为带有updateEvent=BUSINESS_CAPABILITY_UPDATE 的 whatsapp.business_account.updated 进行投递。
此 Webhook 属于 WABA 级别:whatsappBusinessAccount.id 是来自 Meta Webhook 条目的 WABA ID。Meta 目前在不同的更新中分别报告 maxPhoneNumbersPerBusiness 和 maxPhoneNumbersPerWaba。请勿将它们视为互斥:请独立处理各个字段,并在将来的更新同时包含两者时一并接收。0 的值是有效的。
以下是 WABA 电话号码数量限制更新的示例:
请求
响应
在持久化接收事件后确认送达。说明
按type 路由事件,按 id 进行去重,并且仅更新有效载荷中包含的限制字段。
账户违规
当您收到whatsappBusinessAccount.updateEvent 设置为 ACCOUNT_VIOLATION 的 whatsapp.business_account.updated 事件时,请检查 whatsappBusinessAccount.violationType 以确定所报告的政策违规行为。
有关违规类型和说明,请参阅 Meta 的 政策执行违规。Meta 可能会随时间更新此列表。
示例如下:
请求
响应
在持久化接收事件后确认送达。说明
按type 路由事件,按 id 进行去重,并将缓慢或容易失败的操作转移到异步处理器。
账户限制
如果商业账户反复违反 WhatsApp 商业服务条款或高风险政策类别(例如发送垃圾消息、成人内容、销售烟酒、毒品、赌博和不安全补剂),可能会开始受到消息发送限制,且限制时长会逐渐增加。 对于 Utility Direct Send,请参阅 Direct Send 通知 以了解 YCloudACCOUNT_RESTRICTION 有效载荷。请参阅 Meta 的账户限制 Webhook,了解 Direct Send 专属的违规类型和限制详情。
示例如下:
请求
响应
在持久化接收事件后确认送达。说明
按type 路由事件,按 id 进行去重,并将缓慢或容易失败的操作转移到异步处理器。
Utility Direct Send 限制
当 Meta 在多次类别误用后限制 Utility Direct Send 时,您会收到whatsapp.business_account.updated。此示例显示了为期 7 天的限制。
请求
响应
在持久化接收事件后确认送达。说明
使用whatsappBusinessAccount.id 确定受影响的 WABA 并暂停其 Utility Direct Send 工作流。读取 violationType 获取原因,restrictions[].restrictionType 获取受影响的功能,以及在提供时读取 restrictions[].expiration 获取到期时间。单个模板审核成功不会自动解除账户级别的限制。请参阅 Direct Send 限制与通知。
账户已停用
如果商家在多次警告和功能限制或封锁后仍未做出整改,WhatsApp 商业账户可能会被停用。 示例如下:请求
响应
在持久化接收事件后确认送达。说明
按type 路由事件,按 id 进行去重,并将缓慢或容易失败的操作转移到异步处理器。
账户恢复
您可以对 WhatsApp 商业账户封禁决定提出申诉以恢复账户。一旦申诉获批,账户审核状态将变为APPROVED。
示例如下:
请求
响应
在持久化接收事件后确认送达。说明
按type 路由事件,按 id 进行去重,并将缓慢或容易失败的操作转移到异步处理器。
商业账户审核
当 WhatsApp 商业账户已完成审核时,使用whatsapp.business_account.reviewed。
请求
响应
在持久化接收事件后确认送达。说明
使用id 识别 WABA。读取 decision 获取审核决定(APPROVED 或 REJECTED),并在提供时读取 accountReviewStatus 获取账户审核状态。请勿将此事件路由为 whatsapp.business_account.updated。
电话号码删除
当 WhatsApp 商业电话号码被删除时,使用whatsapp.phone_number.deleted。
请求
响应
在持久化接收事件后确认送达。说明
使用whatsappPhoneNumber.id 识别已删除的电话号码,并使用 wabaId 将其与其账户关联。这是一个电话号码级别的事件;请勿将其视为整个 WABA 的删除。
电话号码显示名称审核
当商业电话号码显示名称获批或被拒绝时,使用whatsapp.phone_number.name_updated。
请求
响应
在持久化接收事件后确认送达。说明
读取decision 及提供的名称状态字段。newNameStatus 描述新的显示名称请求,requestedVerifiedName 标识上次请求的名称,rejectionReason 存在时用于说明拒绝原因。显示名称审核与 Business Username 更新是相互独立的。
电话号码质量更新
当商业电话号码的质量相关状态发生变更时,使用whatsapp.phone_number.quality_updated。
请求
响应
在持久化接收事件后确认送达。说明
读取qualityRating(GREEN、YELLOW 或 RED)和 qualityUpdateEvent 以了解更新。messagingLimit 是电话号码层级;whatsappBusinessManagerMessagingLimit 是所属商业资产组合的限制。请区分这些字段,并仅更新事件中提供的值。
商业用户名已激活
使用whatsapp.phone_number.business_username_updated 同步电话号码的商业用户名。
请求
响应
在持久化接收事件后确认交付。说明
businessUsername 是不带前导 @ 的活跃用户名。请结合电话号码 id 一同读取 businessUsernameStatus 和 businessUsernameUpdatedAt。请勿将此值与已验证的显示名称混淆。
商业用户名申请已保留
在替换申请保留期间,原活跃商业用户名仍可继续使用。请求
响应
在持久化接收事件后确认交付。说明
在此示例中,当requestedBusinessUsername 为 acme.help 时,businessUsername 仍保持为 acme.support。reserved 状态描述的是待处理的申请,而非替换项的激活。读取较旧的事件时接受旧版 pending_review 值;新写入使用 reserved。
商业用户名已撤销
事件类型仍为whatsapp.phone_number.business_username_updated。
businessUsernameContext 是一个可选字符串。值为 revoked 表示撤销通知;它与 businessUsernameStatus 分开。
请求
响应
在持久化接收事件后确认交付。说明
YCloud 在生成此事件前会从 Meta 刷新当前用户名和状态。仅当当前成功的 Meta 查询返回的用户名与撤销通知中的用户名匹配时,才会包含revoked。如果通知引用了用户名 A,但 Meta 当前返回 B,则发送的事件包含 B 并省略已作废的 revoked 上下文。
当通知没有上下文时,该上下文也会被省略。控制台中显示的历史警告不会在此字段中重放。模拟的上游通知不会替换 Meta 返回的用户名或状态。
