Webhooks

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",  
  "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]"
}

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.

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