# How to use Message Status Update Webhook

When you send messages from DoubleTick, especially template messages, it is important to know what happens after sending them.

Did the message/template reach the customer?\
Did the customer read it?\
Did the message/template fail?

The **Message Status Update** webhook helps you track all of this automatically.

***

#### <mark style="color:$primary;">**What is Message Status Update Webhook?**</mark>

The Message Status Update event is triggered whenever there is a change in the status of a message sent through DoubleTick.

<mark style="color:$warning;">**In simple terms:**</mark>

<mark style="color:$warning;">**Every time you send a message, this webhook keeps updating your system with the latest status of that message/template.**</mark>

***

<figure><img src="/files/JK17PHnuvitvwrTtkXvQ" alt=""><figcaption></figcaption></figure>

#### <mark style="color:$primary;">**When Does This Webhook Trigger?**</mark>

This webhook is triggered at every stage of the message lifecycle:

* When the message is **sent**
* When the message is **delivered**
* When the message is **read**
* When the message **fails** (not sent or not delivered)

This gives you complete visibility into your message performance.

***

#### <mark style="color:$primary;">**Step-by-Step Setup Guide**</mark>

<figure><img src="/files/9PGKBgijgEPQfYAAD1tT" alt=""><figcaption></figcaption></figure>

#### <mark style="color:$primary;">**Step 1: Open Webhooks in DoubleTick**</mark>

1. Log in to your DoubleTick account
2. Go to **Settings**
3. Click on **Webhooks**

#### <mark style="color:$primary;">**Step 2: Create a New Webhook**</mark>

1. Click **New Webhook** in the top right corner
2. Give it a clear name — for example: `Message Status Webhook`

#### <mark style="color:$primary;">**Step 3: Get Your Webhook URL**</mark>

You need a destination URL — this is where DoubleTick will send the status data every time a message status changes.

You can connect it to:

* A **CRM** like Zoho, HubSpot, or Salesforce
* An **automation tool** like Zapier, Pabbly, or Make
* Your own **backend or server**

**For testing purposes**, you can use DoubleTick's **Bot Studio** to capture and preview the data first:

1. Open a new tab and go to **Bot Studio**
2. Click **Create New Bot**
3. Set the trigger to **On Webhook**
4. **Copy the webhook URL** that appears

#### <mark style="color:$primary;">**Step 4: Fill in Webhook Details**</mark>

1. Go back to the **Webhooks** page
2. Paste the webhook URL
3. Select your **API Number** (your WABA/WhatsApp Business number)
4. Click **Continue**

#### <mark style="color:$primary;">**Step 5: Choose the Event**</mark>

1. Select **Message Status Update** from the event list
2. Click **Create Webhook**

Your webhook is now active.

***

#### <mark style="color:$primary;">**How to Test It**</mark>

1. Go to **New Chat** in DoubleTick
2. Enter a customer number and start the chat
3. Send a template message
4. Go to **Bot Studio → Capture Response → View Response Data**

You will now see all the webhook data captured.

***

#### <mark style="color:$primary;">**What Data Do You Receive?**</mark>

When this webhook fires, it sends the following information to your system:

<table><thead><tr><th width="202">Field</th><th>What It Tells You</th></tr></thead><tbody><tr><td>To</td><td>The customer's phone number the message was sent to</td></tr><tr><td>Status</td><td>The current status of the message — Sent, Delivered, Read, or Failed</td></tr><tr><td>Message Type</td><td>Whether the message was a template or a text message</td></tr><tr><td>Template Name</td><td>The name of the template used (if applicable)</td></tr><tr><td>Message Body</td><td>The full text content of the message that was sent</td></tr><tr><td>Buttons</td><td>The button text and type included in the template (if applicable)</td></tr><tr><td>Header</td><td>The header text included in the template (if applicable)</td></tr><tr><td>Message Language</td><td>The language the template was sent in</td></tr><tr><td>Message ID</td><td>The unique identifier for this specific message</td></tr><tr><td>Template ID</td><td>The unique identifier of the template used</td></tr><tr><td>WABA Number</td><td>The WhatsApp Business number that sent the message</td></tr><tr><td>Fail Message</td><td>The reason the message failed, if the status is Failed</td></tr><tr><td>Customer Name</td><td>The name saved for this customer in DoubleTick</td></tr><tr><td>Status Timestamp</td><td>The exact date and time of the status update</td></tr></tbody></table>

***

#### <mark style="color:$primary;">**Template Status Update Webhook (Failed) – Sample Payload**</mark>&#x20;

{% code expandable="true" %}

```json
{
  "to": "919372139459",
  "sentBy": "919372139459",
  "status": "FAILED",
  "message": {
    "type": "template",
    "templateName": "ziptrip_tem",
    "templateMessage": {
      "body": {
        "text": "Hi Ruchi,\nExplore our top travel picks and choose your next destination ✈️🌍",
        "type": "text"
      },
      "header": {}
    },
    "templateLanguage": "en"
  },
  "messageId": "c3c73f21-6195-4796-bd3e-a7aebcac6aa1",
  "assignedTo": "918169704217",
  "templateId": 1928048,
  "wabaNumber": "919321721251",
  "failMessage": "contact Gupshup Team",
  "customerName": "Slvia",
  "statusTimestamp": "1970-01-21T13:03:57.000Z",
  "templateVariableValues": {
    "First name": "Ruchi"
  }
}
```

{% endcode %}

#### <mark style="color:$primary;">**Template Status Update Webhook (Sent) – Sample Payload**</mark>

{% code expandable="true" %}

```json
{
  "to": "919876123456",
  "sentBy": "919845672310",
  "status": "SENT",
  "message": {
    "type": "template",
    "templateName": "welcome_user_v1",
    "templateMessage": {
      "header": {
        "text": "Hello!",
        "type": "text"
      },
      "body": {
        "text": "Hi Ankit Sharma! Welcome to our service.\n\nLet us know how we can assist you.",
        "type": "text"
      },
      "button": [
        {
          "text": "Request Callback",
          "type": "QUICK_REPLY"
        },
        {
          "text": "Unsubscribe",
          "type": "QUICK_REPLY"
        }
      ]
    },
    "templateLanguage": "en"
  },
  "messageId": "b8c2d4e1-5f73-4a9b-8d21-6e3f7a2c9d10",
  "assignedTo": "919812345678",
  "templateId": 2045678,
  "wabaNumber": "919845672310",
  "customerName": "Ankit Sharma",
  "statusTimestamp": "2026-04-01T13:05:20.000Z",
  "templateVariableValues": {
    "first_name": "Ankit",
    "last_name": "Sharma",
    "platform": "DoubleTick"
  }
}
```

{% endcode %}

#### <mark style="color:$primary;">**Template Message Webhook (Delivered) – Sample Payload**</mark>

{% code expandable="true" %}

```json
{
  "to": "919876123456",
  "sentBy": "919845672310",
  "status": "DELIVERED",
  "message": {
    "type": "template",
    "templateName": "welcome_user_v1",
    "templateMessage": {
      "header": {
        "text": "Hello!",
        "type": "text"
      },
      "body": {
        "text": "Hi Ankit Sharma! Welcome to our service.\n\nLet us know how we can assist you.",
        "type": "text"
      },
      "button": [
        {
          "text": "Request Callback",
          "type": "QUICK_REPLY"
        },
        {
          "text": "Unsubscribe",
          "type": "QUICK_REPLY"
        }
      ]
    },
    "templateLanguage": "en"
  },
  "messageId": "d1f7a3c9-6b52-4e8d-9a21-3c7f5b2e9d40",
  "assignedTo": "919812345678",
  "templateId": 2045678,
  "wabaNumber": "919845672310",
  "customerName": "Ankit Sharma",
  "statusTimestamp": "2026-04-01T13:10:30.000Z",
  "templateVariableValues": {
    "first_name": "Ankit",
    "last_name": "Sharma",
    "platform": "DoubleTick"
  }
}
```

{% endcode %}

#### <mark style="color:$primary;">**Mapping Data in Bot Studio**</mark>

After capturing the response, you need to map key fields in the **'On Webhook'** component.

* First dropdown → Map **Customer Number**
  * Select: `To`
* Second dropdown → Map **Your Number (WABA Number)**
  * Select: `Sent By`

This ensures proper identification of sender and receiver.\
\
**Note:** The second dropdown (WABA Number) appears only in multi-number setups; for single-number accounts, it is selected by default and won’t be visible.

***

#### <mark style="color:$primary;">**What Happens After Setup?**</mark>

Once your webhook is set up:

* Every message you send will generate logs
* You will get separate entries for:
  * Sent
  * Delivered
  * Read
  * Failed

All data will be automatically stored in your connected system (Google Sheets, CRM, or any tool you choose).

***

#### <mark style="color:$primary;">**Real Business Usecase 1 : A Digital Marketing Agency**</mark>

**The Situation**

A digital marketing agency runs WhatsApp campaigns on behalf of their clients — sending promotional messages, offers, and updates to thousands of customers at a time.

**The Problem Before Automation**

* There was no way to track which messages were actually delivered or read
* Failed messages went unnoticed and were never retried
* Follow-up messages were sent to everyone, including those who had already read the original message
* Template performance reports had to be compiled manually, which took hours

**The Solution**

The agency connected the Messages status update webhook to their reporting and CRM tools.

Now, the moment a campaign message is sent:

* Delivery and read status is tracked automatically for every message
* Failed messages are identified instantly along with the reason for failure
* A live dashboard in Google Sheets updates in real time with Template performance data
* Follow-up messages are triggered only for customers who have not yet read the message
* Failed messages are automatically retried without any manual intervention

**The Result**

* Template performance is visible in real time, with no manual reporting
* Failed messages are retried instantly, ensuring nothing is missed
* Follow-ups are more targeted, reaching only the right customers at the right time
* Clients receive accurate and up-to-date campaign reports automatically

***

#### <mark style="color:$primary;">**Real Business Usecase 2: Tracking API-Based Template Messages (Enqueued Status)**</mark>

<figure><img src="/files/p5XGUOei10VRulTjAxf3" alt=""><figcaption></figcaption></figure>

#### **The Situation**

A business is sending WhatsApp template messages using APIs instead of directly from the DoubleTick dashboard.

When a template is sent via API, the immediate response received is:

**“enqueued”**

This is a standard response, which only confirms that the message has been accepted for processing — but it does not confirm whether the message was actually sent, delivered, read, or failed.

#### **The Problem**

* The system only shows **enqueued** status initially
* There is no visibility into the final status of the message
* Businesses cannot confirm:
  * Whether the message was sent
  * Whether it was delivered
  * Whether it was read
  * Whether it failed

This creates a gap in tracking and reporting.

#### **The Solution**

The business uses the **Message Status Update webhook**.

Once the webhook is configured:

* Every API-triggered message is tracked beyond the “enqueued” stage
* The webhook captures the actual final status of the message

#### **What Happens After Setup**

* When a template is sent via API → status shows **enqueued**
* The webhook then updates the system with:
  * Sent
  * Delivered
  * Read
  * Failed

This provides complete visibility into the message lifecycle.

#### **Business Impact**

* Clear tracking beyond the initial “enqueued” response
* Accurate reporting of message delivery and engagement
* Better monitoring of API-based campaigns
* Ability to take action based on real message status

***

#### <mark style="color:$primary;">**Conclusion**</mark>

The Message Status Update webhook is a powerful tool for tracking and managing message performance.

It helps you:

* Monitor the full lifecycle of messages
* Track delivery, read, and failure status
* Automate reporting
* Integrate with external systems
* Improve communication efficiency


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.doubletick.io/webhooks/how-to-use-message-status-update-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.