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 – Multi Factor Authentication
Authenticate – One Tap Authentication
Engage
WhatsApp
Programmable Voice(India)
Email
Programmable Voice (USA)

WhatsApp

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 Media Reporting Webhook Payload

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 Send Message - Text
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.)		 Send Message - Image Message
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.)		 Send Message - Document
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.)		 Send Message - Audio
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.)		 Send Message - Video
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.		 Send Message - 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. 		Send Message - Video
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.

What’s New