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 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",
"sourceId": null,
"sourceUrl": null,
"sourceType": 0
}
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]"
}
8. Template message FAILED
This webhook is triggered when a template message failed to be sent by WhatsApp/Meta. It includes the failure code and message returned by Meta. You may refer to Meta's documentation for more info on specific codes here.
Sample payload for this webhook:
{
"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]"
}
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 144 attempts). The message will not be sent after those 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.
If you want to learn how to track Template Messages using Webhooks: https://support.wati.io/l/en/article/uqshdvgsuv-how-to-track-template-messages-using-webhooks