> ## 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.phone_number.quality_updated

> 在 WhatsApp 商业电话号码的质量评级、消息发送限制或账户连接状态更新时触发。

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

## 触发条件

在 WhatsApp 商业电话号码的质量评级、消息发送限制或账户连接状态更新时触发。

在[配置 Webhook 端点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)时订阅 `whatsapp.phone_number.quality_updated`。

请将电话号码级别的 `messagingLimit` 与描述所属业务资产组合共享限制的 `whatsappBusinessManagerMessagingLimit` 区分开来。示例层级并非账户默认值。

有关质量或层级变更，请参阅 `qualityUpdateEvent`。当账户更新触发此事件时，`updateEvent` 用于标识 `ACCOUNT_OFFBOARDED` 或 `ACCOUNT_RECONNECTED`。

## 语法

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 请求头。参见[签名验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

### 事件外层封装

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

### 事件载荷

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

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

#### whatsappPhoneNumber

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

## 示例

以下 JSON 是传递给您的接收端的主体。ID、电话号码及其他账户值仅供参考。

从 whatsappPhoneNumber 中读取 qualityRating 和 qualityUpdateEvent。messagingLimit 描述电话号码层级；whatsappBusinessManagerMessagingLimit 描述所属业务资产组合的限制。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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 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.