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

Qué es

Gestiona eventos de revisión, actualización y eliminación de cuentas comerciales, además de eliminaciones de números de teléfono, revisiones del nombre para mostrar, calidad y actualizaciones de Business Username. Enruta cada carga útil según su type de evento exacto: los eventos de cuenta usan whatsappBusinessAccount, mientras que los eventos de número de teléfono usan whatsappPhoneNumber.

Antes de comenzar

  • Crea un endpoint público HTTPS en tu aplicación.
  • Configura un endpoint de webhook de YCloud para los tipos de eventos que necesites.
  • Guarda de forma segura el secreto de firma del endpoint.
  • 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, devuelve una respuesta 2xx y procesa las tareas lentas de forma asíncrona.

Solicitud

Los siguientes escenarios muestran las solicitudes enviadas a tu URL de webhook. Trata el id del evento como el identificador de entrega y usa type para enrutar la carga útil.

Respuesta

Devuelve un estado 2xx tras aceptar el evento.
Para la configuración del endpoint, la validación de la firma y el comportamiento de reintento, consulta Configurar webhooks.

Eliminación de cuenta

Usa whatsapp.business_account.deleted para gestionar un evento de eliminación de cuenta de WhatsApp Business. Lee whatsappBusinessAccount.id para identificar la WABA afectada.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Los campos de eliminación aparecen directamente dentro de whatsappBusinessAccount cuando están disponibles. Los valores conocidos de removedReason incluyen: Conserva los valores de motivo e iniciador desconocidos. Deduplica las entregas mediante el id del evento y tolera los campos de eliminación omitidos.

Elegibilidad para la tarifa de autenticación internacional

A partir del 1 de junio de 2024, introduciremos una nueva tarifa de autenticación internacional. Esta tarifa se aplicará en los siguientes países:
  • 1 de junio de 2024 – Indonesia (código de llamada del país +62, código de país ID)
  • 1 de julio de 2024 – India (código de llamada del país +91, código de país IN)
Para más información, consulta Elegibilidad para la tarifa de autenticación internacional . Se activará un webhook whatsapp.business_account.updated si tu empresa se considera apta para tarifas internacionales. El webhook incluirá las horas de inicio para cada país que tenga una tarifa de autenticación internacional.

Solicitud

Respuesta

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

Explicación

Enruta el evento por type, deduplícalo por id y traslada las tareas lentas o propensas a errores a un procesador asíncrono.

Actualización de la ubicación comercial principal

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

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Enruta el evento por type, deduplícalo por id y traslada las tareas lentas o propensas a errores 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 comercial para una WABA cuando cambia el límite de registro de números de teléfono del Business Portfolio o de la WABA correspondiente. YCloud la entrega como whatsapp.business_account.updated con updateEvent=BUSINESS_CAPABILITY_UPDATE. El webhook es a nivel de WABA: whatsappBusinessAccount.id es el ID de la 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 por separado y acepta ambos si una actualización futura los incluye juntos. Un valor de 0 es válido. Aquí tienes un ejemplo de una actualización del límite de números de teléfono de una WABA:

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

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

Infracción de la cuenta

Cuando recibas un evento whatsapp.business_account.updated con whatsappBusinessAccount.updateEvent establecido en ACCOUNT_VIOLATION, inspecciona whatsappBusinessAccount.violationType para identificar la infracción de la política reportada. Consulta Infracciones en la aplicación de políticas de Meta para conocer los tipos y descripciones de las infracciones. Meta puede actualizar esta lista con el tiempo. Aquí tienes un ejemplo:

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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 la cuenta

Si las cuentas de empresa infringen reiteradamente 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 o suplementos no seguros, es posible que comiencen a experimentar restricciones de mensajería cuya duración aumentará de forma gradual. Para Utility Direct Send, consulta Notificaciones de Direct Send para ver una carga útil ACCOUNT_RESTRICTION de YCloud. Consulta Webhook para restricción de cuentas de Meta para conocer los tipos de infracciones y los detalles de las restricciones específicos de Direct Send. Aquí tienes un ejemplo:

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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 Utility Direct Send

Recibes whatsapp.business_account.updated cuando Meta restringe Utility Direct Send tras un uso indebido reiterado de las categorías. Este ejemplo muestra una restricción de siete días.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Usa whatsappBusinessAccount.id para identificar la WABA afectada y pausar su flujo de trabajo de Utility Direct Send. Lee violationType para conocer el motivo, restrictions[].restrictionType para la función afectada y restrictions[].expiration para la fecha de expiración cuando se proporcione. La revisión aprobada de una plantilla no anula automáticamente una restricción a nivel de cuenta. Consulta Restricciones y notificaciones de Direct Send.

Cuenta inhabilitada

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

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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 la cuenta

Puedes apelar la decisión de bloqueo 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

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

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.

Revisión de la cuenta comercial

Usa whatsapp.business_account.reviewed cuando se haya revisado una cuenta de WhatsApp Business.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Identifica la WABA con id. Lee decision para conocer la decisión de la revisión (APPROVED o REJECTED) y accountReviewStatus para el estado de revisión de la cuenta cuando se proporcione. No enrutes este evento como whatsapp.business_account.updated.

Eliminación de un número de teléfono

Usa whatsapp.phone_number.deleted cuando se elimine un número de teléfono comercial de WhatsApp.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Usa whatsappPhoneNumber.id para identificar el número de teléfono eliminado y wabaId para asociarlo con su cuenta. Este es un evento a nivel de número de teléfono; no lo trates como la eliminación de toda la WABA.

Revisión del nombre visible del número de teléfono

Usa whatsapp.phone_number.name_updated cuando se apruebe o rechace el nombre visible de un número de teléfono comercial.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Lee decision y los campos de estado del nombre proporcionados. newNameStatus describe la nueva solicitud de nombre visible, requestedVerifiedName identifica el último nombre solicitado y rejectionReason describe el motivo del rechazo cuando esté presente. La revisión del nombre visible es independiente de una actualización del nombre de usuario comercial.

Actualización de la calidad del número de teléfono

Usa whatsapp.phone_number.quality_updated para cambios en el estado relacionado con la calidad de un número de teléfono comercial.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

Lee qualityRating (GREEN, YELLOW o RED) y qualityUpdateEvent para comprender la actualización. messagingLimit es el nivel del número de teléfono; whatsappBusinessManagerMessagingLimit es el límite de la cartera comercial propietaria. Mantén estos campos por separado y actualiza solo los valores proporcionados en el evento.

Business Username activado

Usa whatsapp.phone_number.business_username_updated para sincronizar el Business Username de un número de teléfono.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

businessUsername es el nombre de usuario activo sin un @ inicial. Lee businessUsernameStatus e businessUsernameUpdatedAt con el id del número de teléfono. No confundas este valor con el nombre visible verificado.

Solicitud de Business Username reservada

Un Business Username activo puede seguir en uso mientras se reserva una solicitud de reemplazo.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

En este ejemplo, businessUsername permanece como acme.support mientras que requestedBusinessUsername es acme.help. El estado reserved describe la solicitud pendiente, no la activación del reemplazo. Acepta el valor heredado pending_review al leer eventos antiguos; las nuevas escrituras utilizan reserved.

Business Username revocado

El tipo de evento sigue siendo whatsapp.phone_number.business_username_updated. businessUsernameContext es una cadena opcional. Un valor de revoked describe una notificación de revocación; es independiente de businessUsernameStatus.

Solicitud

Respuesta

Confirma la entrega tras aceptar el evento de forma duradera.

Explicación

YCloud actualiza el nombre de usuario y el estado actuales desde Meta antes de generar este evento. Incluye revoked solo cuando el nombre de usuario devuelto por una consulta actual correcta a Meta coincide con el nombre de usuario de la notificación de revocación. Si la notificación hace referencia al nombre de usuario A pero Meta ahora devuelve B, un evento emitido contiene B y omite el contexto obsoleto de revoked. El contexto también se omite cuando la notificación no tiene contexto. Las advertencias históricas que se muestran en la consola no se reproducen en este campo. Una notificación simulada en sentido ascendente no reemplaza el nombre de usuario ni el estado devueltos por Meta.