Skip to main content
如需查看完整的基于 Schema 的目录,请参阅所有示例。

功能概述

处理商业账户审核、更新和删除事件,以及电话号码删除、显示名称审核、质量和商业用户名(Business Username)更新。根据其确切的事件 type 路由各个有效载荷:账户事件使用 whatsappBusinessAccount,而电话号码事件使用 whatsappPhoneNumber。

准备工作

  • 在您的应用程序中创建一个公开的 HTTPS 端点。
  • 为您需要的事件类型配置 YCloud Webhook 端点。
  • 安全存储端点签名密钥。
  • 确保事件处理具备幂等性。

工作原理

当事件发生时,YCloud 会发送 HTTP POST 请求。验证签名,持久化记录事件,返回 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 将包含实行国际验证费率的每个国家/地区的生效时间。

请求

响应

在持久化接收事件后确认投递。
如果某条消息按国际验证费率计费,则 whatsapp.message.updated 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 通知 以了解 YCloud ACCOUNT_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 返回的用户名或状态。