Resumen
Los webhooks en Wati le permiten recibir actualizaciones en tiempo real sobre los mensajes y sus estados mediante el envío de datos de eventos a su servidor. Esta guía explica qué eventos puede rastrear, cómo configurar un webhook y cómo funcionan las devoluciones de llamada (callbacks) basadas en sesiones para que pueda procesar de forma fiable la actividad de los mensajes en su sistema.
Instrucciones
¿Qué eventos pueden capturar los webhooks de Wati?
Los webhooks de Wati notifican a su sistema externo cuando ocurren eventos específicos en su cuenta de Wati. Cuando ocurre un evento, Wati envía una carga útil (payload) de callback a la URL del webhook que usted configuró. Su sistema puede usar esta información para rastrear mensajes, monitorear estados de mensajes y mantenerse actualizado sobre los cambios en la cuenta de WhatsApp.
Wati admite los siguientes eventos de webhook:
Eventos de mensajes y conversaciones
Message Received (Mensaje recibido) – Cuando un cliente envía un mensaje.
New Contact Message (Mensaje de nuevo contacto) – Cuando un nuevo contacto envía un mensaje.
Session Message Sent (Mensaje de sesión enviado) – Cuando se envía un mensaje de sesión.
Template Message Sent (Mensaje de plantilla enviado) – Cuando se envía un mensaje de plantilla.
Sent Message is DELIVERED (Mensaje enviado entregado) – Cuando un mensaje enviado es entregado.
Sent Message is Read (Mensaje enviado leído) – Cuando un mensaje enviado es leído.
Sent Message is REPLIED (Mensaje enviado respondido) – Cuando un cliente responde a un mensaje enviado.
Session Message Failed (Error en mensaje de sesión) – Cuando el envío de un mensaje de sesión falla.
Template Message FAILED (Error en mensaje de plantilla) – Cuando el envío de un mensaje de plantilla falla.
Eventos de plantillas
Template Status Update (Actualización de estado de plantilla) – Cuando cambia el estado de una plantilla.
Template Quality Update (Actualización de calidad de plantilla) – Cuando cambia la calificación de calidad de una plantilla.
Template Category Update (Actualización de categoría de plantilla) – Cuando cambia la categoría de una plantilla.
Eventos de cuentas de WhatsApp y números de teléfono
WhatsApp Account Review Updated (Revisión de cuenta de WhatsApp actualizada) – Cuando cambia el estado de revisión de una cuenta de WhatsApp.
Phone Number Quality Update (Actualización de calidad de número de teléfono) – Cuando cambia la calificación de calidad de un número de teléfono.
WABA Account Deleted (Cuenta WABA eliminada) – Cuando se elimina una cuenta de WhatsApp Business (WABA).
WABA Account Content Updated (Contenido de cuenta WABA actualizado) – Cuando se actualiza el contenido de una WABA.
Phone Number Deleted (Número de teléfono eliminado) – Cuando se elimina un número de teléfono.
Business Capability Updated (Capacidad empresarial actualizada) – Cuando se actualiza una capacidad empresarial.
Otros eventos
Chatbot Triggered (Chatbot activado) – Cuando se activa un chatbot.
CTA URL Clicked (Clic en URL de CTA) – Cuando un cliente hace clic en una URL de llamada a la acción (CTA).
CTA Button Clicked (BSUID) (Clic en botón de CTA) – Cuando un cliente hace clic en un botón de CTA.
Call Status (Estado de llamada) – Cuando cambia el estado de una llamada de WhatsApp.
Contact Request Response (Respuesta a solicitud de contacto) – Cuando un cliente responde a una solicitud de contacto.
WhatsApp Payment Captured (Pago de WhatsApp capturado) – Cuando se captura un pago de WhatsApp.
Eventos de webhook adicionales para BSUID
Wati también admite eventos de webhook adicionales para BSUID (Business-Scoped User ID).
Estos incluyen:
Message Received (BSUID)
New Contact Message (BSUID)
Session Message Sent (BSUID)
Session Message Sent v2 (BSUID)
Template Message Sent (BSUID)
Template Message Sent v2 (BSUID)
Chatbot Triggered (BSUID)
CTA Button Clicked (BSUID)
Call Status (BSUID)
Para obtener detalles sobre eventos individuales y sus cargas útiles de callback, consulte nuestra documentación de webhooks.
Cómo agregar un webhook en Wati
Siga estos pasos para configurar un webhook:
Inicie sesión en su panel de control de Wati.
Vaya a Connectors (Conectores) y haga clic en Webhooks.
Haga clic en Add Webhook (Agregar webhook).

Ingrese su URL de webhook completa.
Establezca el estado en Enabled (Habilitado). Los estados de los webhooks pueden ser Enabled (Habilitado), Disabled (Deshabilitado) y Defective (Defectuoso).
Seleccione los eventos que desea capturar.

Haga clic en Save (Guardar).
Cómo probar su webhook
Después de agregar el webhook, puede probar la conexión:
Utilice la opción Trigger sample callback (Disparar callback de muestra).

Wati enviará una carga útil de muestra a la URL de su webhook.

Verifique que su servidor reciba y procese la carga útil correctamente.
Entendiendo los webhooks basados en sesiones
En la API de WhatsApp Business, las conversaciones se rastrean como sesiones de 24 horas. Una sesión comienza cuando se entrega un mensaje de la empresa.
Tipos de sesiones
Sesión activa
Tanto la empresa como el cliente han intercambiado al menos un mensaje.
Ejemplo: Una empresa envía un mensaje de plantilla y el cliente responde.
Sesión inactiva
Solo una de las partes ha enviado un mensaje y la otra no ha respondido.
Ejemplo: Una empresa envía un mensaje de plantilla, pero el cliente no responde.
Nota: Las devoluciones de llamada (callbacks) de webhook pueden variar dependiendo de si la sesión está activa o inactiva.
Respuesta del webhook y lógica de reintento
Para garantizar una entrega fiable, su webhook debe responder correctamente.
Su servidor debe devolver una respuesta
200 OKpara confirmar que se recibió el evento.
Si no se recibe una respuesta
200:Wati volverá a intentar enviar el evento.
Los reintentos pueden ocurrir hasta 144 veces.
Los intentos de reintento se ejecutan en intervalos de 10 minutos.
Si hay más de 100 fallos consecutivos:
El webhook se marca como Defective (Defectuoso).
Recibirá una notificación por correo electrónico.
Si todos los intentos de reintento fallan, el evento dejará de enviarse.
Mejores prácticas
Asegúrese de que su punto final de webhook esté siempre disponible y sea receptivo.
Registre las cargas útiles entrantes para facilitar la depuración.
Gestione eventos duplicados, ya que los reintentos pueden enviar la misma carga útil más de una vez.
Valide las solicitudes entrantes para asegurarse de que provengan de Wati.
Esta configuración le ayuda a mantener sus sistemas sincronizados con la actividad de mensajería en tiempo real en Wati.
Preguntas frecuentes (FAQs)
Eventos y configuración de webhooks
1. ¿Qué tipos de eventos pueden capturar los webhooks de Wati?
Los webhooks de Wati pueden capturar eventos de mensajes y conversaciones, eventos de plantillas, eventos de cuentas de WhatsApp y números de teléfono, y otros eventos. Cuando ocurre un evento compatible, Wati envía una carga útil de callback a la URL del webhook configurada.
2. ¿Qué estados de webhook están disponibles en Wati?
Wati admite tres estados de webhook:
Enabled (Habilitado) – El webhook está habilitado.
Disabled (Deshabilitado) – El webhook está deshabilitado.
Defective (Defectuoso) – El webhook ha sido marcado como defectuoso tras fallos repetidos en la entrega.
3. ¿Wati admite eventos de webhook adicionales para BSUID?
Sí. Wati admite eventos de webhook adicionales para Business-Scoped User ID (BSUID). Consulte la documentación de webhooks para obtener detalles sobre los eventos BSUID individuales y sus cargas útiles de callback.
Webhooks basados en sesiones
4. ¿Cuál es la diferencia entre una sesión activa y una sesión inactiva?
Una sesión activa ocurre cuando tanto la empresa como el cliente han intercambiado al menos un mensaje.
Una sesión inactiva ocurre cuando solo una de las partes ha enviado un mensaje y la otra parte no ha respondido.
5. ¿Las devoluciones de llamada de webhook varían entre sesiones activas e inactivas?
Sí. Las devoluciones de llamada (callbacks) de webhook pueden variar dependiendo de si la sesión de WhatsApp está activa o inactiva. Una sesión de WhatsApp comienza cuando se entrega un mensaje de empresa y dura 24 horas.
Respuesta del webhook y resolución de problemas
6. ¿Qué sucede si mi punto final de webhook no devuelve una respuesta 200 OK?
Su servidor debe devolver una respuesta 200 OK para confirmar que ha recibido un evento de webhook. Si Wati no recibe esta respuesta, intentará reenviar el evento hasta 144 veces en intervalos de 10 minutos.
Si hay más de 100 fallos consecutivos, Wati marca el webhook como Defective (Defectuoso) y envía una notificación por correo electrónico. Si todos los intentos de reintento fallan, Wati deja de enviar el evento.
7. ¿Cómo puedo mejorar la fiabilidad del webhook?
Mantenga su punto final de webhook disponible y receptivo, registre las cargas útiles entrantes para facilitar la depuración, gestione eventos duplicados para evitar procesar la misma carga útil varias veces y valide las solicitudes entrantes para asegurarse de que provengan de Wati.
Did this answer your question?