Configure WhatsApp Callback

Webhooks are user-defined HTTP callbacks that are triggered by specific events.
Whenever the trigger event occurs, the WhatsApp Business API client sees the event, collects the data, and immediately sends a notification (HTTP request) to the Webhook URL specified in the application settings by updating the status of sent messages or indicating when you receive a message. These requests are known as webhooks or callbacks.

The WhatsApp Callbacks page has the following topics:

Status Callback

When a message is sent to the end-user, the client needs to know about the message status (sent, delivered, read, and failed), such messages are referred to as Status Callback.

The following are the scenarios used for Status Callback.

Sent Message Status

Delivered Message Status

Read Message Status

Incoming Message Callback

Webhooks handle incoming messages from people who respond to you on WhatsApp including text, location, and media (Image, Audio, Video, and Document) as well as the status of the messages you have sent.

The Incoming Message Callback section has the following topics:

Incoming Text

If a user is replying with a text message, such messages are referred to as Incoming text.
Example: Text Message Received
The following is an example of a text message received from a customer.
{
  "contacts": [ {
    "profile": {
        "name": "Test"
    },
    "wa_id": "1XXXXXXXX34"
  } ],
  "messages":[{
    "from": "1XXXXXXXX63",
    "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
    "timestamp": "15XXXXX186",
    "text": {
      "body": "Hello this is an answer"
    },
    "type": "text"
  }]
}

Incoming Media

If a user is replying with media (Image, Audio, Video, and Document) messages, such messages are referred to as Incoming Media.
When you receive a message with media, the WhatsApp Business API client will download the media. A notification is sent to your Webbook once the media is downloaded. This notification contains information that identifies the media object and enables you to find and retrieve the object.

Incoming Location

If a user is sending location messages, such messages are referred to as Incoming Location.
Example: Static Location Message Received
The following is an example of a message received from a customer specifying their static location.

{
  "contacts": [ {
    "profile": {
        "name": "Test"
    },
    "wa_id": "1XXXXXXXX634"
  } ],
 "messages":[{
   "from":"1XXXXXXXX63",
   "id":"ABGGFlA5FpafAgo6tHcNmNjXmuSf",
   "location":{
      "address":"Main Street Beach, Santa Cruz, CA",
      "latitude":38.98XXXXX095,
      "longitude":-131.94XXXXX257,
      "name":"Main Street Beach",
      "url":"https://foursquare.com/v/4d7031d35b5df7744"},
   "timestamp":"1521497875",
   "type":"location"
  }]
}

Reply to Messages

When you select and reply to the messages, you have Reply to Interactive List and Reply to Interactive Reply Buttons.

Reply to Interactive List

Example: Customer Replied to a List Message
{
   "messages": [ {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
          "type": "list_reply",
          "list_reply": {
            "title": "row-title-content-here",
            "id": "unique-row-identifier-here",
            "description": "row-description-content-here"
          }
      }
   }

Reply to Interactive Reply Buttons

Example: Customer Replied to a Reply Button Message
{
  "messages": [ 
    {
      "context": {
        "from": "sender_wa_id_of_context_message",
        "group_id": "group_id_of_context_message",
        "id": "message_id_of_context_message",
        "mentions": [ "wa_id1", "wa_id2" ]
      },
      "from": "sender_wa_id",
      "group_id": "group_id",
      "id": "message_id",
      "timestamp": "message_timestamp",
      "type": "interactive",
      "interactive": {
        "type": "button_reply",
        "button_reply": {
          "id": "unique-button-identifier",
          "title": "button-text"
          },
       }

To send a reply button message, you must assemble an interactive object of type button with the following components. For more information, see Interactive Object section in List Message API .

Callback URL

The Callback URL is the end-point where you can receive the status of the message, view the timestamp of the message, and receive the incoming messages on your WhatsApp Business number.

  • To receive Status callbacks, you must send the Callback URL in the message API under the parameter "callback_url".
  • To receive Incoming messages, you must configure the Callback URL in the WhatsApp Number details page.
    The Status callback and Incoming callback endpoints can be the same or different based on your use case.

📘

Note:

Whitelisting the Callback URL is mandatory before passing the Callback URL.
Refer to the below section on Whitelisting the WhatsApp Callback URL for detailed information.

Below are the statuses of the messages:

  • Sent
  • Delivered
  • Read
  • Failed
https: //webhook.site/22b91760-1da9-41d9-a806-1c681bb254fe?id=a2d4ef99-fa14-4487-ab3a-d245b65611a4%3A2&phone_number=%20%20+1202XXXXXXX&status=delivered&timestamp=1580972783"url":"https://whatsapp-mediamnt-sg.s3.ap-southeast-1.amazonaws.com/Z5bf5d8/1607494833355_9019fee8-3247-425e-a691-7a2924da9058.jpg"
ValueDescription
a2d4ef99-fa14-4487-ab3a-d245b65611a4%3A2unique id
phone_number=+1202XXXXXXXyour phone number
timestamp=1580972783time which the callback is received

In case the status is 'Failed', the reason is displayed.

https://webhook.site/22XXXXX9-949a-448b-ad78-28XXXXXXXX20?body=&phone_number=%20%20+1202XXXXXXX&company_id=Z5XXXX8&created_at=160XXXXX74&from=919XXXXX9019&media_name=9019fee8-3247-XXXX-a691-7a2924daXX58&media_url=https://whatsapp-media-mnt-sg.s3.ap-southeast-1.amazonaws.com/Z5bf5d8/16XXXXXXXX074_9019fee8-3247-425e-a691-7a2XXXX99058.jpg&message=[{"from":"91XXXXX99819","timestamp":"160XXX4827","url":"https://whatsapp-mediamnt-sg.s3.ap-southeast-1.amazonaws.com/Z5bf5d8/1607XXXXX4945_9019fee8-3247-425e-a691-7a29XXXXX248.jpg","type":"image","profile":{"name":"test ","wa_number":"919901819819"}]&mime_type=image/jpeg&mobile=91XXXXXXX919&name=test&reply_to=afe9bda2-4b8f-4ce7-b91b-58fd8e8912d4&type=image&wanumber=918XXXXX0128
ValueDescription
phone_number=+1202XXXXXXXyour phone number.
company_id="Z5bf5d8"unique identifier of the company.
from="159901819819"customer's WhatsApp number
media_name ="9019fee8-3247-425e-a691-7a2924da9058"name of the media
media_url ="https://whatsapp-media-mnt-sg.s3.ap-southeast-1.amazonaws.com/Z5bf5d8/1607494833355_9019fee8-3247-425e-a691-7a2924da9058.jpg"location of the media file
"timestamp":"1607494827"callback received time
"profile":{"name":"test ","wa_number":"919901819819"}profile name and number

Whitelisting the WhatsApp Callback URL

To whitelist the WhatsApp Callback URL, perform the following steps:

  1. Sign in to your Kaleyra.io account using valid credentials.
  2. Click on the profile name and click Settings.
  3. On the Settings page click the Settings tab as shown below.

  1. The customer can now whitelist one or more WhatsApp Callback URLs by entering the Callback URL domains.
  2. Click Save. The above WhatsApp Callback URLs are now whitelisted and ready to use in WhatsApp APIs.

📘

Note:

  • If the URL is not whitelisted, then the message will still get delivered but no Callback will be made.

Facebook Documentation

Error Code

Error CodeParameterDescription
E413callback_urlThe Callback URL format is invalid.