Ejemplos de webhook de cuenta de WhatsApp Business actualizada

Para consultar el catálogo exhaustivo derivado del esquema, consulta todos los ejemplos.

Qué es

Gestiona eventos de actualización de cuentas de WhatsApp Business.

Antes de empezar

Crea un endpoint HTTPS público en tu aplicación.
Configura un endpoint de webhook de YCloud para los tipos de eventos que necesites.
Almacena el secreto de firma del endpoint de forma segura.
Haz que el procesamiento de eventos sea idempotente.

Cómo funciona

YCloud envía una solicitud HTTP POST cuando ocurre el evento. Verifica la firma, registra el evento de forma duradera, responde con un estado 2xx y procesa las tareas lentas de forma asíncrona.

Solicitud

Los escenarios a continuación muestran solicitudes enviadas a tu URL de webhook. Trata el identificador de evento id como el identificador de entrega y usa type para enrutar el payload.

Respuesta

Devuelve un estado 2xx tras aceptar el evento.

HTTP/1.1 200 OK

Para la configuración del endpoint, validación de firmas y comportamiento de reintentos, consulta Configurar webhooks.

Elegibilidad para tarifa internacional de autenticación

A partir del 1 de junio de 2024, introducimos una nueva tarifa internacional de autenticación. Esta tarifa se aplicará en los siguientes países:

1 de junio de 2024 – Indonesia (código de país de llamada +62, código de país ID)
1 de julio de 2024 – India (código de país de llamada +91, código de país IN)

Para obtener más información, consulta Elegibilidad para tarifa internacional de autenticación . Se activará un webhook de whatsapp.business_account.updated si tu negocio se considera elegible para tarifas internacionales. El webhook incluirá las horas de inicio para cada país que tenga una tarifa internacional de autenticación.

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
    "authIntlRateEligibilityCountries": [
      {
        "countryCode": "IN",
        "startTime": "2024-07-01T00:00:00.000Z"
      },
      {
        "countryCode": "ID",
        "startTime": "2024-07-01T00:00:00.000Z"
      }
    ]
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Si un mensaje se factura con la tarifa internacional de autenticación, el whatsappMessage.pricingCategory en los webhooks whatsapp.message.updated se establecerá en authentication_international. Aquí tienes un ejemplo:

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2024-07-01T00:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "wabaId": "whatsapp-business-account-id",
    "from": "+447901614024",
    "to": "+447901614024",
    "status": "sent",
    "type": "template",
    "template": {
      "name": "login_otp",
      "language": {
        "code": "862031",
        "policy": "deterministic"
      }
    },
    "conversation": {
      "id": "8078ed05301c40a08d3d1845c94ca18b",
      "originType": "authentication",
      "expireTime": "2024-07-01T00:00:00.000Z"
    },
    "pricingCategory": "authentication_international",
    "totalPrice": 0.085,
    "currency": "USD",
    "sendTime": "2024-07-01T00:00:00.000Z"
  }
}

Explicación

Enruta el evento mediante type, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

Actualización de la ubicación comercial principal

Tu ubicación comercial principal es el país donde se encuentra tu empresa. Aparecerá en el Administrador comercial en el campo Ubicación comercial principal a partir del 1 de mayo de 2024. Si Meta puede determinar el país donde se encuentra tu negocio, activaremos un webhook whatsapp.business_account.updated con el código de país de dos dígitos. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
    "primaryBusinessLocation": "US"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

Actualización del límite de registro de números de teléfono

Meta envía una actualización de capacidad del negocio para una WABA cuando cambia el límite de registro de números de teléfono de la cuenta WABA o del portafolio comercial correspondiente. YCloud lo entrega como whatsapp.business_account.updated con updateEvent=BUSINESS_CAPABILITY_UPDATE. El webhook es a nivel de WABA: whatsappBusinessAccount.id es el ID de WABA de la entrada del webhook de Meta. Meta actualmente reporta maxPhoneNumbersPerBusiness y maxPhoneNumbersPerWaba en actualizaciones independientes. No los trates como mutuamente excluyentes: procesa cada campo de forma independiente y acepta ambos si una actualización futura los incluye juntos. El valor 0 es válido. Aquí tienes un ejemplo de una actualización de límite de números de teléfono de WABA:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2026-09-23T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "BUSINESS_CAPABILITY_UPDATE",
    "maxPhoneNumbersPerWaba": 25
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento por type, deduplícalo por id y actualiza únicamente el campo de límite incluido en el payload.

Infracción de cuenta

Las cuentas de WhatsApp Business recibirán inicialmente una advertencia con información sobre la política que han infringido. Consulta también Infracciones a las políticas de la plataforma de WhatsApp Business
. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_VIOLATION",
    "violationType": "SPAM"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

Restricción de cuenta

Si las cuentas de negocio infringen repetidamente las Condiciones del servicio de WhatsApp Business o categorías de políticas de alto riesgo, como el envío de spam, contenido para adultos, venta de alcohol y tabaco, drogas, apuestas y suplementos no seguros, pueden empezar a sufrir restricciones de mensajería que aumentarán gradualmente en duración. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "ACCOUNT_RESTRICTION",
    "restrictions": [
      {
        "restrictionType": "RESTRICTED_ADD_PHONE_NUMBER_ACTION",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_BIZ_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
      {
        "restrictionType": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING",
        "expiration": "2024-09-01T12:00:00.000Z"
      },
    ]
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

Cuenta desactivada

Las cuentas de WhatsApp Business pueden ser desactivadas si el negocio no realiza cambios tras múltiples advertencias y límites o bloqueos de funciones. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banDate": "September 19, 2024",
    "banState": "DISABLE"
  }
}

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento mediante type, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.

Restablecimiento de cuenta

Puedes apelar la decisión de suspensión de la cuenta de WhatsApp Business para restablecerla. Una vez aprobada, el estado de revisión de la cuenta cambia a APPROVED. Aquí tienes un ejemplo:

Solicitud

{
  "id": "evt_djeIQXaQPQyUcRFi",
  "type": "whatsapp.business_account.updated",
  "apiVersion": "v2",
  "createTime": "2024-06-01T00:00:00.000Z",
  "whatsappBusinessAccount": {
    "id": "106681...",
    "updateEvent": "DISABLED_UPDATE",
    "banState": "REINSTATE",
    "banDate": "December 27, 2024",
    "accountReviewStatus": "APPROVED"
  }
}

Respuesta

Confirma la entrega después de aceptar el evento de forma duradera.

HTTP/1.1 200 OK

Explicación

Enruta el evento por type, deduplícalo por id y traslada el trabajo lento o propenso a errores a un procesador asíncrono.

Primeros pasos

Guías

Endpoints

Webhooks

Ejemplos de webhook de cuenta de WhatsApp Business actualizada

Qué es

Antes de empezar

Cómo funciona

Solicitud

Respuesta

Elegibilidad para tarifa internacional de autenticación

Solicitud

Respuesta

Explicación

Actualización de la ubicación comercial principal

Solicitud

Respuesta

Explicación

Actualización del límite de registro de números de teléfono

Solicitud

Respuesta

Explicación

Infracción de cuenta

Solicitud

Respuesta

Explicación

Restricción de cuenta

Solicitud

Respuesta

Explicación

Cuenta desactivada

Solicitud

Respuesta

Explicación

Restablecimiento de cuenta

Solicitud

Respuesta

Explicación

​Qué es

​Antes de empezar

​Cómo funciona

​Solicitud

​Respuesta

​Elegibilidad para tarifa internacional de autenticación

​Solicitud

​Respuesta

​Explicación

​Actualización de la ubicación comercial principal

​Solicitud

​Respuesta

​Explicación

​Actualización del límite de registro de números de teléfono

​Solicitud

​Respuesta

​Explicación

​Infracción de cuenta

​Solicitud

​Respuesta

​Explicación

​Restricción de cuenta

​Solicitud

​Respuesta

​Explicación

​Cuenta desactivada

​Solicitud

​Respuesta

​Explicación

​Restablecimiento de cuenta

​Solicitud

​Respuesta

​Explicación

Qué es

Antes de empezar

Cómo funciona

Solicitud

Respuesta

Elegibilidad para tarifa internacional de autenticación

Solicitud

Respuesta

Explicación

Actualización de la ubicación comercial principal

Solicitud

Respuesta

Explicación

Actualización del límite de registro de números de teléfono

Solicitud

Respuesta

Explicación

Infracción de cuenta

Solicitud

Respuesta

Explicación

Restricción de cuenta

Solicitud

Respuesta

Explicación

Cuenta desactivada

Solicitud

Respuesta

Explicación

Restablecimiento de cuenta

Solicitud

Respuesta

Explicación