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

> Se produce cuando se actualiza la calidad, el límite de mensajería o el estado de conexión de la cuenta de un número de teléfono comercial de WhatsApp.

Usa `whatsapp.phone_number.quality_updated` para gestionar este evento en tu endpoint de webhook.

## Desencadenadores

Se produce cuando se actualiza la calidad, el límite de mensajería o el estado de conexión de la cuenta de un número de teléfono comercial de WhatsApp.

Suscríbete a `whatsapp.phone_number.quality_updated` cuando [configures tu endpoint de webhook](https://docs.ycloud.com/es/api-reference/guides/api-fundamentals/configure-webhooks.md).

Mantén el `messagingLimit` del número de teléfono separado de `whatsappBusinessManagerMessagingLimit`, que describe el límite compartido de la cartera comercial propietaria. Los niveles de muestra no son valores predeterminados de la cuenta.

Lee `qualityUpdateEvent` para ver los cambios de calidad o de nivel. Cuando una actualización de cuenta desencadena este evento, `updateEvent` identifica `ACCOUNT_OFFBOARDED` o `ACCOUNT_RECONNECTED`.

## Sintaxis

YCloud envía una solicitud HTTP `POST` a tu URL de webhook configurada. La siguiente estructura muestra una variante del payload. Los valores entre corchetes angulares son marcadores de posición; sus tipos se indican en **Parámetros**. Los campos opcionales y otras variantes se describen a continuación.

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

## Parámetros

Valida el encabezado HTTP `YCloud-Signature` antes de procesar el cuerpo JSON. Consulta la [validación de firmas](https://docs.ycloud.com/es/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Sobre del evento

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `id` | string | Sí | ID único del evento. Longitud mínima: `6`. Longitud máxima: `128`. |
| `type` | string | Sí | Siempre `whatsapp.phone_number.quality_updated`. |
| `apiVersion` | string | Sí | La versión de la API utilizada para procesar este evento. |
| `createTime` | string (date-time) | Sí | La fecha y hora en la que se creó este evento, con formato [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). Por ejemplo, `2022-06-01T12:00:00.000Z`. |

### Payload del evento

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `whatsappPhoneNumber` | object | No | Payload `whatsappPhoneNumber` específico del evento. |

Los cuatro campos comunes del sobre son obligatorios. Los campos del payload dependen de la variante del evento. En cada tabla de objetos, **Requerido** se aplica cuando su objeto principal está presente. Los campos opcionales se pueden omitir; una muestra no hace que un campo sea obligatorio.

#### whatsappPhoneNumber

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `id` | string | No | ID del número de teléfono. |
| `phoneNumber` | string | No | Número de teléfono en formato [E.164](https://en.wikipedia.org/wiki/E.164). |
| `displayPhoneNumber` | string | No | Número de teléfono visible. |
| `wabaId` | string | No | ID de la cuenta de WhatsApp Business. |
| `qualityRating` | string | No | Calificación de calidad. Uno de los siguientes valores: `GREEN`, `YELLOW`, `RED` o `UNKNOWN`. Consulta también [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001).<ul><li>`GREEN`: calidad alta.</li><li>`YELLOW`: calidad media.</li><li>`RED`: calidad baja.</li><li>`UNKNOWN`: calidad desconocida.</li></ul> |
| `messagingLimit` | string | No | Los límites de mensajería determinan el número máximo de conversaciones iniciadas por la empresa que cada número de teléfono puede iniciar en un período móvil de 24 horas. Consulta también [Límites de mensajería](https://developers.facebook.com/docs/whatsapp/messaging-limits).<ul><li>`TIER_NOT_SET`: Límite desconocido.</li><li>`TIER_50`: 50 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_250`: 250 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_1K`: 1K conversaciones iniciadas por la empresa con clientes únicos en un período móvil de 24 horas.</li><li>`TIER_10K`: 10K conversaciones iniciadas por la empresa con clientes únicos en un período móvil de 24 horas.</li><li>`TIER_100K`: 100K conversaciones iniciadas por la empresa con clientes únicos en un período móvil de 24 horas.</li><li>`TIER_UNLIMITED`: Un número ilimitado de conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li></ul> |
| `whatsappBusinessManagerMessagingLimit` | string | No | El límite de mensajería de la cartera comercial propietaria. A partir del 7 de octubre de 2025, los límites de mensajería se calcularán y establecerán por cartera comercial, y serán compartidos por todos los números de teléfono comerciales dentro de cada cartera. Consulta también la [referencia del webhook phone\_number\_quality\_update](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/phone_number_quality_update).<ul><li>`TIER_NOT_SET`: El número de teléfono comercial aún no se ha utilizado para enviar un mensaje.</li><li>`TIER_50`: Límite de mensajería de 50 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_250`: Límite de mensajería de 250 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_2K`: Límite de mensajería de 2000 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_10K`: Límite de mensajería de 10 000 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_100K`: Límite de mensajería de 100 000 conversaciones iniciadas por la empresa en un período móvil de 24 horas.</li><li>`TIER_UNLIMITED`: El número de teléfono comercial tiene un mayor rendimiento con conversaciones ilimitadas iniciadas por la empresa.</li></ul> |
| `qualityUpdateEvent` | string | No | Indica el tipo de evento de actualización de la calidad del número de teléfono de WhatsApp cuando se te envía una notificación.<ul><li>`ONBOARDING`: Por lo general, cuando el límite de mensajería cambia de `TIER_NOT_SET` a otro nivel.</li><li>`UPGRADE`: Se actualizó el nivel de límite de mensajería a uno superior.</li><li>`DOWNGRADE`: Se redujo el nivel de límite de mensajería a uno inferior.</li><li>`FLAGGED`: El estado Marcado (Flagged) ocurre cuando la calificación de calidad alcanza un nivel bajo. Si la calidad del mensaje mejora a un estado alto o medio y se mantiene así durante 7 días, tu estado volverá a Connected. Si la calificación de calidad no mejora, tu estado aún volverá a Connected, pero pasarás a un nivel de límite de mensajería inferior. Obtén más información en la documentación sobre [Phone Number Quality Rating](https://www.facebook.com/business/help/896873687365001).</li><li>`UNFLAGGED`: El estado del número de teléfono cambia de `FLAGGED` a `CONNECTED`.</li></ul> |
| `updateEvent` | string | No | Actualización de la cuenta que desencadenó el cambio del número de teléfono. Los valores conocidos son `ACCOUNT_OFFBOARDED` y `ACCOUNT_RECONNECTED`. |

## Ejemplo

El siguiente JSON es el cuerpo entregado a tu receptor. Los ID, los números de teléfono y otros valores de cuenta son ilustrativos.

Lee qualityRating y qualityUpdateEvent de whatsappPhoneNumber. messagingLimit describe el nivel del número de teléfono; whatsappBusinessManagerMessagingLimit describe el límite de la cartera comercial propietaria.

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

Después de verificar la firma y aceptar de forma duradera el evento, devuelve una respuesta `2xx`. Procesa las tareas lentas de forma asíncrona.

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

Para ver tutoriales de escenarios paso a paso, consulta los [ejemplos comentados](https://docs.ycloud.com/es/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.