Skip to main content

Tracking Template Message Status using Webhooks

Updated yesterday

Summary

When sending template messages using WATI's Send Template Message API, it’s essential to track their status - sent, delivered, read, replied, or failed. This ensures better visibility and management of customer interactions.

Instructions

Sending a Template Message

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

Sample cURL Request

curl --location 'https://live-server-123.wati.io/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 for tracking the message status through webhooks.

Webhooks for Tracking Message Status

1. Template Message Sent

Triggered when: A template message is successfully sent.

  • Webhook Event: templateMessageSent_v2

  • Key Field: localMessageId

  • Status String: "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 successfully delivered to the recipient.

  • Webhook Event: sentMessageDELIVERED_v2

  • Status String: "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.

  • Webhook Event: sentMessageREAD_v2

  • Status String: "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.

  • Webhook Event: sentMessageREPLIED_v2

  • Status String: "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.

  • Webhook Event: messageReceived

  • Use Case: Can be used with Template Message Sent to track quick reply button clicks.

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 template message fails to send.

  • Webhook Event: templateMessageFailed

  • Failure Details: Includes a failure code and error message.

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

  1. Go to the WATI Dashboard

  2. Navigate to Webhooks

  3. Click "Add Webhook"

  4. Enter your webhook URL

  5. Set Status to "Enabled"

  6. Select the necessary events (e.g., Template Message Sent, Delivered, Read, etc.)

By following these steps, you can effectively track and manage all template messages sent through the WATI API.

Frequently Asked Questions (FAQs)

Sending Template Messages

1. How do I send a template message using WATI's API?

→ To send a template message, use the sendTemplateMessage V2 endpoint. You need to include the WhatsApp number, template name, and authorization token in the request. Refer to the sample cURL request in the documentation for details.

2. What parameters do I need to include in the API request?

→ The required parameters include whatsappNumber, template_name, broadcast_name, and parameters (if applicable). Ensure you provide a valid authorization token.

Tracking Message Status

3. How can I track the status of a sent message?

→ Each API response includes a localMessageId, which can be used to track the message status through webhooks. Webhooks provide real-time updates for sent, delivered, read, replied, and failed messages.

4. What webhook event tracks when a message is sent?

→ The templateMessageSent_v2 webhook event tracks when a message is sent. It contains the localMessageId, whatsappMessageId, and other metadata.

5. How do I know when a message is delivered?

→ The sentMessageDELIVERED_v2 webhook event indicates that the message has been delivered. The statusString field will have the value Delivered.

6. How do I track when a message is read?

→ The sentMessageREAD_v2 webhook event is triggered when the recipient reads the message. The statusString field will have the value Read.

7. Can I track if a user replies to a message?

→ Yes, the sentMessageREPLIED_v2 webhook event is triggered when the recipient responds to the message.

Handling Failures

8. What happens if a template message fails to send?

→ If a message fails, the templateMessageFailed webhook event is triggered. It provides a failedCode and failedDetail explaining the reason for failure.

9. Where can I find details about failure codes?

→ Failure codes are included in the templateMessageFailed webhook payload. You can refer to Meta’s documentation for a detailed explanation of each error code.

Configuring Webhooks

10. How do I enable webhooks in WATI?

→ To enable webhooks:

  • Go to the WATI Dashboard.

  • Navigate to Webhooks.

  • Click Add Webhook.

  • Enter your webhook URL.

  • Set the status to Enabled.

  • Select the webhook events you want to track.

11. Which webhook events should I enable for complete message tracking?

→ To track the entire message lifecycle, enable the following events:

  • templateMessageSent_v2

  • sentMessageDELIVERED_v2

  • sentMessageREAD_v2

  • sentMessageREPLIED_v2

  • messageReceived

  • templateMessageFailed

Related Articles
How to Integrate Wati with Klaviyo
How to Send WhatsApp Messages via Wati (Using Make.com - formerly Integromat)
How to Send WhatsApp Messages Using Zapier Webhooks and Wati
Webhooks Guide: Wati Webhooks or WhatsApp API Gateway?
How to use Webhook to check Payment Status
Did this answer your question?