> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp 商业账户更新 Webhook 示例
> 处理 WhatsApp 商业账户更新事件。
如需查看基于架构派生的完整目录，请参阅[所有示例](/zh/api-reference/guides/examples/webhook-examples/webhook-payload-examples)。
## 功能介绍
处理 WhatsApp 商业账户更新事件。
## 开始之前
* 在您的应用程序中创建一个公开的 HTTPS 端点。
* 为您需要的事件类型配置 YCloud Webhook 端点。
* 安全存储端点签名密钥。
* 确保事件处理具备幂等性。
## 工作原理
事件发生时，YCloud 会发送一个 HTTP `POST` 请求。请验证签名、持久化记录事件、返回 `2xx` 响应，并异步处理耗时任务。
## 请求
以下场景展示了发送到您的 Webhook URL 的请求。将事件 `id` 作为投递标识符，并使用 `type` 对载荷进行路由。
## 响应
在接收事件后返回 `2xx` 状态。
```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
有关端点设置、签名验证和重试机制，请参阅[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。
## 国际身份验证费率适用资格
自 2024 年 6 月 1 日起，我们将推出新的国际身份验证费率。该费率将适用于以下国家/地区：
* 2024 年 6 月 1 日 – 印度尼西亚（国家/地区拨号代码 +62，国家/地区代码 `ID`）
* 2024 年 7 月 1 日 – 印度（国家/地区拨号代码 +91，国家/地区代码 `IN`）
如需了解更多信息，请参阅[国际身份验证费率适用资格](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#eligibility)。
如果您的企业被视为符合国际费率适用资格，则会触发 `whatsapp.business_account.updated` Webhook。该 Webhook 将包含实行国际身份验证费率的每个国家/地区的开始时间。
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
如果消息按国际身份验证费率计费，则 [whatsapp.message.updated](/zh/api-reference/webhooks/test-webhooks#whatsappmessageupdated) Webhook 中的 `whatsappMessage.pricingCategory` 将设置为 `authentication_international`。
示例如下：
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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` 去重，并将耗时或易失败的工作转移到异步处理器。
## 主要营业地点更新
您的[主要营业地点](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#primary-business-location)是您的企业所在的国家/地区。自 2024 年 5 月 1 日起，它将显示在商务管理平台中的“主要营业地点”字段下。
如果 Meta 能够确定您的企业所在的国家/地区，我们将触发包含该国家/地区两位字母代码的 `whatsapp.business_account.updated` Webhook。
示例如下：
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 电话号码上限更新的示例：
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
通过 `type` 路由事件，通过 `id` 去重，并仅更新载荷中包含的上限字段。
## 账户违规
WhatsApp 商业账户最初会收到包含其所违反政策信息的警告。另请参阅 [WhatsApp 商业平台政策违规行为
](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/violations)。
示例如下：
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
通过 `type` 路由事件，通过 `id` 去重，并将耗时或易失败的工作转移到异步处理器。
## 账户受限
如果商业账户屡次违反 WhatsApp 商业服务条款，或触犯高风险政策类别（例如发送垃圾消息、成人内容、销售烟酒、毒品、赌博和不安全补剂），可能会面临持续时间逐渐增加的消息发送限制。
示例如下：
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
通过 `type` 路由事件，通过 `id` 去重，并将耗时或易失败的工作转移到异步处理器。
## 账户已停用
如果在多次收到警告以及功能受限或封禁后企业仍未作出整改，WhatsApp 商业账户可能会被停用。
示例如下：
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
通过 `type` 路由事件，通过 `id` 去重，并将耗时或易失败的工作转移到异步处理器。
## 账户恢复
您可以对 WhatsApp 商业账户的封禁决定提出申诉以恢复账户。申诉通过后，账户审核状态将变更为 `APPROVED`。
示例如下：
### 请求
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```
### 说明
按 `type` 路由事件，按 `id` 进行去重，并将耗时较长或易失败的任务移至异步处理器。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.