×

Receive messages webhook can be passed in status_callback parameter in send message/template message APIs to receive replies on messages from the business. To receive any message from an end user which is not a reply to a business message, a default callback value needs to be configured. Exotel team will help you configure the default URL while onboarding.

  • If you pass receive messages webhook in send message/template message APIs, reply messages from users will be triggered to the respective URL 
  • If you do not pass any receive messages webhook in send message/template message APIs, reply messages from users will be triggered to the default URL, if any.
  • All user initiated conversations and messages which are not a reply on business message, will be triggered to the default URL

*NOTE: Any messages from an user can be received only in one webhook at any time

Webhook Parameter

Parameter

Type

Mandatory

Notes

whatsapp

Message ICM Object

Mandatory

Incoming message callback for Whatsapp

Message ICM Object

Parameter

Type

Mandatory

Notes

messages

[]Whatsapp Message ICM Object

Mandatory

Information relating to the incoming messages from the end-users

Whatsapp Message ICM Object

Parameter

Type

Mandatory

Notes

callback_type

String

Mandatory

Type of the callback. Possible values: dlr/icm

from

String

Mandatory

Number of the end user who has sent the incoming message to the business

to

String

Mandatory

Business number to whom the message was sent

profile_name

String

Mandatory

Profile Name of the user who has sent the incoming message

timestamp

String

Mandatory

Timestamp at which incoming message was sent

content

Content Object

Mandatory

Content related to the incoming message

Content Object

Parameter

Type

Mandatory

Notes

type

String

Mandatory

Type of the message

text

TextObject

Optional

Mandatory if type is text

image

MediaResponseObject

Optional

Mandatory if type is image

audio

MediaResponseObject

Optional

Mandatory if type is audio

sticker

MediaResponseObject

Optional

Mandatory if type is sticker

video

MediaResponseObject

Optional

Mandatory if type is video

document

MediaResponseObject

Optional

Mandatory if type is document

error

MessageICMErrorObject

Optional

If there is an error

Media Response Object

Parameter

Type

Mandatory

Notes

url

String

Mandatory

URL to download the media

caption

String

Optional

Caption for the media. Describes the specified media.

filename

String

Optional

This is passed if the media is document. Describes the filename for the specific document. 

The extension of the filename will specify what format the document is displayed as in WhatsApp.

Message ICM Error Object

Parameter

Type

Mandatory

Notes

exo_status_code

Integer

Mandatory

Exo Status Code for the error

exo_detailed_status

String

Mandatory

Detailed Status of the Exo Status Code

description

String

Mandatory

Description of the Exo Status code
  • Incoming Text Whatsapp message from an end-user
{
   "whatsapp": {
     "messages": [
       {
         "callback_type": "incoming_message",
         "from": "1234",
         "profile_name": "John",
         "to": "5698",
         "timestamp": "1235654654",
         "content": {
           "type": "text",
           "text": {
             "body": "This is a text message from Whatsapp"
           }
         }
       }
     ]
   }
 }
  • Incoming Text WhatsApp message when clicked on a Quick Reply button
{
  "whatsapp": {
    "messages": [
      {
        "callback_type": "incoming_message",
        "sid": "b4352d7XXXXXXX",
        "from": "+9199XXXXXXXX",
        "to": "+9180XXXXXXXX",
        "timestamp": "2024-09-16T17:05:35+05:30",
        "profile_name": "KXXXXX",
        "content": {
          "type": "button",
          "context": {
            "sid": "b4352d7XXXXXXX"
          },
          "button": {
            "payload": "Good",
            "text": "Good"
          }
        }
      }
    ]
  }
}
  • Incoming Text WhatsApp message when clicked on a List button
{
  "whatsapp": {
    "messages": [
      {
        "callback_type": "incoming_message",
        "sid": "2f77028adcb7XXXXXX",
        "from": "+9199XXXXXXXX",
        "to": "+9180XXXXXXXX",
        "timestamp": "2024-09-16T17:05:01+05:30",
        "profile_name": "KXXXXXX",
        "content": {
          "type": "interactive",
          "context": {
            "sid": "95126d4462XXXXX"
          },
          "interactive": {
            "type": "list_reply",
            "list_reply": {
              "id": "1",
              "title": "./Time: 10:00",
              "description": "./Place: Whitefield, Bangalore"
            }
          }
        }
      }
    ]
  }
}
  • Incoming Image Whatsapp message from an end-user 
{
   "whatsapp": {
     "messages": [
       {
         "callback_type": "incoming_message",
         "from": "1234",
         "profile_name": "John",
         "to": "5698",
         "timestamp": "1235654654",
         "content": {
           "type": "image",
           "image": {
             "url": "https://exotel.com/abc.jpeg",
             "caption": "Hello this is image from Whatsapp"
           }
         }
       }
     ]
   }
 }
  • Error status code for an Incoming message from an end-user
{
   "whatsapp": {
     "messages": [
       {
         "callback_type": "incoming_message",
         "from": "1234",
         "profile_name": "John",
         "to": "5698",
         "timestamp": "1235654654",
         "content": {
“type”: “unsupported”,
           "error": {
             "exo_status_code": 24501,
             "exo_detailed_status": "EX_UNSUPPORTED_MEDIA_TYPE",
             "description": "The media type is currently not supported"
           }
         }
       }
     ]
   }
 }