Configure WhatsApp Callback URL

Webhooks are user-defined HTTP callbacks that are triggered by specific events.
Whenever the trigger event occurs, the kaleyra.io WhatsApp Business API client recognizes the event, collects the data, and immediately sends a notification (HTTPS request) to the Webhook URL specified in the kaleyra.io settings by providing the relevant information related to the trigger event.

For example, a change in the message status or an incoming message.

The WhatsApp Callbacks user guide covers the following topics:

• Status Callback
• Incoming Message Callback
• Callback URL

Status Callback

When a message is sent to the end-user, the status callback provides information to the client about the message status (not-sent, sent, delivered, read, or failed).

The following are the scenarios used for Status Callback.

Sent Message Status

Not-Sent Message status

Delivered Message Status

Read Message Status

Failed Message Status

📘

Note:

• For the postpaid account type, the price value exists in the callbacks for Delivered status whenever that message opens a conversation and it is hence charged.
• For the Tech Provider account type, the price parameter is not supported.

Limitations

• The callback about the delivered message that opened any of the first 1000 free service conversations will have a price key-value pair shown in the callbacks even though the price will not be actually charged.

You must configure the Callback Profile for WhatsApp Outgoing Messages Status Update to receive notifications regarding the WhatsApp message status (not-sent, sent, delivered, read, or failed) for all the messages sent using your registered business WhatsApp number. You need first to create a Callback Profile ID (GET or POST method) and then add the same in the Send Message template/session API payload of the callback_profile_id parameter.

Incoming Message Callback

The example mentioned on the page are examples of Webhooks received from META on different types of replies.

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
• Incoming Media (Image/Audio/video)
• Incoming Location
• Reply to Messages
  a) Reply to Interactive List
  b) Reply to Interactive Reply Buttons

Incoming Text

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

Reply to Interactive List

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

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

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

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.

4. The customer can now whitelist one or more WhatsApp Callback URLs by entering the Callback URL domains.
5. 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

developers.facebook.com

Inbound Notifications - WhatsApp Business API - Documentation - Facebook for Developers

Error Code