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 plan.

How to add a Webhook to Wati?

  1. Click on 'Webhooks' on the top navigation on Wati Dashboard
  1. Click on 'Add Webhook'
  1. Enter the full webhook URL, set the status as 'Enabled', and choose the events you would like to capture with this webhook.
  1. Once the webhook is added, use the Trigger sample callback option to test the connection
  1. 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