> ## 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

> Occurs when a WhatsApp business phone number's quality, messaging limit, or account connection state is updated.

Use `whatsapp.phone_number.quality_updated` to handle this event at your webhook endpoint.

## Triggers

Occurs when a WhatsApp business phone number's quality, messaging limit, or account connection state is updated.

Subscribe to `whatsapp.phone_number.quality_updated` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

Keep the phone-number `messagingLimit` separate from `whatsappBusinessManagerMessagingLimit`, which describes the owning business portfolio’s shared limit. Sample tiers are not account defaults.

Read `qualityUpdateEvent` for quality or tier changes. When an account update triggers this event, `updateEvent` identifies `ACCOUNT_OFFBOARDED` or `ACCOUNT_RECONNECTED`.

## Syntax

YCloud sends an HTTP `POST` request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under **Parameters**. Optional fields and other variants are described below.

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

## Parameters

Validate the `YCloud-Signature` HTTP header before you process the JSON body. See [signature validation](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Event envelope

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique ID for the event. Minimum length: `6`. Maximum length: `128`. |
| `type` | string | Yes | Always `whatsapp.phone_number.quality_updated`. |
| `apiVersion` | string | Yes | The API version used to render this event. |
| `createTime` | string (date-time) | Yes | The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. |

### Event payload

| Parameter | Type | Required | Description |
| - | - | - | - |
| `whatsappPhoneNumber` | object | No | Event-specific `whatsappPhoneNumber` payload. |

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, **Required** applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

#### whatsappPhoneNumber

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | No | Phone number ID. |
| `phoneNumber` | string | No | Phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format. |
| `displayPhoneNumber` | string | No | Display phone number. |
| `wabaId` | string | No | WhatsApp Business Account ID. |
| `qualityRating` | string | No | Quality rating. One of `GREEN`, `YELLOW`, `RED`, or `UNKNOWN`. See also [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001).<ul><li>`GREEN`: High quality.</li><li>`YELLOW`: Medium quality.</li><li>`RED`: Low quality.</li><li>`UNKNOWN`: Unknown quality.</li></ul> |
| `messagingLimit` | string | No | Messaging limits determine the maximum number of business-initiated conversations each phone number can start in a rolling 24-hour period. See also [Messaging Limits](https://developers.facebook.com/docs/whatsapp/messaging-limits).<ul><li>`TIER_NOT_SET`: Unknown limit.</li><li>`TIER_50`: 50 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_250`: 250 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_1K`: 1K business-initiated conversations with unique customers in a rolling 24-hour period.</li><li>`TIER_10K`: 10K business-initiated conversations with unique customers in a rolling 24-hour period.</li><li>`TIER_100K`: 100K business-initiated conversations with unique customers in a rolling 24-hour period.</li><li>`TIER_UNLIMITED`: An unlimited number of business-initiated conversations in a rolling 24-hour period.</li></ul> |
| `whatsappBusinessManagerMessagingLimit` | string | No | The owning business portfolio's messaging limit. Starting October 7, 2025, messaging limits will instead be calculated and set on a business portfolio basis, and will be shared by all business phone numbers within each portfolio. See also [phone\_number\_quality\_update webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update).<ul><li>`TIER_NOT_SET`: The business phone number has not been used to send a message yet.</li><li>`TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period.</li><li>`TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations.</li></ul> |
| `qualityUpdateEvent` | string | No | Indicates the update event type of WhatsApp phone number quality when a notification is sent to you.<ul><li>`ONBOARDING`: Typically when the messaging limit changes from `TIER_NOT_SET` to another tier.</li><li>`UPGRADE`: Messaging limit tier upgraded.</li><li>`DOWNGRADE`: Messaging limit tier downgraded.</li><li>`FLAGGED`: Flagged status occurs when the quality rating reaches a low state. If the message quality improves to a high or medium state and maintains this for 7 days, your status will return to Connected. If the quality rating doesn't improve, your status will still return to Connected, but you'll be placed in a lower messaging limit tier. Learn more on [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001) docs.</li><li>`UNFLAGGED`: Phone number status changes from `FLAGGED` to `CONNECTED`.</li></ul> |
| `updateEvent` | string | No | Account update that triggered the phone-number change. Known values are `ACCOUNT_OFFBOARDED` and `ACCOUNT_RECONNECTED`. |

## Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

Read qualityRating and qualityUpdateEvent from whatsappPhoneNumber. messagingLimit describes the phone-number tier; whatsappBusinessManagerMessagingLimit describes the owning business portfolio's limit.

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

After verifying the signature and durably accepting the event, return a `2xx` response. Process slow work asynchronously.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/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.