whatsapp.business_account.updated

在您的 Webhook 端点使用 whatsapp.business_account.updated 来处理此事件。

触发条件

在发生政策违规、WhatsApp 商业账户被封禁等情况时触发。在配置您的 Webhook 端点时订阅 whatsapp.business_account.updated。

语法

YCloud 会向您配置的 Webhook URL 发送 HTTP POST 请求。以下结构展示了一种载荷变体。尖括号中的值为占位符；其类型列在 Parameters 下。可选字段和其他变体在下方说明。

{
  "id": "<ID>",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappBusinessAccount": {
    "id": "<ID>",
    "name": "<NAME>",
    "updateEvent": "<UPDATE_EVENT>",
    "violationType": "<VIOLATION_TYPE>",
    "restrictions": [
      {
        "restrictionType": "<RESTRICTION_TYPE>",
        "expiration": "<EXPIRATION>"
      }
    ]
  }
}

参数

在处理 JSON 请求体之前，请验证 YCloud-Signature HTTP 请求头。参见签名验证。

事件外层结构 (Event envelope)

参数	类型	必填	说明
`id`	string	是	事件的唯一标识符。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.business_account.updated`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	创建此事件的时间，按 RFC 3339 格式化。例如 `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	否	向您发送通知以报告政策违规、WABA 被封禁等情况时，指示 WABA 的更新事件类型。 `DISABLED_UPDATE`：WhatsApp 商业账户已封禁。 `ACCOUNT_RESTRICTION`：WhatsApp 商业账户因违反政策而受到限制。 `ACCOUNT_VIOLATION`：WhatsApp 商业账户违反政策。 `PARTNER_REMOVED`：WhatsApp 商业账户已从合作伙伴连接中移除。 `PARTNER_APP_UNINSTALLED`：WhatsApp 商业账户合作伙伴应用已被卸载。 `AUTH_INTL_PRICE_ELIGIBILITY_UPDATE`：WhatsApp 商业账户符合国际身份验证费率资格。 `BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE`：商家的主要经营地已设置。 `BUSINESS_CAPABILITY_UPDATE`：Meta 报告了业务资产组 (Business Portfolio) 或 WABA 电话号码注册上限的变更。
`banState`	string	否	WhatsApp 商业账户的封禁状态。可选值：`SCHEDULE_FOR_DISABLE`、`DISABLE`、`REINSTATE`。
`banDate`	string	否	WABA 被封禁的日期。
`violationType`	string	否	用于报告对 WABA 实施的违规处罚。有关违规类型和说明，请参阅 Meta 的政策执行违规。Meta 可能会随时间推移更新此列表。有关 Utility Direct Send 违规类型和限制详情，请参阅 Meta 的账户限制 Webhook。
`restrictions`	object[]	否	当 WABA 违反 WhatsApp 商业平台政策时，用于报告对该 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`）另请参阅国际身份验证费率。
`primaryBusinessLocation`	string	否	您的主要业务经营地是指您企业所在的国家/地区。自 2024 年 5 月 1 日起，它将显示在业务管理平台的“Primary Business Location”（主要业务经营地）字段下。ISO 3166-1 alpha-2 国家/地区代码。

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。例如 `2022-06-01T12:00:00.000Z`。

whatsappBusinessAccount.authIntlRateEligibilityCountries[]

参数	类型	必填	说明
`countryCode`	string	否	ISO 3166-1 alpha-2 国家/地区代码。
`startTime`	string (date-time)	否	新开通的身份验证对话开始适用国际身份验证费率的日期，格式符合 RFC 3339。例如 `2024-07-01T00:00:00.000Z`。

示例

以下 JSON 是发送给接收方的消息体。ID、电话号码和其他账户值仅供参考。

Utility Direct Send 限制事件

在多次滥用类别后，Meta 对 Utility Direct Send 实施了为期 7 天的限制。

{
  "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"
      }
    ]
  }
}

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

{
  "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"
      }
    ]
  }
}

主要业务经营地更新

{
  "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"
  }
}

电话号码注册上限更新

{
  "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
  }
}

账户违规

{
  "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"
  }
}

账户受限

{
  "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"
      }
    ]
  }
}

账户已停用

{
  "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"
  }
}

账户恢复

{
  "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/1.1 200 OK

有关场景演示，请参阅带注释的示例。

开始使用

指南

接口

Webhook reference

whatsapp.business_account.updated

触发条件

语法

参数

事件外层结构 (Event envelope)

事件载荷

whatsappBusinessAccount

示例

​触发条件

​语法

​参数

​事件外层结构 (Event envelope)

​事件载荷

​whatsappBusinessAccount

​示例

触发条件

语法

参数

事件外层结构 (Event envelope)

事件载荷

whatsappBusinessAccount

示例