Learn how to use our serverless platform to create voice, video and messaging applications and services by reading our getting started guide. It's the best way to become familiar with the platform architecture and capabilities.
The WhatsApp Business API is a programmable API, allowing businesses to Broadcast & Receive Unlimited messages to a Global audience & drive better customer experiences on WhatsApp. Business can create templates, broadcast campaigns, manage rich media, and access reporting and analytics.
Please note that A message can be sent via API, only if the user has communicated to the WhatsApp Business number in the last 24 hours.
A text message can be a maximum of 4096 characters long. The maximum file size foruploaded media is 100MB.
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization:
AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "text",
"text": {
"body": "<Message Text With URL>",
"preview_url": false
}
}
}'
Variable | Value | Device Screenshot |
---|---|---|
body | The message to be sent | |
preview_url | Add only if you wish to see thumbnail of url added in text response. |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY \
--header 'Content-Type: application/json' \
--data-raw '{
"to": "91XXXXXXXXXX",
"type": "text",
"text": {
"preview_url": false,
"body": "Hi, What can I do for you?"
}
}'
Please replace 91xxxxxxxx with the number you want to use for sending.
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "image",
"image": {
"link": "<Link to Image, https>",
"caption": "<Media Caption>"
}
}
}'
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "image",
"image": {
"id": "<Media Id, from Media API>",
"caption": "<Media Caption>"
}
}
}'
Variable | Value | Device Screenshot |
---|---|---|
id (string) | your-media-id (Example: Either id or link is required but should not be used at the same time.) | |
link (string) | your-media-url (Example: Required when type is audio,document, image, sticker, or video and you are not using an uploaded media ID.) | |
caption (string) | Describes the specified image or video media. (Example: Do not use with audio, document, or sticker media.) |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "document",
"document": {
"link": "<Link to Doc, https>",
"caption": "<Media Caption>"
}
}
}'
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "document",
"document": {
"id": "<Media Id, from Media API>",
"caption": "<Media Caption>",
"filename": "<Filename>"
}
}
}'
Variable | Value | Device Screenshot |
---|---|---|
id (string) | your-media-id (Example: Either id or link is required but should not be used at the same time.) | |
link (string) | your-media-url (Example: Required when type is audio,document, image, sticker, or video and you are not using an uploaded media ID.) | |
caption (string) | Optional.Describes the specified image or video media. | |
filename (string) | Optional.Describes the filename for the specific document. Use only with document media.The extension of the filename will specify what format the document is displayed as in WhatsApp. |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "audio",
"audio": {
"link": "<Link to Audio, https>",
}
}
}'
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "audio",
"audio": {
"id": "<Media Id, from Media API>"
}
}
}'
Variable | Value | Device Screenshot |
---|---|---|
id (string) | your-media-id (Example: Either id or link is required but should not be used at the same time.) | |
link (string) | your-media-url (Example: Required when type is audio,document, image, sticker, or video and you are not using an uploaded media ID.) |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "video",
"video": {
"link": "<Link to Video, https>",
"caption": "<Media Caption>"
}
}
}'
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "video",
"video": {
"id": "<Media Id, from Media API>",
"caption": "<Media Caption>"
}
}
}'
Variable | Value | Device Screenshot |
---|---|---|
id (string) | your-media-id (Example: Either id or link is required but should not be used at the same time.) | |
link (string) | your-media-url (Example: Required when type is audio,document, image, sticker, or video and you are not using an uploaded media ID.) | |
caption (string) | Describes the specified image or video media. (Example: Do not use with audio, document, or sticker media.) |
Media | Supported Content-Types | Size |
---|---|---|
audio | audio/aac, audio/mp4, audio/amr,audio/mpeg, audio/ogg; codecs=opus Note: The base audio/ogg type is not supported. | 16 MB |
document | Any valid MIME-type. | 100 MB |
image | image/jpeg, image/png | 5 MB |
video | video/mp4, video/3gpp Notes: Only H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported. |
16 MB |
Sticker | Image/webp | Static Sticker : 100KB Animated Sticker : 500KB |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "location",
"location": {
"latitude": "<Longitude of the location>",
"longitude": "<Latitude of the location>",
"name": "<Name of the location>",
"address": "<Address of the location. Only displayed if name is present.>"
}
}
}'
Variable | Value | Device Screenshot |
---|---|---|
longitude | Required.Longitude of the location. | |
latitude | Required.Latitude of the location. | |
name | Optional.Name of the location. | |
address | Optional Address of the location. Only displayed if name is present |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "<Header List Message>"
},
"body": {
"text": "<List Body Message>"
},
"footer": {
"text": "<Footer Message>"
},
"action": {
"button": "Send",
"sections": [{
"title": "<List Category Item>",
"rows": [{
"id": "<Item ID>",
"title": "<Item Title>",
"description": "<Item Description>"
},
{
"id": "<Item ID>",
"title": "<Item Title>",
"description": "<Item Description>"
}
]
},
{
"title": "<List Category Item>",
"rows": [{
"id": "<Item ID>",
"title": "<Item Title>",
"description": "<Item Description>"
},
{
"id": "<Item ID>",
"title": "<Item Title>",
"description": "<Item Description>"
}
]
}
]
}
}
}'
Name | Description |
---|---|
action object |
Required.Action, you want the user to perform after reading the message. |
body object |
Optional for type product. Required for other message types.An object with the body of the message.The body object contains the following field:textstring – Required if body is present. The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. |
footer object |
Optional. An object with the footer of the message.The footer object contains the following field:textstring – Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length: 60 characters. |
header object |
Required for type product_list. Optional for other types. Header content displayed on top of a message. You cannot set a header if your interactive object is of product type. See header object for more information. |
type object |
Required. The type of interactive message you want to send. Supported values:
|
Name | Description |
---|---|
button string |
Required for List Messages.Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not.
Maximum length: 20 characters. |
buttons array of objects |
Required for Reply Buttons.A button object can contain the following parameters:
You can have up to 3 buttons. You cannot have leading or trailing spaces when setting the ID. |
catalog_id string |
Required for Single Product Messages and Multi-Product Messages.Unique identifier of the Facebook catalog linked to your WhatsApp Business Account. This ID can be retrieved via the Meta Commerce Manager.. |
product_retailer_id string |
Required for Single Product Messages and Multi-Product Messages. Unique identifier of the product in a catalog. To get this ID go to Meta Commerce Manager and select your Meta Business account. You will see a list of shops connected to your account. Click the shop you want to use. On the left-side panel, click Catalog > Items, and find the item you want to mention. The ID for that item is displayed under the item’s name. |
sections array of objects |
Required for List Messages and Multi-Product Messages. Array of section objects. Minimum of 1, maximum of 10. See section object. |
Name | Description |
---|---|
document object |
Required if type is set to document.Contains the media object for this document. |
image object |
Required if type is set to image.Contains the media object for this image. |
text string |
Required if type is set to text.Text for the header. Formatting allows emojis, but not markdown. Maximum length: 60 characters.. |
type string |
Required. The header type you would like to use. Supported values:
|
video object |
Required if type is set to video. Contains the media object for this video. |
Name | Description |
---|---|
product_items array of objects |
Required for Multi-Product Messages.Array of product objects. There is a minimum of 1 product per section and a maximum of 30 products across all sections.
Each product object contains the following field:
|
rows array of objects |
Required for List Messages.Contains a list of rows. You can have a total of 10 rows across your sections.
Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters),but it is optional. Example: copy
|
title string |
Required if the message has more than one section.Title of the section.
Maximum length: 24 characters. |
type string |
Required. The header type you would like to use. Supported values:
|
video object |
Required if type is set to video. Contains the media object for this video. |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": "{{Recipient-Phone-Number}}",
"from": "{optional - need to define when more than one phone number, if not define than system will use the default one}",
"type": "template",
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_AND_LOCALE_CODE"
},
"components": [{
"type": "body",
"parameters": [{
"type": "text",
"text": "text-string"
},
{
"type": "currency",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": NUMBER
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "DATE"
}
}
]
}]
}
}'
Name | Description |
---|---|
language object |
Required.Contains a language object. Specifies the language the template may be rendered in.
The language object can contain the following fields:
|
components array of objects |
Optional.Array of components objects containing the parameters of the message. |
namespace | Optional.Namespace of the template. |
name | Name of the template. |
The following objects are nested inside the template object:
Name | Description |
---|---|
type string |
Required.Indicates the type of parameter for the button. |
payload | Required for URL buttons.Developer-provided suffix that is appended to the predefined prefix URL in the template. |
type string |
Required.Indicates the type of parameter for the button. |
Name | Description |
---|---|
type | Required. |
string | Describes the component type. Example of a components object with an array of parameters object nested inside: copy
|
sub_type string |
Required when type=button. Not used for the other types.
|
parameters array of objects |
Required when type=button. Array of parameter objects with the content of the message. For components of type=button, see the button parameter object. |
index | Required when type=button. Not used for the other types. Only used for Cloud API.Position index of the button. You can have up to 3 buttons using index values of 0 to 2. |
type string |
Required. Describes the component type. Example of a components object with an array of parameters object nested inside: copy
|
Name | Description |
---|---|
fallback_value | Required. Default text if localization fails. |
code | Required.
|
amount_1000 | Required.Amount multiplied by 1000. |
fallback_value | Required.Default text if localization fails. |
code | Required.Currency code as defined in ISO 4217. |
Name | Description |
---|---|
fallback_value | Required. Default text. For Cloud API, we always use the fallback value, and we do not attempt to localize using other optional fields. |
Name | Description |
---|---|
type string |
Required. Describes the parameter type. Supported values:
For text-based templates, the only supported parameter types are currency, date_time,and text. |
text string |
Required when type=text. The message’s text. Character limit varies based on the following included component type For the header component type:
For the body component type:
|
currency object |
Required when type=currency.A currency object |
date_time object |
Required when type=date_time.A date_time object. |
copy
curl --location --request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/messages' \
--header 'Authorization: AUTHKEY ' \
--header 'Content-Type: application/json' \
--data-raw '{
"to": "PHONE_NUMBER",
"type": "contacts",
"contacts": [{
"addresses": [{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "HOME"
},
{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "WORK"
}
],
"birthday": "YEAR_MONTH_DAY",
"emails": [{
"email": "EMAIL",
"type": "WORK"
},
{
"email": "EMAIL",
"type": "HOME"
}
],
"name": {
"formatted_name": "NAME",
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"middle_name": "MIDDLE_NAME",
"suffix": "SUFFIX",
"prefix": "PREFIX"
},
"org": {
"company": "COMPANY",
"department": "DEPARTMENT",
"title": "TITLE"
},
"phones": [{
"phone": "PHONE_NUMBER",
"type": "HOME"
},
{
"phone": "PHONE_NUMBER",
"type": "WORK",
"wa_id": "PHONE_OR_WA_ID"
}
],
"urls": [{
"url": "URL",
"type": "WORK"
},
{
"url": "URL",
"type": "HOME"
}
]
}]
}'
Variable | Value | Device Screenshot |
---|---|---|
addresses object |
Optional. Full contact address(es) formatted as an addresses object. The object can contain the following fields: streetstring – Optional. Street number and name. citystring – Optional. City name statestring – Optional. State abbreviation zipstring – Optional. Zip Code countrystring – Optional. Full country name country_codestring – Optional. Two-letter country abbreviation. typestring – Optional. Standard values are HOME and WORK. |
|
birthday | Optional YYYY-MM-DD formatted string. | |
emails object |
Optional Contact email address(es) formatted as an emails object.The object can contain the following fields: emailstring – Optional. Email address. typestring – Optional. Standard values are HOME and WORK |
|
name object |
Required. Full contact name formatted as a name object. The object can contain the following fields: formatted_namestring – Required. Full name, as it normally appears. first_namestring – Optional*. First name. last_namestring – Optional*. Last name. middle_namestring – Optional*. Middle name. suffixstring – Optional*.Name suffix. prefixstring – Optional*. Name prefix. *At least one of the optional parameters needs to be included along with the formatted_name parameter. |
|
org object |
Optional. Contact organization information formatted as an org object. The object can contain the following fields: companystring – Optional. Name of the contact’s company. departmentstring – Optional. Name of the contact’s department. titlestring – Optional. Contact’s business title. phonesobject – Optional. Contact’s business title. |
|
phones object |
Optional. Contact phone number(s) formatted as a phone object. The object can contain the following fields: phonestring – Automatically populated with the `wa_id` value as a formatted phone number. typestring – Standard Values are CELL, MAIN, IPHONE, HOME, and WORK. wa_idstring – WhatsApp ID |
|
urls object |
Optional. Contact URL(s) formatted as a urls object. The object can contain the following fields: urlstring – URL typestring – Standard values are HOME and WORK |
|
addresses object |
Optional. Full contact address(es) formatted as an addresses object. The object can contain the following fields: streetstring – Street number and name. citystring – City name. statestring – State abbreviation. name. zipstring – ZIP code. countrystring – Full country name. country_codestring – Two-letter country abbreviation. typesstring – Standard values are HOME and WORK. |
Parameters | Description |
---|---|
file | Required Path to the file stored in your local directory. For example: “@/local/path/file.jpg”. |
type | Required Type of media file being uploaded. Supported options for images are:
Supported options for documents are:
Supported options for audio are:
Supported options for video are:
Supported options for stickers are:
|
messaging_product | Required. Messaging service used for the request. In this case,use whatsapp. |
copy
curl --location --
request POST 'https://api.apigw.tatacommunications.com/v1/whatsapp/media' \
--header 'Authorization: ' \
--form 'messaging_product="whatsapp"' \
--form 'file=@"<FILE_LOCATION>"'
copy
{
"id":"<MEDIA_ID>"
}
A successful response returns an object with the uploaded media’s ID:
To retrieve your media’s URL, send a GET request to /MEDIA_ID. Use the returned URL to download the media file. Note that clicking this URL (i.e. performing a generic GET) will not return the media; you must include an access token.
copy
curl -X GET 'https://api.apigw.tatacommunications.com/v1/whatsapp/MEDIA_ID>/'
\
-H 'Authorization: '
A successful response includes an object with a media url. The URL is only valid for 5 minutes.
copy
{
"messaging_product": "whatsapp",
"url": "<URL>",
"mime_type": "<MIME_TYPE>",
"sha256": "<HASH>",
"file_size": "<FILE_SIZE>",
"id": "<MEDIA_ID>"
}
To delete media, make a DELETE call to the ID of the media you want to delete.
copy
curl -X DELETE
'https://api.apigw.tatacommunications.com/v1/whatsapp/' \
-H 'Authorization: '
copy
{
"success": true
}
To download media, make a GET call to your media’s URL. All media URLs expire after 5 minutes —you need to retrieve the media URL again if it expires. If you directly click on the URL you get from a /MEDIA_ID GET call, you get an access error.
copy
curl \
'URL' \
-H 'Authorization: ACCESS_TOKEN' > media_file
If successful, you will receive the binary data of media saved in media_file, response headers contain a content-type header to indicate the mime type of returned data. If media fails to download, you will receive a 404 Not Found response code. In that case, we recommend you try to retrieve a new media URL and download it again. If doing so doesn’t resolve the issue, please try to renew the ACCESS_TOKEN then retry downloading the media.
The maximum supported file size for media messages on Cloud API is 100MB. In the event the customer sends a file that is greater than 100MB, you will receive a webhook with error code 131052 and title:
“Media file size too big. Max file size we currently support: 100MB. Please communicate with your customer to send a media file that is smaller than 100MB”. We advise that you send customers a warning message that their media file exceeds the maximum file size when this webhook event is triggered.
The analytics field provides the number and type of messages sent and delivered by the phone numbers associated with a specific WABA
Parameters | Description |
---|---|
start type: UNIX Timestamp |
Required. The start date for the date range you are retrieving analytics for. |
end type: UNIX Timestamp |
Required. The end date for the date range you are retrieving analytics for. |
granularity type: String Supported Options |
Required. The granularity by which you would like to retrieve the analytics.
|
phone_numbers type: Array |
Optional. An array of phone numbers for which you would like to retrieve analytics. If not provided, all phone numbers added to your WABA are included. |
product_types type: Array |
Optional. The types of messages (notification messages and/or customer support messages) for which you want to retrieve notifications. Provide an array and include 0 for notification messages, and 2 for customer support messages. If not provided, analytics will be returned for all messages together. |
country_codes type: Array |
Optional. The countries for which you would like to retrieve analytics. Provide an array with 2 letter country codes for the countries you would like to include. If not provided, analytics will be returned for all countries you have communicated with. |
Scenario: You need to get the number of messages sent and delivered by all phone numbers associated
with your WABA.
Suggested Solution: Assemble the URL you want to call and include the following filtering parameters: start, end, granularity. Then, make a GET request to that URL:
copy
curl -i -X GET \
"https://api.apigw.tatacommunications.com/v1/whatsapp/metrics
?fields=analytics
.start(1543543200)
.end(1544148000)
.granularity(DAY)
&access_token={access-token}"
A successful response returns an analytics object with the data you have requested:
copy
{
"analytics": {
"phone_numbers": [
"16505550111",
"16505550112"
],
"country_codes": [
"US",
"BR"
],
"granularity": "DAY",
"data_points": [{
"start": 1543543200,
"end": 1543629600,
"sent": 196093,
"delivered": 179715
},
{
"start": 1543629600,
"end": 1543716000,
"sent": 147649,
"delivered": 139032
},
# more data points
]
},
"id": "952305634918047"
}
The following is an example of a text message you received from a customer:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"text": {
"body": "MESSAGE_BODY"
},
"type": "text"
}]
},
"field": "messages"
}]
}]
}
The following is an example of a reaction message you received from a customer. You will not receive this webbook if the message the customer is reacting to is more than 30 days old.
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"reaction": {
"message_id": "MESSAGE_ID",
"emoji": "EMOJI"
},
"type": "reaction"
}]
},
"field": "messages"
}]
}]
}
When a message with media is received, the WhatsApp Business Platform downloads the media. A notification is sent to your Webhook once the media is downloaded.The Webhook notification contains information that identifies the media object and enables you to find and retrieve the object. Use the media endpoints to retrieve the media.
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"type": "image",
"image": {
"caption": "CAPTION",
"mime_type": "image/jpeg",
"sha256": "IMAGE_HASH",
"id": "ID"
}
}]
},
"field": "messages"
}]
}]
}
When you receive a sticker, you will get the following notification:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "ID"
}],
"messages": [{
"from": "SENDER_PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"type": "sticker",
"sticker": {
"mime_type": "image/webp",
"sha256": "HA
}
}]
},
"field": "messages"
}]
}]
}
It’s possible to receive an unknown message callback notification. For example, a customer could send you a message that’s not supported, such as a disappearing message (in which case we’d notify the customer that the message type is not supported).The following is an example of a message you received from a customer that is not supported.
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"errors": [{
"code": 131051,
"details": "Message type is not currently supported",
"title": "Unsupported message type"
}],
"type": "unknown"
}]
},
"field": "messages"
}]
}]
}
The following is an example of a location message you received from a customer:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"location": {
"latitude": LOCATION_LATITUDE,
"longitude": LOCATION_LONGITUDE,
"name": LOCATION_NAME,
"address": LOCATION_ADDRESS,
}
}]
},
"field": "messages"
}]
}]
}
The following is an example of a contact message you received from a customer:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"from": "PHONE_NUMBER",
"id": "wamid.ID",
"timestamp": "TIMESTAMP",
"contacts": [{
"addresses": [{
"city": "CONTACT_CITY",
"country": "CONTACT_COUNTRY",
"country_code": "CONTACT_COUNTRY_CODE",
"state": "CONTACT_STATE",
"street": "CONTACT_STREET",
"type": "HOME or WORK",
"zip": "CONTACT_ZIP"
}],
"birthday": "CONTACT_BIRTHDAY",
"emails": [{
"email": "CONTACT_EMAIL",
"type": "WORK or HOME"
}],
"name": {
"formatted_name": "CONTACT_FORMATTED_NAME",
"first_name": "CONTACT_FIRST_NAME",
"last_name": "CONTACT_LAST_NAME",
"middle_name": "CONTACT_MIDDLE_NAME",
"suffix": "CONTACT_SUFFIX",
"prefix": "CONTACT_PREFIX"
},
"org": {
"company": "CONTACT_ORG_COMPANY",
"department": "CONTACT_ORG_DEPARTMENT",
"title": "CONTACT_ORG_TITLE"
},
"phones": [{
"phone": "CONTACT_PHONE",
"wa_id": "CONTACT_WA_ID",
"type": "HOME or WORK"
}],
"urls": [{
"url": "CONTACT_URL",
"type": "HOME or WORK"
}]
}]
}]
},
"field": "messages"
}]
}]
}
When your customer clicks on a quick reply button in an interactive message template, a response is sent. Below is an example of the callback format.
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "WHATSAPP_ID"
}],
"messages": [{
"context": {
"from": PHONE_NUMBER,
"id": "wamid.ID"
},
"from": "16315551234",
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"type": "button",
"button": {
"text": "No",
"payload": "No-Button-Payload"
}
}]
},
"field": "messages"
}]
}]
}
The following webhook notification is received when a user clicks on an item from a list message you sent:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID",
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}],
"messages": [{
"from": PHONE_NUMBER_ID,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"interactive": {
"list_reply": {
"id": "list_reply_id",
"title": "list_reply_title",
"description": "list_reply_description"
},
"type": "list_reply"
},
"type": "interactive"
}]
},
"field": "messages"
}]
}]
}
The following webhook notification is received when a user clicks on a reply button you sent:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": PHONE_NUMBER_ID,
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": "PHONE_NUMBER_ID"
}],
"messages": [{
"from": PHONE_NUMBER_ID,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"interactive": {
"button_reply": {
"id": "unique-button-identifier-here",
"title": "button-text",
},
"type": "button_reply"
},
"type": "interactive"
}]
},
"field": "messages"
}]
}]
}
The following notification is received when a business sends a message as part of a user-initiated conversation (if that conversation did not originate in a free entry point):
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"statuses": [{
"id": "WHATSAPP_MESSAGE_ID",
"status": "sent",
"timestamp": "TIMESTAMP",
"recipient_id": "CUSTOMER_PHONE_NUMBER",
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": "CONVERSATION_EXPIRATION_TIMESTAMP",
"origin": {
"type": "user_initiated"
}
},
"pricing": {
"billable": true,
"pricing_model": "CBP",
"category": "user_initiated"
}
}]
},
"field": "messages"
}]
}]
}
The following notification is received when a business sends a message as part of a business-initiated conversation:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"statuses": [{
"id": "wamid.ID",
"recipient_id": "PHONE_NUMBER",
"status": "sent",
"timestamp": "TIMESTAMP",
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "business_initated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "business_initated"
}
}]
},
"field": "messages"
}]
}]
}
The following notification is received when a business sends a message in reply to a user-initiated conversation originating from free entry points:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"statuses": [{
"id": "wamid.ID",
"status": "sent",
"timestamp": TIMESTAMP,
"recipient_id": PHONE_NUMBER,
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "referral_conversion"
}
},
"pricing": {
"billable": false,
"pricing_model": "CBP",
"category": "referral_conversion"
}
}]
},
"field": "messages"
}]
}]
}
The following notification is received when a business’ message is delivered and that message is part of a user-initiated conversation (if that conversation did not originate in a free entry point):
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"statuses": [{
"id": "wamid.ID",
"recipient_id": "PHONE_NUMBER",
"status": "delivered",
"timestamp": "TIMESTAMP",
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin": {
"type": "user_initiated"
}
},
"pricing": {
"pricing_model": "CBP",
"billable": true,
"category": "user_initiated"
}
}]
},
"field": "messages"
}]
}]
}
The following notification is received when a business’ message is delivered and that message is part of a user-initiated conversation originating from a free entry point:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "PHONE_NUMBER",
"phone_number_id": "PHONE_NUMBER_ID"
},
"statuses": [{
"id": "wamid.ID",
"status": "sent",
"timestamp": "TIMESTAMP",
"recipient_id": "PHONE_NUMBER",
"conversation": {
"id": "CONVERSATION_ID",
"expiration_timestamp": TIMESTAMP,
"origin" {
"type": "referral_conversion"
}
},
"pricing": {
"billable": false,
"pricing_model": "CBP",
"category": "referral_conversion"
}
}]
},
"field": "messages"
}]
}]
}
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "BUSINESS_DISPLAY_PHONE_NUMBER",
"phone_number_id": "BUSINESS_PHONE_NUMBER_ID"
},
"statuses": [{
"id": "WHATSAPP_MESSAGE_ID",
"status": "read",
"timestamp": "TIMESTAMP",
"recipient_id": "CUSTOMER_PHONE_NUMBER"
}]
},
"field": "messages"
}]
}]
}
Currently, the Cloud API does not support webhook status updates for deleted messages. If a user deletes a message, you will receive a webhook with an error code for an unsupported message type:
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER
},
"contacts": [{
"profile": {
"name": "NAME"
},
"wa_id": PHONE_NUMBER
}],
"messages": [{
"from": PHONE_NUMBER,
"id": "wamid.ID",
"timestamp": TIMESTAMP,
"errors": [{
"code": 131051,
"details": "Message type is not currently supported",
"title": "Unsupported message type"
}],
"type": "unsupported"
}]
},
"field": "messages"
}]
}]
}
copy
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
"changes": [{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": PHONE_NUMBER,
"phone_number_id": PHONE_NUMBER_ID
},
"statuses": [{
"id": "wamid.ID",
"status": "failed",
"timestamp": TIMESTAMP,
"recipient_id": PHONE_NUMBER,
"errors": [{
"code": 131014,
"title": "Request for url https://URL.jpg failed with error: 404 (Not Found)"
}]
}]
},
"field": "messages"
}]
}]
}
Anonymize, Authenticate, Programmable SMS
Please fill in your details below and we will get in touch with you shortly
One of our team members will be in contact soon.
Please fill in your details below and we will get in touch with you shortly
One of our team members will be in contact soon.
Please fill in your details below
One of our team members will be in contact soon.
You will need auth token to access our APIs. Please fill in your details below and we will get in touch with you.
One of our team members will be in contact soon.
By continuing to browse the site, you are accepting our use of cookies. To find out more about the cookies we use, please read our Cookie Policy.
Accept All CookiesCookie Policy