WATI supports webhooks that can alert you of the following via callback URLs.
- Messages received
- Messages sent (Template & Session)
- Status of the messages sent (Sent/Delivered/read)
These functionalities are currently available through the WATI CRM plan. The complete official Whatsapp API/webhooks access is available through our API Gateway plan.
How to add a Webhook to WATI?
- Click on 'Webhooks' on the top navigation on WATI Dashboard

- Click on 'Add Webhook'

- Enter the full webhook URL, set the status as 'Enabled', and choose the events you would like to capture with this webhook.

- Once the webhook is added, use the Trigger sample callback option to test the connection

- Whenever an event is triggered, the respective callback is sent to your webhook URL with a sample payload

Session based Webhooks:
The WhatsApp Business API conversations are measured in 24-hour increments, or "sessions", that start whenever the first message from a business is delivered. The first message can be initiated by the company (business-initiated) or a business reply within 24 hours of a user message (user-initiated).
Active Session: A session where the business and user have sent each other at least 1 message is considered an Active session e.g., a business sent a template message to a user and the user responded.
Inactive session: A session where only one message was sent from one party and the other hasn't responded yet is considered an Inactive session e.g., a business sent a template message to a user and the user hasn't responded.
The callbacks sent via webhooks depend on whether a conversation/session is active or not.

Webhooks supported by WATI:
1. Message Received
This webhook is triggered whenever a user sends a message to your WATI number.
Sample payload for this webhook:
{
"id": "1a2b3b4d5e6f7g8h9i10j",
"created": "2022-10-14T05:53:01.3833674Z",
"whatsappMessageId": "abcdefghi_jklmnop",
"conversationId": "a1b2c3d4e5f6g7h8i9j10",
"ticketId": "m1n2o3p4q5r6s7t8u9v10",
"text": "Hello there",
"type": "text",
"data": null,
"timestamp": "1665726781",
"owner": false,
"eventType": "message",
"statusString": "SENT",
"avatarUrl": null,
"assignedId": "6343c17682538bf08459f5ed",
"operatorName": "Wati User",
"operatorEmail": "[email protected]",
"waId": "911234567890",
"messageContact": null,
"senderName": "wati user",
"listReply": null,
"replyContextId": null
}
2. New Contact Message
This webhook is triggered when a new contact (not in the WATI Contact Section) sends a message.
Sample payload for this webhook:
{
"eventType": "newContactMessageReceived",
"id": "634930ab82538bf0845a116a",
"created": "2022-10-14T09:49:31.2419621Z",
"waId": "911234567890",
"senderName": "New User"
}
3. Session Message Sent
This webhook is triggered when a Session message is sent.
Sample payload for this webhook:
{
"eventType": "sessionMessageSent",
"id": "1a2b3b4d5e6f7g8h9i10j",
"whatsappMessageId": "abcdefghi_jklmnop",
"conversationId": "a1b2c3d4e5f6g7h8i9j10",
"ticketId": "m1n2o3p4q5r6s7t8u9v10",
"text": "Brand new offer: 50% OFF just for you!",
"type": "text",
"data": null,
"timestamp": "1665650047",
"owner": true,
"statusString": "SENT",
"assigneeId": "6343c17682538bf08459f5ed",
"operatorEmail": "[email protected]",
"operatorName": "Wati User",
"waId": "911234567890"
}
4. Template Message Sent
This webhook is triggered when a Template message is sent.
Sample payload for this webhook:
{
"eventType": "templateMessageSent",
"id": "6347bc2a82538bf0845a0ba0",
"whatsappMessageId": "abcdefghi_jklmnop",
"templateId": "1a2b3b4d5e6f7g8h9i10j",
"templateName": "shipping_template",
"created": "2022-10-13T07:20:11.3921095Z",
"conversationId": "a1b2c3d4e5f6g7h8i9j10",
"ticketId": "m1n2o3p4q5r6s7t8u9v10",
"text": "Hi! Your order is out for delivery",
"operatorEmail": "[email protected]",
"waId": "911234567890",
"type": "template",
"statusString": "SENT",
"sourceType": "WEB"
}
5. Sent Message is DELIVERED
This webhook is triggered when the message you sent is delivered to the user.
Sample payload for this webhook:
{
"eventType": "sentMessageDELIVERED",
"statusString": "Delivered",
"id": "1a2b3b4d5e6f7g8h9i10j",
"whatsappMessageId": "abcdefghi_jklmnop",
"conversationId": "a1b2c3d4e5f6g7h8i9j10",
"ticketId": "m1n2o3p4q5r6s7t8u9v10",
"text": null,
"type": "template",
"timestamp": "1665645642",
"assigneeId": null,
"operatorEmail": "[email protected]"
}
6. Sent Message is READ
This webhook is triggered when the message you sent is read by the user.
Sample payload for this webhook:
{
"eventType": "sentMessageREAD",
"statusString": "Read",
"id": "1a2b3b4d5e6f7g8h9i10j",
"whatsappMessageId": "abcdefghi_jklmnop",
"conversationId": "a1b2c3d4e5f6g7h8i9j10",
"ticketId": "m1n2o3p4q5r6s7t8u9v10",
"text": null,
"type": "template",
"timestamp": "1665645642",
"assigneeId": null,
"operatorEmail": "[email protected]"
}
7. Sent Message is REPLIED
This webhook is triggered when the user replies back to the message you sent
Sample payload for this webhook:
{
"eventType": "sentMessageREPLIED",
"statusString": "Replied",
"id": "1a2b3b4d5e6f7g8h9i10j",
"whatsappMessageId": "abcdefghi_jklmnop",
"conversationId": "a1b2c3d4e5f6g7h8i9j10",
"ticketId": "m1n2o3p4q5r6s7t8u9v10",
"text": null,
"type": "template",
"timestamp": "1665645642",
"assigneeId": null,
"operatorEmail": "[email protected]"
}
Payload Structure
Name | Type | Nullable | Notes |
---|---|---|---|
id | String | No | Forward message id |
created | String | No | Forward message created time (UTC time in unix format) |
conversationId | String | No | WATI conversation ID |
ticketId | String | No | WATI ticket ID |
text | String | Yes | Message text |
type | String | No | value type: image/text/document/location/voice/audio/button/video/sticker |
data | String | Yes | Media path if message is media, null for text message |
timestamp | Timestamp | No | message sent time (UTC time in unix format) |
owner | Boolean | No | true = sent by WATI false = incoming message |
eventType | String | No | WATI message type, "message" |
statusString | String | Yes | WATI message status |
avatarUrl | String | Yes | WATI avatar URL |
assignedId | String | Yes | WATI assigned ID |
operatorName | String | Yes | WATI assigned Operator Name |
operatorEmail | String | Yes | WATI assigned Operator Email |
waId | String | No | WhatsApp ID: country code + phone number |
senderName | String | No | original WhatsApp name of sender |
Note: When WATI sends events to the webhook, we will expect a 200 response to acknowledge the event was received. If the webhook provided cannot respond with a 200 response code, the same message will be retried at a later time (up to 5 times). The message will not be sent after 5 attempts. The retry jobs (which can contain multiple previously failed messages) run in 10-minute intervals.
If the webhook has more than 100 consecutive failed jobs, it will be considered Defective and you shall receive an email alert about this.