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?

1. Click on 'Webhooks' on the top navigation on WATI Dashboard

2. Click on 'Add Webhook'

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

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

5. 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 Session 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

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.