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 sutype 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 HTTPPOST 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 elid del evento como el identificador de entrega y usa type para enrutar la carga útil.
Respuesta
Devuelve un estado2xx 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
Usawhatsapp.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 dewhatsappBusinessAccount 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)
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.whatsappMessage.pricingCategory en los webhooks whatsapp.message.updated se establecerá en authentication_international.
Aquí tienes un ejemplo:
Explicación
Enruta el evento portype, 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 webhookwhatsapp.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 portype, 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 comowhatsapp.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 mediantetype, 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 eventowhatsapp.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 mediantetype, 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 útilACCOUNT_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 mediantetype, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.
Restricción de Utility Direct Send
Recibeswhatsapp.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
UsawhatsappBusinessAccount.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 mediantetype, 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 aAPPROVED.
Aquí tienes un ejemplo:
Solicitud
Respuesta
Confirma la entrega tras aceptar el evento de forma duradera.Explicación
Enruta el evento mediantetype, deduplícalo por id y traslada el trabajo lento o propenso a fallos a un procesador asíncrono.
Revisión de la cuenta comercial
Usawhatsapp.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 conid. 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
Usawhatsapp.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
UsawhatsappPhoneNumber.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
Usawhatsapp.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
Leedecision 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
Usawhatsapp.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
LeequalityRating (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
Usawhatsapp.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 siendowhatsapp.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. Incluyerevoked 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.
