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

Table of Contents

• Overview
• Message JSON Format Explanation
• JSON for different type of Actions/Reactions
  • Message deleted
  • Replied a Message
  • Reacted with Emoji
  • Clicked a Quick Reply Button (Message with Template)
  • Clicked a Button on Interactive Message
  • Selected a List Option on Interactive List Message
• Acknowledgement

Overview

These are actions or reactions against an incoming or outgoing messages. Basic JSON Format of these messages are also similar to incoming message.

Incoming Message JSON Format Explanation

All action and reaction messages follow a common JSON format as 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}"
}

Incoming Action/Reaction Message JSON Explanation

Key / Object	Data Type	Description
messages	Array	Its presented as array of messages. The message information will appear as an object in it.
contacts	Array	Its 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_phone	String	Business Phone Number to which the message is sent by user or customer.

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

Key / Object	Data Type	Description
id	String	Message ID. All Action, reactions will be received on this ID.
from	String	Sender Phone Number
timestamp	String	Unix Timestamp for the message in UTC
type	String	Type of content. Enumerated data. e.g. text, unknown

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

Key / Object	Data Type	Description
profile	Object	Its sender profile information
profile.name	String	Sender Name
wa_id	String	WhatsApp ID i.e. Sender Phone Number including country code

JSON Explanation for different Actions/Reactions

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

Message is 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}" 
}

Delete Specific Explanation: Covers only key/objects related to deleted message. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It comes as unknown
errors	Array	Array of objects. Each object contains a Error definition. This Array appears with type:unknown.
errors[n].code	String	Error Code
errors[n].title	String	Error Title

Replied a 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.

Note that while replying any type of content can be sent including text, image, audio, video, document etc.

{
  "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}" 
}

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

Key / Object	Data Type	Description
type	String	Content type, Enumerated data: text, image, video, audio, document etc.
$type	Object	This object is named after the content type. This object will carry content type related data structure. Refer Incoming Message JSON of different types.
context	Object	This object appears in an incoming message when its being replied against a old message. This object contains the replied message information.
context.from	String	Sender Phone of replied message
context.id	String	Message ID of replied message

Note: While a reply message, 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}" 
}

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

Key / Object	Data Type	Description
type	String	It carries reaction
reaction	Object	This object appears with type:reaction. It contains reaction emoji and the message_id of the message being reacted
reaction.emoji	Emoji	Emoji with which message was reacted
reaction.message_id	String	Message ID of reacted message

Clicked a Quick Reply Button (From Message 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}"
}

Button Reply Specific Explanation: Covers only key/objects related to button click. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It carries button
button	Object	This object carries information about the clicked quick-reply button
button.payload	String	Label of the clicked button
button.text	String	Label 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}"
}

Button Reply Specific Explanation: Covers only key/objects related to button click. For other keys, refer explanation given above.

Key / Object	Data Type	Description
type	String	It carries interactive
interactive	Object	This object carries information about the clicked interactive button
interactive.type	String	It carries button_reply
interactive.button_reply	Object	It carries the information of the clicked button
context	Object	This object contains the message information from which the button was clicked
context.from	String	Sender Phone of replied message
context.id	String	Message ID of replied message

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

Key / Object	Data Type	Description
id	String	ID of the clicked button
title	String	Title / 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}"
}

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

Key / Object	Data Type	Description
type	String	It carries interactive
interactive	Object	This object carries information about the clicked interactive button/list
interactive.type	String	It carries list_reply
interactive.list_reply	Object	It carries the information of the selected list item
context	Object	This object contains the message information from which the button was clicked
context.from	String	Sender Phone of replied message
context.id	String	Message ID of replied message

List Reply Object Explanation: Covers only keys related to list_reply object.

Key / Object	Data Type	Description
id	String	ID of the selected List Item
title	String	Title / Label of the selected List Item
description	String	Description 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");
?>