whatsapp.phone_number.quality_updated

使用 whatsapp.phone_number.quality_updated 在您的 Webhook 端点处理此事件。

触发条件

在 WhatsApp 商业电话号码的质量评级、消息发送限制或账户连接状态更新时触发。在配置 Webhook 端点时订阅 whatsapp.phone_number.quality_updated。请将电话号码级别的 messagingLimit 与描述所属业务资产组合共享限制的 whatsappBusinessManagerMessagingLimit 区分开来。示例层级并非账户默认值。有关质量或层级变更，请参阅 qualityUpdateEvent。当账户更新触发此事件时，updateEvent 用于标识 ACCOUNT_OFFBOARDED 或 ACCOUNT_RECONNECTED。

语法

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

{
  "id": "<ID>",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPhoneNumber": {
    "id": "<ID>",
    "phoneNumber": "<PHONE_NUMBER>",
    "displayPhoneNumber": "<DISPLAY_PHONE_NUMBER>",
    "wabaId": "<WABA_ID>",
    "qualityRating": "<QUALITY_RATING>",
    "messagingLimit": "<MESSAGING_LIMIT>",
    "whatsappBusinessManagerMessagingLimit": "<WHATSAPP_BUSINESS_MANAGER_MESSAGING_LIMIT>",
    "qualityUpdateEvent": "<QUALITY_UPDATE_EVENT>"
  }
}

参数

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

事件外层封装

参数	类型	必需	说明
`id`	string	是	事件的唯一标识符。最小长度：`6`。最大长度：`128`。
`type`	string	是	固定为 `whatsapp.phone_number.quality_updated`。
`apiVersion`	string	是	用于呈现此事件的 API 版本。
`createTime`	string (date-time)	是	此事件的创建时间，格式采用 RFC 3339。例如：`2022-06-01T12:00:00.000Z`。

事件载荷

参数	类型	必需	说明
`whatsappPhoneNumber`	object	否	事件特定的 `whatsappPhoneNumber` 载荷。

四个通用外层字段均为必需。载荷字段取决于具体的事件变体。在每个对象表格中，必需适用于其父对象存在的情况。可选字段可以省略；示例并不意味着字段是必需的。

whatsappPhoneNumber

参数	类型	必需	说明
`id`	string	否	电话号码 ID。
`phoneNumber`	string	否	采用 E.164 格式的电话号码。
`displayPhoneNumber`	string	否	显示电话号码。
`wabaId`	string	否	WhatsApp 商业账户 ID。
`qualityRating`	string	否	质量评级。取值为 `GREEN`、`YELLOW`、`RED` 或 `UNKNOWN` 之一。另请参阅电话号码质量评级。 `GREEN`：高质量。 `YELLOW`：中等质量。 `RED`：低质量。 `UNKNOWN`：质量未知。
`messagingLimit`	string	否	消息发送限制决定了每个电话号码在连续 24 小时内可以发起的业务发起会话的最大数量。另请参阅消息发送限制。 `TIER_NOT_SET`：未知限制。 `TIER_50`：在连续 24 小时内允许 50 次业务发起会话。 `TIER_250`：在连续 24 小时内允许 250 次业务发起会话。 `TIER_1K`：在连续 24 小时内允许与 1K 个独立客户进行业务发起会话。 `TIER_10K`：在连续 24 小时内允许与 10K 个独立客户进行业务发起会话。 `TIER_100K`：在连续 24 小时内允许与 100K 个独立客户进行业务发起会话。 `TIER_UNLIMITED`：在连续 24 小时内允许无限次业务发起会话。
`whatsappBusinessManagerMessagingLimit`	string	否	所属业务资产组合的消息发送限制。自 2025 年 10 月 7 日起，消息发送限制将改为按业务资产组合进行计算和设置，并由每个资产组合内的所有业务电话号码共享。另请参阅 phone_number_quality_update Webhook 参考文档。 `TIER_NOT_SET`：该业务电话号码尚未用于发送消息。 `TIER_50`：在连续 24 小时内限制 50 次业务发起会话。 `TIER_250`：在连续 24 小时内限制 250 次业务发起会话。 `TIER_2K`：在连续 24 小时内限制 2,000 次业务发起会话。 `TIER_10K`：在连续 24 小时内限制 10,000 次业务发起会话。 `TIER_100K`：在连续 24 小时内限制 100,000 次业务发起会话。 `TIER_UNLIMITED`：该业务电话号码拥有更高吞吐量，且业务发起会话次数无限制。
`qualityUpdateEvent`	string	否	表示向您发送通知时 WhatsApp 电话号码质量的更新事件类型。 `ONBOARDING`：通常在消息发送限制从 `TIER_NOT_SET` 变更为其他层级时触发。 `UPGRADE`：消息发送限制层级已升级。 `DOWNGRADE`：消息发送限制层级已降级。 `FLAGGED`：当质量评级处于低状态时会出现已标记状态。如果消息质量提升至高或中状态并保持 7 天，您的状态将恢复为 Connected。如果质量评级未见提升，您的状态仍会恢复为 Connected，但您会被调低至更低的消息发送限制层级。前往电话号码质量评级文档了解更多信息。 `UNFLAGGED`：电话号码状态从 `FLAGGED` 变更为 `CONNECTED`。
`updateEvent`	string	否	触发电话号码变更的账户更新。已知值为 `ACCOUNT_OFFBOARDED` 和 `ACCOUNT_RECONNECTED`。

示例

以下 JSON 是传递给您的接收端的主体。ID、电话号码及其他账户值仅供参考。从 whatsappPhoneNumber 中读取 qualityRating 和 qualityUpdateEvent。messagingLimit 描述电话号码层级；whatsappBusinessManagerMessagingLimit 描述所属业务资产组合的限制。

{
  "id": "evt_phone_number_quality_updated_123",
  "type": "whatsapp.phone_number.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+12025550124",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "qualityRating": "GREEN",
    "messagingLimit": "TIER_1K",
    "whatsappBusinessManagerMessagingLimit": "TIER_2K",
    "qualityUpdateEvent": "ONBOARDING"
  }
}

在验证签名并持久接收该事件后，返回 2xx 响应。耗时工作请异步处理。

HTTP/1.1 200 OK

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

开始使用

指南

接口

Webhook reference

whatsapp.phone_number.quality_updated

触发条件

语法

参数

事件外层封装

事件载荷

whatsappPhoneNumber

示例

​触发条件

​语法

​参数

​事件外层封装

​事件载荷

​whatsappPhoneNumber

​示例

触发条件

语法

参数

事件外层封装

事件载荷

whatsappPhoneNumber

示例