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
- Incoming Media (Image/Audio/video)
- Incoming Location
- Reply to Messages
a) Reply to Interactive List
b) Reply to Interactive Reply Buttons
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×tamp=1580972783"url":"https://whatsapp-mediamnt-sg.s3.ap-southeast-1.amazonaws.com/Z5bf5d8/1607494833355_9019fee8-3247-425e-a691-7a2924da9058.jpg"
Value | Description |
---|---|
a2d4ef99-fa14-4487-ab3a-d245b65611a4%3A2 | unique id |
phone_number=+1202XXXXXXX | your phone number |
timestamp=1580972783 | time 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
Value | Description |
---|---|
phone_number=+1202XXXXXXX | your 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:
- Sign in to your Kaleyra.io account using valid credentials.
- Click on the profile name and click Settings.
- On the Settings page click the Settings tab as shown below.
- The customer can now whitelist one or more WhatsApp Callback URLs by entering the Callback URL domains.
- 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 Code | Parameter | Description |
---|---|---|
E413 | callback_url | The Callback URL format is invalid. |
Updated 4 months ago