Skip to main content

How to track template message delivery and message status using Wati webhooks

Summary

When you send template messages using the Wati API, you may want to track their status - such as sent, delivered, read, replied, or failed - using webhooks instead of relying only on Wati’s built-in campaign analytics.

After sending campaigns via the API, you can always view their performance in Campaign Overview in Wati. However, you can also use Wati webhooks to track message status and delivery events for those campaigns in real time through your own systems.

This approach helps you monitor message performance, troubleshoot delivery issues, and manage customer interactions through your applications. This guide explains how to send a template message and track its lifecycle using webhooks.

Note: For more information about Wati webhooks, refer to the Wati developer documentation.

Instructions

Send a template message

To send a template message using Wati’s API, use the sendTemplateMessage V2 endpoint.

Sample cURL request

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": []
}'

Sample API response

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

Key field

  • localMessageId: A unique identifier used to track the message across webhook events. Save this value, as it links all status updates for the message.

Track message status using webhooks

Once the message is sent, Wati sends webhook events for each status update. Use the localMessageId to match these events with the original message.

1. Template message sent

  • Triggered when: The message is successfully sent from Wati

  • Event: templateMessageSent_v2

  • Status: SENT

Sample Webhook Payload

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

Template sent webhook now includes button information

The Template Sent webhook now includes button information configured in the WhatsApp template. This allows you to identify the button text associated with a sent template message.

This feature is available to customers on the Pro, Business, and Enterprise plans.

What button information is included?

The webhook payload can include the following button information from the WhatsApp template:

  • Quick reply button text

  • Link button text

When you retrieve template information through the API, the response also includes the button text configured for the template.

2. Message delivered

  • Triggered when: The message is delivered to the recipient

  • Event: sentMessageDELIVERED_v2

  • Status: Delivered

Sample Webhook Payload

{
  "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. Message read

  • Triggered when: The recipient reads the message

  • Event: sentMessageREAD_v2

  • Status: Read

Sample Webhook Payload

{
  "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. Message replied

  • Triggered when: The recipient replies to the message

  • Event: sentMessageREPLIED_v2

  • Status: Replied

Sample Webhook Payload

{
  "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. Message received

  • Triggered when: A user sends a message to your Wati number

  • Event: messageReceived

  • Status: Received

Use case:

  • Track replies from users

  • Capture quick reply button clicks from template messages

Sample Webhook Payload

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

6. Template message failed

  • Triggered when: The message fails to send

  • Event: templateMessageFailed

  • Status: Failed

Sample Webhook Payload

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

How to set up webhooks in Wati

Follow these steps to start receiving webhook events:

  • Log in to your Wati account

  • Go to Connectors → Webhooks

  • Click Add Webhook

  • Enter your webhook URL

  • Set status to Enabled

  • Select the required events:

    • Template Message Sent

    • Delivered

    • Read

    • Replied

    • Failed

Final notes

  • Always store the localMessageId when sending messages

  • Use it to map all webhook events to the same message

  • Combine multiple webhook events to build a complete message lifecycle

By setting up webhooks correctly, you can reliably track every template message sent through Wati and take action based on real-time updates.

Frequently Asked Questions (FAQs)

Sending and Tracking Template Messages

1. How do I send a template message using the Wati API?

Use the sendTemplateMessage V2 endpoint to send a template message through the Wati API.

2. What is the localMessageId and why should I save it?

The localMessageId is a unique identifier for a message. Save it because Wati uses it to link webhook events to the original message and track its status throughout its lifecycle.

3. How can I track template message status using Wati webhooks?

Configure Wati webhooks to receive real-time events for template messages. Use the localMessageId to match each webhook event with the original message.

4. Which webhook events track the template message lifecycle?

The available webhook events are:

  • templateMessageSent_v2 — the message was successfully sent.

  • sentMessageDELIVERED_v2 — the message was delivered.

  • sentMessageREAD_v2 — the recipient read the message.

  • sentMessageREPLIED_v2 — the recipient replied to the message.

  • templateMessageFailed — the message failed to send.

  • messageReceived — a user sent a message to your Wati number.

5. What can the messageReceived webhook be used for?

The messageReceived webhook can be used to track replies from users and capture quick reply button clicks from template messages.

6. What button information is included in the Template Sent webhook?

The Template Sent webhook can include the quick reply button text and link button text configured in the WhatsApp template. The API response for template information also includes the configured button text.

7. Which Wati plans support button information in the Template Sent webhook?

The button information feature is available to customers on the Pro, Business, and Enterprise plans.

8. How do I set up webhooks in Wati to track template messages?

Go to Connectors → Webhooks in your Wati account, click Add Webhook, enter your webhook URL, set the status to Enabled, and select the required events: Template Message Sent, Delivered, Read, Replied, and Failed.

9. How can I track the complete lifecycle of a template message?

Store the localMessageId when sending the message and use it to map all related webhook events. Combining these events lets you track whether the message was sent, delivered, read, replied to, or failed.

Related Articles
Did this answer your question?