Resumen

Cuando envías mensajes de plantilla mediante la API de Wati, puedes realizar un seguimiento de su estado (enviado, entregado, leído, respondido o fallido) usando webhooks en tiempo real, 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, puedes ver su rendimiento en Resumen de campañas en Wati. Los webhooks te permiten realizar un seguimiento del estado de los mensajes y de los eventos de entrega a través de tus propios sistemas a medida que ocurren.

Nota: Para obtener la documentación de referencia completa sobre los webhooks, consulta la documentación para desarrolladores de Wati.

Instrucciones

Enviar un mensaje de plantilla

Utiliza el endpoint v3 para enviar un mensaje de plantilla. Se recomienda usar v3 para todas las integraciones nuevas.

Endpoint: POST https://live-mt-server.wati.io/api/ext/v3/messageTemplates/send

Las rutas v3 no incluyen /{tenantId}/. Crea un token de API con alcance en Connector > API > Create API Token con el alcance messagetemplatev3:write.

Ejemplo de solicitud cURL:

curl --location 'https://live-mt-server.wati.io/api/ext/v3/messageTemplates/send' \
--header 'Authorization: Bearer <Token>' \
--header 'Content-Type: application/json' \
--data '{
  "template_name": "update_for_you",
  "broadcast_name": "JPTestBroadcast",
  "channel_number": "85264318722",
  "target": "<whatsappNumber>",
  "parameters": []
}'

channel_number es obligatorio. Utiliza dígitos con el código de país, sin "+" (por ejemplo, 85264318722). target acepta un número de teléfono, ContactId, BSUID o Channel:PhoneNumber.

Ejemplo de respuesta de la API:

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

Importante: Una respuesta 200 significa que la solicitud fue aceptada, no que el mensaje fue entregado. La entrega se confirma mediante el webhook sentMessageDELIVERED_v2. Los fallos se notifican mediante templateMessageFailed.

Campo clave:

localMessageId — Identificador único del mensaje. Guarda este valor, ya que vincula todos los eventos de estado salientes de los webhooks con el mensaje original.

Realizar el seguimiento del estado del mensaje mediante webhooks

Una vez enviado, Wati dispara eventos de webhook para cada actualización de estado. Utiliza localMessageId para relacionar los eventos con el mensaje original.

1. Mensaje de plantilla enviado

Se activa cuando: El mensaje se acepta y se envía desde Wati
Evento: templateMessageSent_v2
Estado: SENT

SENT significa que el mensaje salió del sistema de Wati, no que se entregó al dispositivo del destinatario.

Ejemplo de carga útil:

{
  "eventType": "templateMessageSent_v2",
  "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",
  "channelId": null,
  "channelPhoneNumber": "174742",
  "bsuid": "HK.xxxxxxxxxxxxx",
  "parentBsuid": "HK.ENT.xxxxxxxxxxxxx",
  "username": "@bob",
  "templateContent": {
    "header": { "type": "text", "text": "Hello" },
    "footer": "Footer text",
    "buttons": [
      { "type": "QUICK_REPLY", "text": "Yes" },
      { "type": "URL", "text": "Visit us", "url": "https://example.com" },
      { "type": "CALL", "text": "Call us", "phoneNumber": "+1234567890" }
    ]
  }
}

Campos de templateContent:

Campo	Descripción
`header`	Tipo y contenido del encabezado (texto, imagen, video o documento)
`footer`	Texto del pie de página
`buttons`	Matriz de botones: tipos `QUICK_REPLY`, `URL` y `CALL`

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

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

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

¿Qué información de botones 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 obtienes 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.

Variante BSUID

templateMessageSent_v2_bsuid dispara el mismo evento con los campos bsuid, parentBsuid y username para identificar los contactos por BSUID en lugar de por número de teléfono.

2. Mensaje entregado

Se activa cuando: El mensaje se entrega en el dispositivo del destinatario
Evento: sentMessageDELIVERED_v2
Estado: Delivered

Ejemplo de carga útil:

{
  "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"
}

Variante BSUID: sentMessageDELIVERED_v2_bsuid

3. Mensaje leído

Se activa cuando: El destinatario lee el mensaje
Evento: sentMessageREAD_v2
Estado: Read

Ejemplo de carga útil:

{
  "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"
}

Variante BSUID: sentMessageREAD_v2_bsuid

4. Mensaje respondido

Se activa cuando: El destinatario responde al mensaje
Evento: sentMessageREPLIED_v2
Estado: Replied

Ejemplo de carga útil:

{
  "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"
}

Variante BSUID: sentMessageREPLIED_v2_bsuid

5. Mensaje recibido

Se activa cuando: Un usuario envía un mensaje a tu número de Wati
Evento: message
Estado: Received

Casos de uso:

Realizar el seguimiento de los mensajes entrantes de los usuarios
Capturar clics en botones de respuesta rápida de los mensajes de plantilla
Detectar respuestas a un mensaje saliente específico mediante replyContextId

Los mensajes entrantes no llevan un localMessageId. Para vincular una respuesta al mensaje de plantilla original, utiliza replyContextId; contiene el whatsappMessageId del mensaje saliente original.

Ejemplo de carga útil: mensaje de texto:

{
  "eventType": "message",
  "statusString": "Received",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "replyContextId": "wamid.HBgNODEYEjQ3RDMzQzM2QjM3QjU1ODQ4RQA=",
  "text": "Hello, I need help!",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

Ejemplo de carga útil: clic en botón de respuesta rápida:

{
  "eventType": "message",
  "statusString": "Received",
  "whatsappMessageId": "wamid.HBgMOAE4NjY4NDkzNjAxFAIAERgSOTEENzFCNjEwMkNDNENGQUJGAA==",
  "buttonReply": {
    "id": "btn_yes",
    "title": "Yes"
  },
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

6. Fallo en el mensaje de plantilla

Se activa cuando: El mensaje no se puede enviar
Evento: templateMessageFailed
Estado: Failed

Ejemplo de carga útil:

{
  "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]"
}

channelPhoneNumber solo se incluye en esta carga útil cuando el webhook está vinculado a un número específico.

Cómo configurar webhooks en Wati

A través de la interfaz de usuario de Wati:

Ve a Connector > Webhooks.
Haz clic en Add Webhook.

Ingresa la URL de tu webhook y establece el estado en Enabled.
Selecciona los eventos a los que quieres suscribirte:
- Template Message Sent (Mensaje de plantilla enviado)
- Delivered (Entregado)
- Read (Leído)
- Replied (Respondido)
- Failed (Fallido)

A través de API:

Crear un webhook (v2):

POST https://live-mt-server.wati.io/{tenantId}/api/v2/webhookEndpoints

Listar, obtener, actualizar y eliminar webhooks (v3: recomendado):

https://live-mt-server.wati.io/api/ext/v3/webhooks

Los endpoints de webhook v3 no incluyen /{tenantId}/ en la ruta.

Notas finales

Guarda siempre el localMessageId de la respuesta de envío: vincula todos los eventos de estado salientes con el mensaje original.
Para mensajes entrantes, usa replyContextId para vincular una respuesta al mensaje saliente original.
Usa buttonReply para detectar interacciones con botones de respuesta rápida.
Combina varios eventos de webhook para crear una vista completa del ciclo de vida del mensaje.

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

Resumen

Instrucciones

Enviar un mensaje de plantilla

Realizar el seguimiento del estado del mensaje mediante webhooks

1. Mensaje de plantilla enviado

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

¿Qué información de botones se incluye?

Variante BSUID

2. Mensaje entregado

3. Mensaje leído

4. Mensaje respondido

5. Mensaje recibido

6. Fallo en el mensaje de plantilla

Cómo configurar webhooks en Wati

Notas finales