whatsapp.phone_number.quality_updated

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

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

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. 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.
`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. `GREEN`: calidad alta. `YELLOW`: calidad media. `RED`: calidad baja. `UNKNOWN`: calidad desconocida.
`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. `TIER_NOT_SET`: Límite desconocido. `TIER_50`: 50 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_250`: 250 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_1K`: 1K conversaciones iniciadas por la empresa con clientes únicos en un período móvil de 24 horas. `TIER_10K`: 10K conversaciones iniciadas por la empresa con clientes únicos en un período móvil de 24 horas. `TIER_100K`: 100K conversaciones iniciadas por la empresa con clientes únicos en un período móvil de 24 horas. `TIER_UNLIMITED`: Un número ilimitado de conversaciones iniciadas por la empresa en un período móvil de 24 horas.
`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. `TIER_NOT_SET`: El número de teléfono comercial aún no se ha utilizado para enviar un mensaje. `TIER_50`: Límite de mensajería de 50 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_250`: Límite de mensajería de 250 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_2K`: Límite de mensajería de 2000 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_10K`: Límite de mensajería de 10 000 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_100K`: Límite de mensajería de 100 000 conversaciones iniciadas por la empresa en un período móvil de 24 horas. `TIER_UNLIMITED`: El número de teléfono comercial tiene un mayor rendimiento con conversaciones ilimitadas iniciadas por la empresa.
`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. `ONBOARDING`: Por lo general, cuando el límite de mensajería cambia de `TIER_NOT_SET` a otro nivel. `UPGRADE`: Se actualizó el nivel de límite de mensajería a uno superior. `DOWNGRADE`: Se redujo el nivel de límite de mensajería a uno inferior. `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. `UNFLAGGED`: El estado del número de teléfono cambia de `FLAGGED` a `CONNECTED`.
`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.

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

Para ver tutoriales de escenarios paso a paso, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.phone_number.quality_updated

Desencadenadores

Sintaxis

Parámetros

Sobre del evento

Payload del evento

whatsappPhoneNumber

Ejemplo

​Desencadenadores

​Sintaxis

​Parámetros

​Sobre del evento

​Payload del evento

​whatsappPhoneNumber

​Ejemplo

Desencadenadores

Sintaxis

Parámetros

Sobre del evento

Payload del evento

whatsappPhoneNumber

Ejemplo