Documentation and APIs

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.

Number Management

SMS

Anonymize

Authenticate – OTP

Authenticate – One Tap Authentication

Engage

Programmable Voice(India)

Programmable Voice (USA)

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

Send Message

Text

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.

Example

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.

Image Message

Image Message BY URL

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>"
        }
    }
}'

Image Message BY 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": "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.)

Document

Document Message BY URL

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>"
        }
    }
}'

Document Message BY 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": "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.

Audio

Audio Message BY URL

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>",
        }
    }
}'

Audio Message BY 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": "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.)

Video

Video Message BY URL

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>"
        }
    }
}'

Video Message BY 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": {
            "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.)

Supported media types and sizes

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

Location

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

List Message

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: button: Use it for Reply Buttons list: Use it for List Messages. product: Use for Single Product Messages. product_list: Use for Multi-Product Messages.

Action Object:

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: type: only supported type is reply (for Reply Button) title: Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. id: Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. 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.

Header 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: text: Used for List Messages, Reply Buttons, and Multi-Product Messages video: Used for Reply Buttons. image: Used for Reply Buttons. document: Used for Reply Buttons.
video object	Required if type is set to video. Contains the media object for this video.

Section Object:

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: product_retailer_idstring – Required for Multi-Product Messages. Unique identifier of the product in a catalog. To get this ID, go to the Meta Commerce Manager, select your account and the shop you want to use. Then, click Catalog > Items, and find the item you want to mention. The ID for that item is displayed under the item’s name.
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 `"rows": [{ "id": "unique-row-identifier-here", "title": "row-title-content-here", "description": "row-description-content-here", }]`
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: text: Used for List Messages, Reply Buttons, and Multi-Product Messages video: Used for Reply Buttons. image: Used for Reply Buttons. document: Used for Reply Buttons.
video object	Required if type is set to video. Contains the media object for this video.

Text-Based Message Template

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: policy string – Required. The language policy the message should follow. The only supported option is deterministic. code string – Required. The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US). For all codes,see Supported Languages.
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:

Button Parameter 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.

Components Object

Name	Description
type	Required.
string	Describes the component type. Example of a components object with an array of parameters object nested inside: copy `"components": [{ "type": "body", "parameters": [{ "type": "text", "text": "name" }, { "type": "text", "text": "Hi there" } ] }]`
sub_type string	Required when type=button. Not used for the other types. Type of button to create.
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 `"components": [{ "type": "body", "parameters": [{ "type": "text", "text": "name" }, { "type": "text", "text": "Hi there" } ] }]`

Currency Object

Name	Description
fallback_value	Required. Default text if localization fails.
code	Required. Currency code as defined in ISO 4217.
amount_1000	Required. Amount multiplied by 1000.
fallback_value	Required. Default text if localization fails.
code	Required. Currency code as defined in ISO 4217.

Date_Time Object

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.

Parameter Object

Name	Description
type string	Required. Describes the parameter type. Supported values: currency date_time document image text video 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: 60 characters For the body component type: 1024 characters if other component types are included 32768 characters if body is the only component type included
currency object	Required when type=currency. A currency object
date_time object	Required when type=date_time. A date_time object.

Contact

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.

Media

Upload Media

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: image/jpeg image/png Supported options for documents are: text/plain application/pdf application/vnd.ms-powerpoint application/msword application/vnd.ms-excel application/vnd.openxmlformatsofficedocument.wordprocessingml.document application/vnd.openxmlformatsofficedocument.presentationml.presentation application/vnd.openxmlformatsofficedocument.spreadsheetml.sheet Supported options for audio are: audio/aac audio/mp4 audio/mpeg audio/amr audio/ogg audio/opus Supported options for video are: video/mp4 video/3gp Supported options for stickers are: image/webp
messaging_product	Required. Messaging service used for the request. In this case,use whatsapp.

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:

image/jpeg
image/png

Supported options for documents are:

text/plain
application/pdf
application/vnd.ms-powerpoint
application/msword
application/vnd.ms-excel
application/vnd.openxmlformatsofficedocument.wordprocessingml.document
application/vnd.openxmlformatsofficedocument.presentationml.presentation
application/vnd.openxmlformatsofficedocument.spreadsheetml.sheet

Supported options for audio are:

audio/aac
audio/mp4
audio/mpeg
audio/amr
audio/ogg
audio/opus

Supported options for video are:

video/mp4
video/3gp

Supported options for stickers are:

image/webp

messaging_product

Required.
Messaging service used for the request. In this case,use whatsapp.

Example

Sample request:

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:

Retrieve Media URL

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.

Example

Sample request:

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

Delete Media

To delete media, make a DELETE call to the ID of the media you want to delete.

Example

Sample request:

copy

curl -X DELETE
'https://api.apigw.tatacommunications.com/v1/whatsapp/' \
-H 'Authorization: '

Sample response:

copy

{
    "success": true
}

Download Media

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.

Example

Sample request:

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.

Media message download constraints

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.

Reporting

Analytics

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. HALF_HOUR DAY MONTH
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.

Example

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

Webhook Payload

Text webhook format

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"
        }]
    }]
}

Reaction message webhook format

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"
        }]
    }]
}

Media Messages webhook format

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"
        }]
    }]
}

Unknown Message

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"
        }]
    }]
}

Location Messages Webhook Format

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"
        }]
    }]
}

Contact Messages Webhook Format

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"
        }]
    }]
}

Received Callback from a Quick Reply Button

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"
        }]
    }]
}

Received Answer from List 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"
        }]
    }]
}

Received Answer from Reply Button

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"
        }]
    }]
}

Status : Message Sent

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"
        }]
    }]
}

Status: Message Delivered

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"
        }]
    }]
}

Status: Message Read

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"
        }]
    }]
}

Status: Message Deleted

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"
        }]
    }]
}

Status: Message Failed

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"
        }]
    }]
}

Documentation and APIs

WhatsApp

Send Message

Text

Example

Image Message

Image Message BY URL

Image Message BY ID

Document

Document Message BY URL

Document Message BY ID

Audio

Audio Message BY URL

Audio Message BY ID

Video

Video Message BY URL

Video Message BY ID

Supported media types and sizes

Location

List Message

Action Object:

Header Object:

Section Object:

Text-Based Message Template

Button Parameter object

Components Object

Currency Object

Date_Time Object

Parameter Object

Contact

Media

Upload Media

Example

Sample request:

Retrieve Media URL

Example

Sample request:

Delete Media

Example

Sample request:

Sample response:

Download Media

Example

Sample request:

Media message download constraints

Reporting

Analytics

Example

Webhook Payload

Text webhook format

Reaction message webhook format

Media Messages webhook format

Unknown Message

Location Messages Webhook Format

Contact Messages Webhook Format

Received Callback from a Quick Reply Button

Received Answer from List Messages

Received Answer from Reply Button

Status : Message Sent

Status: Message Delivered

Status: Message Read

Status: Message Deleted

Status: Message Failed

Products

Solutions

Usecase

More

Say Hello

Scan to Connect

& Discover

Say Hello

Scan to Connect

& Discover