whatsapp.phone_number.quality_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. 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.

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

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. 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 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. `GREEN`: High quality. `YELLOW`: Medium quality. `RED`: Low quality. `UNKNOWN`: Unknown quality.
`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. `TIER_NOT_SET`: Unknown limit. `TIER_50`: 50 business-initiated conversations in a rolling 24-hour period. `TIER_250`: 250 business-initiated conversations in a rolling 24-hour period. `TIER_1K`: 1K business-initiated conversations with unique customers in a rolling 24-hour period. `TIER_10K`: 10K business-initiated conversations with unique customers in a rolling 24-hour period. `TIER_100K`: 100K business-initiated conversations with unique customers in a rolling 24-hour period. `TIER_UNLIMITED`: An unlimited number of business-initiated conversations in a rolling 24-hour period.
`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. `TIER_NOT_SET`: The business phone number has not been used to send a message yet. `TIER_50`: Messaging limit of 50 business-initiated conversations in a rolling 24-hour period. `TIER_250`: Messaging limit of 250 business-initiated conversations in a rolling 24-hour period. `TIER_2K`: Messaging limit of 2,000 business-initiated conversations in a rolling 24-hour period. `TIER_10K`: Messaging limit of 10,000 business-initiated conversations in a rolling 24-hour period. `TIER_100K`: Messaging limit of 100,000 business-initiated conversations in a rolling 24-hour period. `TIER_UNLIMITED`: The business phone number has higher throughput with unlimited business-initiated conversations.
`qualityUpdateEvent`	string	No	Indicates the update event type of WhatsApp phone number quality when a notification is sent to you. `ONBOARDING`: Typically when the messaging limit changes from `TIER_NOT_SET` to another tier. `UPGRADE`: Messaging limit tier upgraded. `DOWNGRADE`: Messaging limit tier downgraded. `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 docs. `UNFLAGGED`: Phone number status changes from `FLAGGED` to `CONNECTED`.
`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.

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

For scenario walkthroughs, see annotated examples.

Getting Started

Guides

Endpoints

Webhook reference

whatsapp.phone_number.quality_updated

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappPhoneNumber

Example

​Triggers

​Syntax

​Parameters

​Event envelope

​Event payload

​whatsappPhoneNumber

​Example

Triggers

Syntax

Parameters

Event envelope

Event payload

whatsappPhoneNumber

Example