Skip to main content

How to track template message delivery and status using Wati webhooks

Updated today

Summary

When you send template messages using Wati’s API, it’s important to track their status - such as sent, delivered, read, replied, or failed. This helps you understand message performance, troubleshoot issues, and manage customer interactions more effectively. This guide explains how to send a template message and use webhooks to track its lifecycle.

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",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "templateId": "63766ae83b2e064905789c63",
  "templateName": "update_for_you",
  "created": "2023-03-11T14:27:32.9655388Z",
  "statusString": "SENT",
  "sourceType": "API"
}

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": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678544854",
  "operatorEmail": "[email protected]"
}

3. Message read

  • Triggered when: The recipient reads the message

  • Event: sentMessageREAD_v2

  • Status: Read

Sample Webhook Payload

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "localMessageId": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678545043",
  "operatorEmail": "[email protected]"
}

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": "d38f0c3a-e833-4725-a894-53a2b1dc1af6",
  "id": "640c8fd48b67615f886237b8",
  "whatsappMessageId": "gBEGkXmJQZVJAgkRHwjjZsITS6M",
  "timestamp": "1678545074",
  "operatorEmail": "[email protected]"
}

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==",
  "timestamp": "1665645642",
  "operatorEmail": "[email protected]"
}

How to set up webhooks in Wati

Follow these steps to start receiving webhook events:

  1. Log in to your Wati dashboard

  2. Go to Connectors → Webhooks

  3. Click Add Webhook

  4. Enter your webhook URL

  5. Set status to Enabled

  6. 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 template messages

1. How do you send a template message using Wati’s API?

You can send a template message using Wati’s API by calling the sendTemplateMessage V2 endpoint with the required headers and JSON body, including fields such as template_name, broadcast_name, and parameters.

2. What is the purpose of the localMessageId in the API response?

The localMessageId is a unique identifier returned in the API response that is used to track the message across all webhook events. This value should be stored because it links all status updates to the same message.

Tracking message status with webhooks

3. How can you track the lifecycle of a template message in Wati?

You can track the lifecycle of a template message using webhook events sent by Wati after the message is sent. Each webhook event includes a localMessageId that allows you to match the event with the original message and follow its status updates.

4. What webhook events are triggered for different template message statuses?

Wati triggers the following webhook events for template message statuses:

  • templateMessageSent_v2 when the message is successfully sent (Status: SENT)

  • sentMessageDELIVERED_v2 when the message is delivered (Status: Delivered)

  • sentMessageREAD_v2 when the message is read (Status: Read)

  • sentMessageREPLIED_v2 when the recipient replies (Status: Replied)

  • messageReceived when a user sends a message to your Wati number (Status: Received)

  • templateMessageFailed when the message fails to send (Status: Failed)

5. When is the messageReceived webhook event triggered and what is its use?

The messageReceived webhook event is triggered when a user sends a message to your Wati number. It can be used to track user replies and capture quick reply button clicks from template messages.

Webhook setup

6. How do you set up webhooks in Wati to receive message status events?

To set up webhooks in Wati:

  • Log in to your Wati dashboard.

  • Go to Connectors → Webhooks.

  • Click Add Webhook.

  • Enter your webhook URL.

  • Set the status to Enabled.

  • Select the required events such as Template Message Sent, Delivered, Read, Replied, and Failed.

Best practices for message tracking

7. Why should you store the localMessageId when sending messages?

You should store the localMessageId because it is required to map all webhook events to the same message and track its complete lifecycle.

8. How can you build a complete message lifecycle using webhook events?

You can build a complete message lifecycle by combining multiple webhook events linked by the same localMessageId, which provides all status updates for a single template message.

9. Why is webhook setup important for tracking template messages in Wati?

Webhook setup is important because it enables real-time tracking of every template message sent through Wati and allows you to take action based on status updates such as sent, delivered, read, replied, or failed.

Related Articles
Integrating Wati with Bitrix24
How to send WhatsApp messages using Zapier webhooks and Wati
How to use Webhook to check Payment Status
General FAQs: Wati APIs & Webhooks
How to set up and use webhooks in Wati
Did this answer your question?