Ir al contenido principal

Cómo realizar el seguimiento de la entrega de mensajes de plantilla y el estado del mensaje utilizando webhooks de Wati

Resumen

Cuando envía mensajes de plantilla mediante la API de Wati, es posible que desee realizar un seguimiento de su estado (como enviado, entregado, leído, respondido o fallido) utilizando webhooks en lugar de depender únicamente de los análisis de campañas integrados de Wati.

Después de enviar campañas a través de la API, siempre puede ver su rendimiento en Información general de la campaña en Wati. Sin embargo, también puede utilizar los webhooks de Wati para realizar un seguimiento del estado del mensaje y de los eventos de entrega de dichas campañas en tiempo real a través de sus propios sistemas.

Este enfoque le ayuda a supervisar el rendimiento de los mensajes, solucionar problemas de entrega y gestionar las interacciones con los clientes a través de sus aplicaciones. Esta guía explica cómo enviar un mensaje de plantilla y realizar el seguimiento de su ciclo de vida mediante webhooks.

Nota: Para obtener más información sobre los webhooks de Wati, consulte la documentación para desarrolladores de Wati.

Instrucciones

Enviar un mensaje de plantilla

Para enviar un mensaje de plantilla mediante la API de Wati, utilice el endpoint sendTemplateMessage V2.

Ejemplo de solicitud cURL

curl --location 'https://live-mt-server.wati.io/{tenant_id}/api/v2/sendTemplateMessage?whatsappNumber=<whatsappNumber>' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "template_name": "update_for_you",
  "broadcast_name": "JPTestBroadcast",
  "parameters": []
}'

Ejemplo de respuesta de API

{
  "result": true,
  "error": null,
  "templateName": "update_for_you",
  "receivers": [
    {
      "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
      "waId": "<whatsappNumber>",
      "isValidWhatsAppNumber": true,
      "errors": []
    }
  ],
  "parameters": []
}

Campo clave

  • localMessageId: un identificador único que se utiliza para realizar el seguimiento del mensaje a través de los eventos de webhook. Guarde este valor, ya que vincula todas las actualizaciones de estado del mensaje.

Realizar el seguimiento del estado del mensaje mediante webhooks

Una vez enviado el mensaje, Wati envía eventos de webhook para cada actualización de estado. Utilice el localMessageId para hacer coincidir estos eventos con el mensaje original.

1. Mensaje de plantilla enviado

  • Se activa cuando: El mensaje se envía correctamente desde Wati

  • Evento: templateMessageSent_v2

  • Estado: SENT (Enviado)

Ejemplo de carga útil (payload) de webhook

{
  "eventType": "templateMessageSent_v2_bsuid",
  "localMessageId": "84689938-5e2-877821d672c2",
  "id": "693fd8ee21f81",
  "whatsappMessageId": "wamid.HBgNODEYEjQ3RDMzQzM2QjM3QjU1ODQ4RQA=",
  "templateId": "6929b",
  "templateName": "test_jm4",
  "created": "2025-12-15T09:46:23.4083984Z",
  "conversationId": "68b68470e93cc",
  "ticketId": "693fd6ab545f82",
  "text": "Make your messages personal using variables like name and get more replies!",
  "operatorEmail": "[email protected]",
  "waId": "86151285",
  "type": "template",
  "statusString": "SENT",
  "sourceType": "WEB",
  "headerLink": null,
  "headerType": null,
  "channelId": null,
  "channelPhoneNumber": "174742",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob"
}

El webhook de plantilla enviada ahora incluye información de botones

El webhook de Plantilla enviada ahora incluye la información de los botones configurados en la plantilla de WhatsApp. Esto le permite identificar el texto del botón asociado con un mensaje de plantilla enviado.

Esta función está disponible para los clientes en los planes Pro, Business y Enterprise.

¿Qué información de botón se incluye?

La carga útil del webhook puede incluir la siguiente información de botones de la plantilla de WhatsApp:

  • Texto del botón de respuesta rápida

  • Texto del botón de enlace

Cuando recupera información de la plantilla a través de la API, la respuesta también incluye el texto del botón configurado para la plantilla.

2. Mensaje entregado

  • Se activa cuando: El mensaje se entrega al destinatario

  • Evento: sentMessageDELIVERED_v2

  • Estado: Delivered (Entregado)

Ejemplo de carga útil (payload) de webhook

{
  "eventType": "sentMessageDELIVERED_v2",
  "statusString": "Delivered",
  "localMessageId": "16bf77ae-79e8-691eb4b",
  "id": "693fd65f99391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEzMzg4Nzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba32b3349e",
  "ticketId": "693f7a0a8545f54",
  "text": "hello",
  "type": "text",
  "timestamp": "1765791326",
  "assigneeId": "65a105b5cf65262",
  "operatorEmail": "derre.ai",
  "channelId": null,
  "channelPhoneNumber": "17742"
}

3. Mensaje leído

  • Se activa cuando: El destinatario lee el mensaje

  • Evento: sentMessageREAD_v2

  • Estado: Read (Leído)

Ejemplo de carga útil (payload) de webhook

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

4. Mensaje respondido

  • Se activa cuando: El destinatario responde al mensaje

  • Evento: sentMessageREPLIED_v2

  • Estado: Replied (Respondido)

Ejemplo de carga útil (payload) de webhook

{
  "eventType": "sentMessageREPLIED_v2",
  "statusString": "Replied",
  "localMessageId": "16bf77ae-79e691eb4b",
  "id": "693fd65f961dc81779391640",
  "whatsappMessageId": "wamid.HBgNODYxMzEABEYEjVCNzg2MDU0OEM0NTYxRTlBMwA=",
  "conversationId": "68cba3db12b3349e",
  "ticketId": "693fd64d1d45f54",
  "text": "hello",
  "type": "text",
  "timestamp": "17651326",
  "assigneeId": "65a10905cf65262",
  "operatorEmail": "[email protected]",
  "channelId": null,
  "channelPhoneNumber": "174742"
}

5. Mensaje recibido

  • Se activa cuando: Un usuario envía un mensaje a su número de Wati

  • Evento: messageReceived

  • Estado: Received (Recibido)

Caso de uso:

  • Hacer un seguimiento de las respuestas de los usuarios

  • Capturar clics en botones de respuesta rápida de los mensajes de plantilla

Ejemplo de carga útil (payload) de webhook

{
  "eventType": "messageReceived",
  "statusString": "Received",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "text": "Hello, I need help!",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

6. Mensaje de plantilla fallido

  • Se activa cuando: El mensaje no se puede enviar

  • Evento: templateMessageFailed

  • Estado: Failed (Fallido)

Ejemplo de carga útil (payload) de webhook

{
  "eventType": "templateMessageFailed",
  "statusString": "Failed",
  "localMessageId": "fd29c1f-9033-59b2-7d72-5ac964c4c8a7",
  "failedCode": "131026",
  "failedDetail": "Message undeliverable",
  "id": "66b2531d4931581381944612",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "conversationId": "66b1fb044045cedb1f19538e",
  "ticketId": "66bdfba190194752bb7326d7",
  "text": null,
  "type": "template",
  "timestamp": "1665645642",
  "assigneeId": null,
  "operatorEmail": "[email protected]"
}

Cómo configurar webhooks en Wati

Siga estos pasos para empezar a recibir eventos de webhook:

  • Inicie sesión en su cuenta de Wati

  • Vaya a Connectors (Conectores) → Webhooks

  • Haga clic en Add Webhook (Añadir webhook)

  • Introduzca la URL de su webhook

  • Establezca el estado en Enabled (Habilitado)

  • Seleccione los eventos requeridos:

    • Template Message Sent (Mensaje de plantilla enviado)

    • Delivered (Entregado)

    • Read (Leído)

    • Replied (Respondido)

    • Failed (Fallido)

Notas finales

  • Guarde siempre el localMessageId al enviar mensajes

  • Úselo para asignar todos los eventos de webhook al mismo mensaje

  • Combine varios eventos de webhook para crear un ciclo de vida completo del mensaje

Al configurar correctamente los webhooks, puede realizar un seguimiento fiable de cada mensaje de plantilla enviado a través de Wati y tomar medidas basadas en actualizaciones en tiempo real.

Preguntas frecuentes (FAQs)

Envío y seguimiento de mensajes de plantilla

1. ¿Cómo envío un mensaje de plantilla mediante la API de Wati?

Utilice el endpoint sendTemplateMessage V2 para enviar un mensaje de plantilla a través de la API de Wati.

2. ¿Qué es el localMessageId y por qué debo guardarlo?

El localMessageId es un identificador único para un mensaje. Guárdelo porque Wati lo utiliza para vincular los eventos de webhook al mensaje original y realizar un seguimiento de su estado a lo largo de todo su ciclo de vida.

3. ¿Cómo puedo realizar el seguimiento del estado de los mensajes de plantilla mediante webhooks de Wati?

Configure los webhooks de Wati para recibir eventos en tiempo real para los mensajes de plantilla. Utilice el localMessageId para hacer coincidir cada evento de webhook con el mensaje original.

4. ¿Qué eventos de webhook realizan el seguimiento del ciclo de vida de los mensajes de plantilla?

Los eventos de webhook disponibles son:

  • templateMessageSent_v2 — el mensaje se envió correctamente.

  • sentMessageDELIVERED_v2 — el mensaje fue entregado.

  • sentMessageREAD_v2 — el destinatario leyó el mensaje.

  • sentMessageREPLIED_v2 — el destinatario respondió al mensaje.

  • templateMessageFailed — el mensaje no pudo enviarse.

  • messageReceived — un usuario envió un mensaje a su número de Wati.

5. ¿Para qué se puede utilizar el webhook messageReceived?

El webhook messageReceived se puede utilizar para realizar un seguimiento de las respuestas de los usuarios y capturar los clics en los botones de respuesta rápida de los mensajes de plantilla.

6. ¿Qué información de botones se incluye en el webhook de Plantilla enviada?

El webhook de Plantilla enviada puede incluir el texto del botón de respuesta rápida y el texto del botón de enlace configurados en la plantilla de WhatsApp. La respuesta de la API para la información de la plantilla también incluye el texto del botón configurado.

7. ¿Qué planes de Wati admiten la información de botones en el webhook de Plantilla enviada?

La función de información de botones está disponible para los clientes en los planes Pro, Business y Enterprise.

8. ¿Cómo configuro los webhooks en Wati para realizar el seguimiento de los mensajes de plantilla?

Vaya a Connectors → Webhooks en su cuenta de Wati, haga clic en Add Webhook, introduzca la URL de su webhook, establezca el estado en Enabled y seleccione los eventos requeridos: Template Message Sent, Delivered, Read, Replied y Failed.

9. ¿Cómo puedo realizar un seguimiento del ciclo de vida completo de un mensaje de plantilla?

Almacene el localMessageId al enviar el mensaje y úselo para asignar todos los eventos de webhook relacionados. Combinar estos eventos le permite realizar un seguimiento de si el mensaje se envió, entregó, leyó, respondió o falló.

Artículos relacionados
¿Ha quedado contestada tu pregunta?