Actions & Reactions

  • When a user reacts, interacts or takes some actions on messages sent to him by business or acts on own message; these are posted to Webhook at real time as a new message with a JSON Payload of predefined format.
  • Basic JSON Format of these messages are also similar to incoming message.

Incoming Message JSON Format

All action and reaction messages follow a common JSON format as incoming message given below:

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "{content type}",
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explaination

Key / ObjectData TypeDescription
messagesArrayIts presented as array of messages. The message information will appear as an object in it.
contactsArrayIts message sender profile. Its presented as array of senders. For incoming message, sender is the user or customer who sent message using WhatsApp App to business.
business_phoneStringBusiness Phone Number to which the message is sent by user or customer.

A Single Object of messages Array Its related to the message information placed in messages array in incoming message payload.

Key / ObjectData TypeDescription
idStringMessage ID. All Action, reactions will be received on this ID.
fromStringSender Phone Number
timestampStringUnix Timestamp for the message in UTC
typeStringType of content. Enumerated data. e.g. text, unknown

A Single Object of contacts Array: Its related to the Sender Profile placed in contacts array in incoming message payload.

Key / ObjectData TypeDescription
profileObjectIts sender profile information.
profile.nameStringSender Name
wa_id StringWhatsApp ID i.e. Sender Phone Number including country code

Actions/Reactions JSON Format

Read the following section to understand different type of Action/Reaction messages and related JSON received on Webhook.

Message deleted

JSON Payload: This message is received when user deletes his message which was sent by him earlier.

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "unknown",
"errors": [
{
"code": 131051,
"title": "{error title }"
}
]
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explaination: Covers only key/objects related to deleted message. For other keys, refer explanation given above.

Key / ObjectData TypeDescription
typeStringIt comes as unknown
errorsArrayArray of objects. Each object contains a Error definition. This Array appears with type:unknown.
errors[n].codeStringError Code
errors[n].titleStringError Title

Replied Message

JSON Payload: This message is received as a reply to a message sent earlier. It will have a context object with reference to the message which was replied.

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "{content type}",
"{content type}": {
},
"context": {
"from": "{sender phone}",
"id": "{message id being replied}"
}
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explaination: Covers only key/objects related to a replied message. For other keys, refer explanation given above.

Key / ObjectData TypeDescription
typeStringContent type, Enumerated data: text, image, video, audio, document etc.
$typeObjectThis object is named after the content type. This object will carry content type related data structure. Refer Incoming Message JSON of different types.
contextObjectThis object appears in an incoming message when its being replied against a old message. This object contains the replied message information.
context.fromStringSender Phone of replied message
context.idStringMessage ID of replied message

Note: While replying, any type of content may be received as sent by user. Refer Incoming Message JSON of different types.

Reacted on a message with Emoji

JSON Payload: This message is related to user’s reaction on a message with like, love, thumbs up etc.

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "reaction",
"reaction": {
"message_id": "{message id being reacted}",
"emoji": "{emoji e.g. 👍}"
}
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explaination: Covers only key/objects related to a reacted message with emoji. For other keys, refer explanation given above.

Key / ObjectData TypeDescription
typeStringIt carries reaction
reactionObjectThis object appears with type:reaction. It contains reaction emoji and the message_id of the message being reacted
reaction.emojiEmojiEmoji with which message was reacted
reaction.message_idStringMessage ID of reacted message

Clicked a Quick Reply Button

Clicked a Quick Reply Button (From a Message sent using Template)

JSON Payload: This message is received when a quick-reply button is clicked from a message sent with Template. It will have a context object with reference to the message which was responded with a button click.

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "button",
"button": {
"payload": "{label of clicked button}",
"text": "{label of clicked button}"
},
"context": {
"from": "{sender phone}",
"id": "{message id being replied}"
}
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explaination: Covers only key/objects related to button click. For other keys, refer explanation given above.

Key / ObjectData TypeDescription
typeStringIt carries button
buttonObjectThis object carries information about the clicked quick-reply button
button.payloadStringLabel of the clicked button
button.textStringLabel of the clicked button

Clicked a Button in Interactive Message

JSON Payload: This message is received when a button is clicked from a message sent with Interactive Buttons. It will have a context object with reference to the message which was responded with a button click.

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": {
"id": "{id of the clicked button}",
"title": "{title the button}"
}
},
"context": {
"from": "{sender phone}",
"id": "{message id being replied}"
}
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explaination: Covers only key/objects related to button click. For other keys, refer explanation given above.

Key / ObjectData TypeDescription
typeStringIt carries interactive
interactiveObjectThis object carries information about the clicked interactive button
interactive.typeStringIt carries button_reply
interactive.button_replyObjectIt carries the information of the clicked button
context ObjectThis object contains the message information from which the button was clicked
context.fromStringSender Phone of replied message
context.idStringMessage ID of replied message

button_reply Object Explanation: Covers only keys related to button_reply object.

Key / ObjectData TypeDescription
idStringID of the clicked button
titleStringTitle / Label of the clicked button

Selected a List Option in Interactive List Message

JSON Payload: This message is received when an option is selected from from a message sent with Interactive List. It will have a context object with reference to the message which was responded with an option selected.

{
"messages": [
{
"id": "{message id}",
"from": "{sender phone}",
"timestamp": "{unix timestamp}",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "{id of the selected list item}",
"title": "{title of the list item}",
"description": "{description of the list item}"
}
} ,
"context": {
"from": "{sender phone}",
"id": "{message id being replied}"
}
}
],
"contacts": [
{
"profile": {
"name": "{sender name}"
},
"wa_id": "{sender phone}"
}
],
"business_phone": "{business phone}"
}

JSON Explanation: Covers only key/objects related to selected list option. For other keys, refer explanation given above.

Key / ObjectData TypeDescription
typeStringIt carries interactive
interactiveObjectThis object carries information about the clicked interactive button/lis
interactive.typeStringIt carries list_reply
interactive.list_replyObjectIt carries the information of the selected list item
contextObjectThis object contains the message information from which the button was clicked
context.fromStringSender Phone of replied message
context.idStringMessage ID of replied message

**list_reply Object Explanation**: Covers only keys related to list_reply` object.

Key / ObjectData TypeDescription
id StringID of the selected List Item
titleStringTitle / Label of the selected List Item
descriptionStringDescription of the selected List Item

Acknowledgement

Any Message received at Webhook must be acknowledged by returning HTTP 200 header in the same connection.

Refer the example below written in PHP, to return HTTP 200 header.

<?php
header("HTTP/1.1 200 OK");
?>