WhatsApp 商业账户更新 Webhook 示例

如需查看基于架构派生的完整目录，请参阅所有示例。

功能介绍

处理 WhatsApp 商业账户更新事件。

开始之前

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

工作原理

事件发生时，YCloud 会发送一个 HTTP POST 请求。请验证签名、持久化记录事件、返回 2xx 响应，并异步处理耗时任务。

请求

以下场景展示了发送到您的 Webhook URL 的请求。将事件 id 作为投递标识符，并使用 type 对载荷进行路由。

响应

在接收事件后返回 2xx 状态。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制，请参阅配置 Webhook。

国际身份验证费率适用资格

自 2024 年 6 月 1 日起，我们将推出新的国际身份验证费率。该费率将适用于以下国家/地区：

2024 年 6 月 1 日 – 印度尼西亚（国家/地区拨号代码 +62，国家/地区代码 ID）
2024 年 7 月 1 日 – 印度（国家/地区拨号代码 +91，国家/地区代码 IN）

如需了解更多信息，请参阅国际身份验证费率适用资格。如果您的企业被视为符合国际费率适用资格，则会触发 whatsapp.business_account.updated Webhook。该 Webhook 将包含实行国际身份验证费率的每个国家/地区的开始时间。

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

如果消息按国际身份验证费率计费，则 whatsapp.message.updated Webhook 中的 whatsappMessage.pricingCategory 将设置为 authentication_international。示例如下：

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

说明

通过 type 路由事件，通过 id 去重，并将耗时或易失败的工作转移到异步处理器。

主要营业地点更新

您的主要营业地点是您的企业所在的国家/地区。自 2024 年 5 月 1 日起，它将显示在商务管理平台中的“主要营业地点”字段下。如果 Meta 能够确定您的企业所在的国家/地区，我们将触发包含该国家/地区两位字母代码的 whatsapp.business_account.updated Webhook。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 去重，并将耗时或易失败的工作转移到异步处理器。

电话号码注册上限更新

当对应的业务资产组合或 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 电话号码上限更新的示例：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 去重，并仅更新载荷中包含的上限字段。

账户违规

WhatsApp 商业账户最初会收到包含其所违反政策信息的警告。另请参阅 WhatsApp 商业平台政策违规行为
。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SPAM"
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 去重，并将耗时或易失败的工作转移到异步处理器。

账户受限

如果商业账户屡次违反 WhatsApp 商业服务条款，或触犯高风险政策类别（例如发送垃圾消息、成人内容、销售烟酒、毒品、赌博和不安全补剂），可能会面临持续时间逐渐增加的消息发送限制。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
    ]
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 去重，并将耗时或易失败的工作转移到异步处理器。

账户已停用

如果在多次收到警告以及功能受限或封禁后企业仍未作出整改，WhatsApp 商业账户可能会被停用。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

响应

在持久化接收事件后确认投递。

HTTP/1.1 200 OK

说明

通过 type 路由事件，通过 id 去重，并将耗时或易失败的工作转移到异步处理器。

账户恢复

您可以对 WhatsApp 商业账户的封禁决定提出申诉以恢复账户。申诉通过后，账户审核状态将变更为 APPROVED。示例如下：

请求

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

响应

在持久化接收该事件后确认送达。

HTTP/1.1 200 OK

说明

按 type 路由事件，按 id 进行去重，并将耗时较长或易失败的任务移至异步处理器。

开始使用

指南

接口

Webhooks

WhatsApp 商业账户更新 Webhook 示例

功能介绍

开始之前

工作原理

请求

响应

国际身份验证费率适用资格

请求

响应

说明

主要营业地点更新

请求

响应

说明

电话号码注册上限更新

请求

响应

说明

账户违规

请求

响应

说明

账户受限

请求

响应

说明

账户已停用

请求

响应

说明

账户恢复

请求

响应

说明

​功能介绍

​开始之前

​工作原理

​请求

​响应

​国际身份验证费率适用资格

​请求

​响应

​说明

​主要营业地点更新

​请求

​响应

​说明

​电话号码注册上限更新

​请求

​响应

​说明

​账户违规

​请求

​响应

​说明

​账户受限

​请求

​响应

​说明

​账户已停用

​请求

​响应

​说明

​账户恢复

​请求

​响应

​说明

功能介绍

开始之前

工作原理

请求

响应

国际身份验证费率适用资格

请求

响应

说明

主要营业地点更新

请求

响应

说明

电话号码注册上限更新

请求

响应

说明

账户违规

请求

响应

说明

账户受限

请求

响应

说明

账户已停用

请求

响应

说明

账户恢复

请求

响应

说明