> ## 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.business_account.updated > 在发生政策违规、WhatsApp 商业账户被封禁等情况时触发。 在您的 Webhook 端点使用 `whatsapp.business_account.updated` 来处理此事件。 ## 触发条件 在发生政策违规、WhatsApp 商业账户被封禁等情况时触发。 在[配置您的 Webhook 端点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)时订阅 `whatsapp.business_account.updated`。 ## 语法 YCloud 会向您配置的 Webhook URL 发送 HTTP `POST` 请求。以下结构展示了一种载荷变体。尖括号中的值为占位符；其类型列在 **Parameters** 下。可选字段和其他变体在下方说明。 ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "", "type": "whatsapp.business_account.updated", "apiVersion": "", "createTime": "", "whatsappBusinessAccount": { "id": "", "name": "", "updateEvent": "", "violationType": "", "restrictions": [ { "restrictionType": "", "expiration": "" } ] } } ``` ## 参数 在处理 JSON 请求体之前，请验证 `YCloud-Signature` HTTP 请求头。参见[签名验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。 ### 事件外层结构 (Event envelope) | 参数 | 类型 | 必填 | 说明 | | - | - | - | - | | `id` | string | 是 | 事件的唯一标识符。最小长度：`6`。最大长度：`128`。 | | `type` | string | 是 | 固定为 `whatsapp.business_account.updated`。 | | `apiVersion` | string | 是 | 用于呈现此事件的 API 版本。 | | `createTime` | string (date-time) | 是 | 创建此事件的时间，按 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式化。例如 `2022-06-01T12:00:00.000Z`。 | ### 事件载荷 | 参数 | 类型 | 必填 | 说明 | | - | - | - | - | | `whatsappBusinessAccount` | object | 否 | 特定事件的 `whatsappBusinessAccount` 载荷。 | 四个通用 envelope 字段是必填的。载荷字段取决于事件变体。在每个对象表中， **必填** 仅在其父对象存在时适用。可选字段可以省略；示例中包含某个字段并不代表该字段为必填项。 #### whatsappBusinessAccount | 参数 | 类型 | 必填 | 说明 | | - | - | - | - | | `id` | string | 否 | WhatsApp 商业账户 ID。 | | `name` | string | 否 | 便于识别和区分 WhatsApp 商业账户的易记名称。 | | `accountReviewStatus` | string | 否 | WhatsApp 商业账户审核状态。可选值：`PENDING`、`APPROVED`、`REJECTED`。 | | `updateEvent` | string | 否 | 向您发送通知以报告[政策违规](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement)、WABA 被封禁等情况时，指示 WABA 的更新事件类型。
  • `DISABLED_UPDATE`：WhatsApp 商业账户已封禁。
  • `ACCOUNT_RESTRICTION`：WhatsApp 商业账户因违反政策而受到限制。
  • `ACCOUNT_VIOLATION`：WhatsApp 商业账户违反政策。
  • `PARTNER_REMOVED`：WhatsApp 商业账户已从合作伙伴连接中移除。
  • `PARTNER_APP_UNINSTALLED`：WhatsApp 商业账户合作伙伴应用已被卸载。
  • `AUTH_INTL_PRICE_ELIGIBILITY_UPDATE`：WhatsApp 商业账户符合[国际身份验证费率](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates)资格。
  • `BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE`：商家的[主要经营地](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates#primary-business-location)已设置。
  • `BUSINESS_CAPABILITY_UPDATE`：Meta 报告了业务资产组 (Business Portfolio) 或 WABA 电话号码注册上限的变更。
| | `banState` | string | 否 | WhatsApp 商业账户的封禁状态。可选值：`SCHEDULE_FOR_DISABLE`、`DISABLE`、`REINSTATE`。 | | `banDate` | string | 否 | WABA 被封禁的日期。 | | `violationType` | string | 否 | 用于报告对 WABA 实施的违规处罚。有关违规类型和说明，请参阅 Meta 的[政策执行违规](https://developers.facebook.com/documentation/business-messaging/whatsapp/policy-enforcement-violations)。Meta 可能会随时间推移更新此列表。有关 Utility Direct Send 违规类型和限制详情，请参阅 Meta 的[账户限制 Webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/direct-send/integrity-and-content-guidelines#webhook-for-account-restriction)。 | | `restrictions` | object\[] | 否 | 当 WABA 违反 [WhatsApp 商业平台政策](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement) 时，用于报告对该 WABA 实施的限制。 | | `maxPhoneNumbersPerBusiness` | integer (int32) | 否 | 当 Meta 报告 Business Portfolio（业务资产组合）电话号码注册上限时，包含在带有 `updateEvent=BUSINESS_CAPABILITY_UPDATE` 的 `whatsapp.business_account.updated` Webhook 中。Meta 目前将此字段与 `maxPhoneNumbersPerWaba` 分开报告，但如果未来的更新将它们合并在一起，使用者必须同时处理这两者。 | | `maxPhoneNumbersPerWaba` | integer (int32) | 否 | 当 Meta 报告 WABA 电话号码注册上限时，包含在带有 `updateEvent=BUSINESS_CAPABILITY_UPDATE` 的 `whatsapp.business_account.updated` Webhook 中。Meta 目前将此字段与 `maxPhoneNumbersPerBusiness` 分开报告，但如果未来的更新将它们合并在一起，使用者必须同时处理这两者。 | | `authIntlRateEligibilityCountries` | object\[] | 否 | 自 2024 年 6 月 1 日起，我们将更新身份验证费率卡，并推出全新的国际身份验证费率。该费率将适用于以下国家/地区：
  • 2024 年 6 月 1 日 – 印度尼西亚（国家/地区呼叫代码 +62，国家/地区代码 `ID`）
  • 2024 年 7 月 1 日 – 印度（国家/地区呼叫代码 +91，国家/地区代码 `IN`）
另请参阅[国际身份验证费率](https://developers.facebook.com/docs/whatsapp/pricing/authentication-international-rates)。 | | `primaryBusinessLocation` | string | 否 | 您的主要业务经营地是指您企业所在的国家/地区。自 2024 年 5 月 1 日起，它将显示在业务管理平台的“Primary Business Location”（主要业务经营地）字段下。[ISO 3166-1 alpha-2 国家/地区代码](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。 | > [accordion] whatsappBusinessAccount.restrictions\[] > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `restrictionType` | string | 否 | 限制类型。可选值：`RESTRICTED_ADD_PHONE_NUMBER_ACTION`、`RESTRICTED_BIZ_INITIATED_MESSAGING`、`RESTRICTED_CUSTOMER_INITIATED_MESSAGING`、`RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES`。 | > | `expiration` | string (date-time) | 否 | 此限制到期的时间，格式符合 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)。例如 `2022-06-01T12:00:00.000Z`。 | > [accordion] whatsappBusinessAccount.authIntlRateEligibilityCountries\[] > > | 参数 | 类型 | 必填 | 说明 | > | - | - | - | - | > | `countryCode` | string | 否 | [ISO 3166-1 alpha-2 国家/地区代码](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。 | > | `startTime` | string (date-time) | 否 | 新开通的身份验证对话开始适用国际身份验证费率的日期，格式符合 [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339)。例如 `2024-07-01T00:00:00.000Z`。 | ## 示例 以下 JSON 是发送给接收方的消息体。ID、电话号码和其他账户值仅供参考。 > [accordion] Utility Direct Send 限制事件 > > 在多次滥用类别后，Meta 对 Utility Direct Send 实施了为期 7 天的限制。 > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "id": "evt_direct_send_restriction_123", > "type": "whatsapp.business_account.updated", > "apiVersion": "v2", > "createTime": "2026-09-17T08:00:00.000Z", > "whatsappBusinessAccount": { > "id": "whatsapp-business-account-id", > "name": "Example business", > "updateEvent": "ACCOUNT_RESTRICTION", > "violationType": "DIRECT_SEND_UTILITY_CATEGORY_ABUSE_STRIKE_1", > "restrictions": [ > { > "restrictionType": "RESTRICTED_DIRECT_SEND_UTILITY_TEMPLATES", > "expiration": "2026-09-24T08:00:00.000Z" > } > ] > } > } > ``` > [accordion] 国际身份验证费率适用资格 > > ```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" > } > ] > } > } > ``` > [accordion] 主要业务经营地更新 > > ```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" > } > } > ``` > [accordion] 电话号码注册上限更新 > > ```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 > } > } > ``` > [accordion] 账户违规 > > ```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": "SCAM" > } > } > ``` > [accordion] 账户受限 > > ```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" > } > ] > } > } > ``` > [accordion] 账户已停用 > > ```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" > } > } > ``` > [accordion] 账户恢复 > > ```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" > } > } > ``` 在验证签名并持久化接收事件后，返回 `2xx` 响应。耗时较长的工作请以异步方式处理。 ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK ``` 有关场景演示，请参阅[带注释的示例](https://docs.ycloud.com/zh/api-reference/guides/examples/webhook-examples/whatsapp-business-account-updated-webhook-examples)。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.