whatsapp.phone_number.business_username_updated

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

Desencadenadores

Se produce cuando se actualiza el nombre de usuario de empresa (Business Username) de un número de teléfono comercial de WhatsApp. Suscríbete a whatsapp.phone_number.business_username_updated cuando configures tu endpoint de webhook.

Sintaxis

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

{
  "id": "<ID>",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPhoneNumber": {
    "id": "<ID>",
    "wabaId": "<WABA_ID>",
    "phoneNumber": "<PHONE_NUMBER>",
    "businessUsername": "<BUSINESS_USERNAME>",
    "businessUsernameStatus": "<BUSINESS_USERNAME_STATUS>",
    "businessUsernameContext": "<BUSINESS_USERNAME_CONTEXT>"
  }
}

Parámetros

Valida el encabezado HTTP YCloud-Signature antes de procesar el cuerpo JSON. Consulta validación de firmas.

Envoltorio del evento

Parámetro	Tipo	Obligatorio	Descripción
`id`	string	Sí	ID único para el evento. Longitud mínima: `6`. Longitud máxima: `128`.
`type`	string	Sí	Siempre `whatsapp.phone_number.business_username_updated`.
`apiVersion`	string	Sí	La versión de la API utilizada para representar este evento.
`createTime`	string (date-time)	Sí	La fecha y hora en que se creó este evento, con formato en RFC 3339. P. ej., `2022-06-01T12:00:00.000Z`.

Payload del evento

Parámetro	Tipo	Obligatorio	Descripción
`whatsappPhoneNumber`	object	No	Payload de `whatsappPhoneNumber` específico del evento.

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

whatsappPhoneNumber

Parámetro	Tipo	Obligatorio	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 para mostrar.
`wabaId`	string	No	ID de la cuenta de WhatsApp Business.
`businessUsername`	string	No	Business Username activo para este número de teléfono. El valor es un nombre de usuario simple sin `@`.
`businessUsernameStatus`	string	No	Estado del Business Username para un número de teléfono comercial de WhatsApp. `not_set`: no existe un Business Username activo ni pendiente. `active`: un Business Username está activo. `reserved`: un Business Username solicitado está reservado por Meta y aún puede estar en revisión. `pending_review`: valor de compatibilidad heredado para una solicitud en revisión. Las nuevas escrituras usan `reserved`. Si existe un nombre de usuario activo mientras una nueva solicitud está reservada o en revisión, `businessUsernameStatus` es `reserved`, `businessUsername` contiene el nombre de usuario que aún está activo y `requestedBusinessUsername` contiene el nombre de usuario solicitado.
`requestedBusinessUsername`	string	No	Último Business Username solicitado que aún está en revisión. Este valor puede coexistir con un `businessUsername` activo mientras la nueva solicitud esté pendiente.
`businessUsernameContext`	string	No	Contexto opcional para esta notificación de nombre de usuario. `revoked` solo aparece cuando el nombre de usuario devuelto por una consulta actual correcta a Meta coincide con esta notificación de revocación. Se omite para una revocación obsoleta o una notificación sin contexto. Este campo no expone advertencias históricas de la página.
`businessUsernameUpdatedAt`	string (date-time)	No	La fecha y hora en que se actualizó por última vez el estado del Business Username.

Ejemplo

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

Nombre de usuario comercial revocado y reemplazado

{
  "id": "evt_business_username_revoked_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-10-10T08:00:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "wabaId": "whatsapp-business-account-id",
    "phoneNumber": "+12025550124",
    "businessUsername": "autogenerated_name",
    "businessUsernameStatus": "active",
    "businessUsernameContext": "revoked"
  }
}

Evento de actualización del nombre de usuario comercial del número de teléfono de WhatsApp

Carga útil de ejemplo cuando el nombre de usuario comercial de un número de teléfono de WhatsApp pasa a estar activo

{
  "id": "evt_business_username_updated_123",
  "type": "whatsapp.phone_number.business_username_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",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "active",
    "businessUsernameUpdatedAt": "2026-05-26T12:00:00.000Z"
  }
}

Evento de reserva de nombre de usuario comercial del número de teléfono de WhatsApp

Carga útil de ejemplo cuando un número de teléfono de WhatsApp tiene una solicitud de nombre de usuario comercial reservado

{
  "id": "evt_business_username_pending_123",
  "type": "whatsapp.phone_number.business_username_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:30:00.000Z",
  "whatsappPhoneNumber": {
    "id": "1234567890123456",
    "phoneNumber": "+12025550124",
    "displayPhoneNumber": "+1 631-555-1111",
    "wabaId": "whatsapp-business-account-id",
    "businessUsername": "acme.support",
    "businessUsernameStatus": "reserved",
    "requestedBusinessUsername": "acme.help",
    "businessUsernameUpdatedAt": "2026-05-26T12:30:00.000Z"
  }
}

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 guías paso a paso de escenarios, consulta los ejemplos comentados.

Primeros pasos

Guías

Endpoints

Webhook reference

whatsapp.phone_number.business_username_updated

Desencadenadores

Sintaxis

Parámetros

Envoltorio del evento

Payload del evento

whatsappPhoneNumber

Ejemplo

​Desencadenadores

​Sintaxis

​Parámetros

​Envoltorio del evento

​Payload del evento

​whatsappPhoneNumber

​Ejemplo

Desencadenadores

Sintaxis

Parámetros

Envoltorio del evento

Payload del evento

whatsappPhoneNumber

Ejemplo