Direct WA API¶

Sending¶

To send WhatsApp messages it is required to:

Agree on sender's name in personal account.
Call requests, sending message parameters in the request body with the authorization data in the header:
- POST /whatsapp/v2/messages for single message.
- POST /whatsapp/v2/messages/batch for multiple messages.

Request parameters¶

Attention

The following types of messages are supported: text, images, documents, audio, video, message templates, location, contacts, interactive messages.

Parameter	Data type	Description
from	string	Approved sender’s name.
to	string	Phone number in international format, according to E.164 standard.
recipient_type (optional)	string	The type of recipient the message is being sent to. Supported value: `individual`.
callbackUrl (optional)	string	The URL to which the system will send notifications about message status changes. Any valid URL with the `HTTP` or `HTTPS` scheme.
callbackData (optional)	object	An object with the data which will be specified in the callback with the message status. Any `"key"` array: `{ "key1": "value1", "key2": "value2" }`
preview_url (optional)	boolean	URL previews in the text messages. `False` by default.
type (optional)	string	Message type. Possible values: ○ `audio` - for messages with audio. ○ `sticker` - for messages with a sticker. ○ `contacts` - for messages with contacts. ○ `document` - for messages with documents. ○ `image` - for messages with images. ○ `interactive` - for messages with buttons. ○ `location` - for messages with geolocation. ○ `template` - for template messages. ○ `text` - for text messages, default value.
text (optional)	Text	Required for `text` message type. Contains a Text object.
audio (optional)	Media	Required for `audio` message type. A Media object contains audio.
document (optional)	Media	Required for `document` message type. A Media object contains a document.
image (optional)	Media	Required for `image` message type. A Media object contains an image.
video (optional)	Media	Required for `video` message type. A Media object contains a video.
sticker (optional)	Media	Required for `sticker` message type. A Media object contains a sticker.
contacts (optional)	array[object]	List of contacts sent by user. Required for`contacts` message type. Contact can contain the following objects: `addresses`, `emails`, `name`, `org`, `phone` и `urls`.
template (optional)	Template	Used only for template messages. Contains a Template object.
location (optional)	Location	Required for `location` message type. Contains a Location object.
interactive (optional)	Interactive	Required for `interactive` message type. Contains an Interactive object.

Request examples¶

Single message

{
  "from": "MySourceAddress",
  "to": "PhoneNumber",
  "type": "template",
  "template": {
    "name": "template_name",
    "language": {
      "code": "en",
      "policy": "deterministic"
      }
  }
}

Multiple messages

{
  "messages": [
    {
      "from": "MySourceAddress",
      "to": "PhoneNumber",
      "text": "your_message_content",
      "callbackUrl": "http://the_url"
    },
    {
      "from": "MySourceAddress",
      "to": "PhoneNumber",
      "text": "your_message_content",
      "callbackUrl": "http://the_url"
    }
  ]
}

Text¶

Parameter	Data type	Description
body	string	Contains the text of the message. Can contain a few URLs and formatting. The maximum length of a text message is 4 096 characters.

Message example¶

{
  "from": "MySourceAddress",
  "to": "PhoneNumber",
  "type": "text",
  "text": {
      "body": "your_message_content"
  }
}

Media¶

Note

The body of a valid request can contain only one Media object.

Parameter	Data type	Description
link	string	The protocol and URL of the media being sent. Used only for URLs with `HTTP` or `HTTPS` prefix. Cannot be used with message type `text`.
id	string	ID of the media file. Required if you do not use the `link` option.
caption (optional)	string	Name of the media file. Used for media files of type `image` or `video`. Cannot be used for `audio`, `sticker` and `document` files.
filename (optional)	string	Filename corresponding to the selected document. Can be used only for `document` type media files. Length from 1 to 100.

MIMEType¶

Media	Supported content type	File extensions	Size restrictions	Comment
`audio`	`audio/acc` `audio/mp4` `audio/amr` `audio/mpeg` `audio/ogg`	`.acc` `.mp4` `.mp4a` `.amr` `.mpeg` `.ogg`	16Mb	`codecs=opus`
`voice`	`audio/ogg`	`.ogg`	16 Mb	Audio recorded on the device. `codecs=opus`
`document`	any valid MIME Type		100 Mb
`image`	`image/jpeg` `image/png`	`.jpeg` `.jpg` `.png`	5 Mb	GIFs will be automatically converted to MP4 videos by WhatsApp. Images with a transparent background are not supported.
`video`	`video/mp4` `video/3gpp`	`.mp4` `.3gp` `.3g2`	16 Mb	Only H.264 video codec and AAC audio codec are supported. Only videos with or without one audio stream are supported.

Message examples¶

Audio messages

{
  "from": "MySourceAddress",
  "to": "PhoneNumber",
  "type": "audio",
  "audio": {
      "link": "http(s)://the_url"
  }
}

Video messages

{
  "from": "MySourceAddress",
  "to": "PhoneNumber",
  "type": "video",

  "video": {
      "link": "http(s)://the_url",
      "caption": "your_video-name"
  }
}

Document messages

{
  "from": "MySourceAddress",
  "to": "PhoneNumber",
  "type": "document",
  "document": {
      "link": "http(s)://the_url",
      "filename": "your_document_filename"
  }
}

Contact¶

Info

Can accept multiple contacts.

Parameter	Data type	Description
name	object	Full contact name (ContactName object).
addresses (optional)	array[object]	Full contact addresses (ContactAddress object).
birthday (optional)	string	`YYYY-MM-DD` formatted string.
emails (optional)	array[object]	Contact email addresses (ContactEmail object).
org (optional)	object	Contact organization information (ContactCompany object).
phones (optional)	array[object]	Contact phone number (ContactPhone object).
urls (optional)	array[object]	Contact URL (ContactUrl object).

ContactName¶

Note

At least one of the optional parameters needs to be included along with the formatted_name parameter.

Parameter	Data type	Description
formatted_name	string	Full name, as it normally appears.
first_name (optional)	string	First name.
last_name (optional)	string	Last name.
middle_name (optional)	string	Middle name.
suffix (optional)	string	Name suffix.
prefix (optional)	string	Name prefix.

ContactAddress¶

Parameter	Data type	Description
street (optional)	string	Street name and house number.
city (optional)	string	City name.
state (optional)	string	State abbreviation.
zip (optional)	string	ZIP code.
country (optional)	string	Full country name.
country_code (optional)	string	Two-letter country abbreviation.
type (optional)	string	Standard values: `HOME`, `WORK`.

ContactEmail¶

Parameter	Data type	Description
email (optional)	string	Email address.
type (optional)	string	Standard values: `HOME`, `WORK`.

ContactCompany¶

Parameter	Data type	Description
company (optional)	string	Name of the company.
department (optional)	string	Name of the department.
title (optional)	string	Job title.

ContactPhone¶

Parameter	Data type	Description
phone (optional)	string	Automatically populated with the `wa_id` value as a formatted phone number.
type (optional)	string	Standard Values:`CELL`, `MAIN`, `IPHONE`, `HOME`, `WORK`.
wa_id (optional)	string	WhatsApp ID.

ContactUrl¶

Parameter	Data type	Description
url (optional)	string	Contact URL.
type (optional)	string	Standard values: `HOME`, `WORK`.

Message example¶

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "contacts",
    "contacts": [
        {
            "name": {
                "formatted_name": "formatted_name 1",
                "first_name": "contact_first_name",
                "last_name": "contact_last_name"
            },
            "emails": [
                {
                    "email": "email@example.com",
                    "type": "WORK"
                }
            ]
        },
        {
            "name": {
                "formatted_name": "formatted_name 2",
                "first_name": "contact_first_name",
                "last_name": "contact_last_name"
            },
            "phones": [
                {
                    "phone": "+74956460054",
                    "type": "WORK"
                }                
            ]
        }
    ]
}

Template¶

Parameter	Data type	Description
name	string	Name of the template.
namespace	string	The namespace for the template.
language	object	TemplateLanguage object specifies the language the template may be rendered in. Only the `deterministic` language policy works with media template messages.
components (optional)	array[object]	Array of the TemplateComponent objects containing the parameters of the message.

TemplateLanguage¶

Parameter	Data type	Description
policy	string	The language policy the message should follow. Default value: `deterministic`.
code (optional)	string	The code of the language or locale to use. Accepts both `language` and `language_locale` formats (e.g., `en` and `en_US`).

TemplateComponent¶

Parameter	Data type	Description
type	string	Describes the `component` type. Values: `header`, `body`, `footer`, `button`.
parameters (optional)	array[object]	Array TemplateComponentParameter object containing the content of the message.
sub_type (optional)	string	Type of button being created. Values: `quick_reply`, `url`. Required for `button` type.
index (optional)	string	Position index of the button. You can create up to 3 buttons using index values of `0-2`. Required for `button` type.

TemplateComponentParameter¶

Parameter	Data type	Description
type	string	Values for the type: ○ `header`: `text`, `image`, `video`, `document`. ○ `body`: `text`, `currency`, `date_time`. ○ `footer`: `text`. ○ `button`: `text`, `payload`.
payload (optional)	string	Developer-defined payload that will be returned when the button with the text is clicked. Required for `quick_reply` buttons.
text (optional)	string	For `header` no more than 60 characters with variable support. For `body` no more than 1024 characters with emoji and variables support. For `footer` no more than 60 characters. For `button` with `"sub_type": "url"` a developer-supplied suffix is required. This suffix is appended to the given button URL. No more than 20 characters.
document (optional)	object	A Media object containing a document.
image (optional)	object	A Media object containing an image.
video (optional)	object	A Media object containing a video.
currency (optional)	object	A Currency object containing currency information.

Currency¶

Parameter	Data type	Description
fallback_value	string	The text that is displayed in case of a message localization error.
amount_1000 (optional)	integer	The amount of currency multiplied by 1000.
code (optional)	string	Currency code according to ISO 4217.

Info

Variables can be added to the template. Variables allow you to add unique information such as, for example, a customer's name, address, order number, etc. The numbering of variables starts from one and continues in ascending order.

Your order {{1}} for a total of {{2}} has been confirmed.

Where {{1}} and {{2}} are variables: 119833 and 2900.

Your order 119833 for a total of 2900 has been confirmed.

Message examples¶

With button

The button contains a link with a variable part:

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "template",
    "template": {
        "name": "template_name",
        "language": {
            "policy": "deterministic",
            "code": "ru"
        },
        "components": [
            {
                "type": "button",
                "sub_type": "url",
                "index": "0",
                "parameters": [
                    {
                        "type": "text",
                        "text": "/start"
                    }
                ]
            }
        ]
    }
}

With currency

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "template",
    "template": {
        "name": "template_name",
        "language": {
            "policy": "deterministic",
            "code": "ru"
        },
        "components": [
            {
                "type": "currency",
                "currency" : {
                    "fallback_value": "$230.99",
                    "code": "USD",
                    "amount_1000": 230990
                }
            }
        ]
    }
}

With media

The template message with documents in the header, variables in the body, text in the footer and two buttons:

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "template",
    "template": {
        "name": "template_name",
        "language": {
            "code": "ru",
            "policy": "deterministic"
        },
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "document",
                        "document": {
                            "link": "http(s)://the_url",
                            "filename": "document_name"
                        }
                    }
                ]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "119833"
                    },
                    {
                        "type": "text",
                        "text": "2900"
                    },
                    {
                        "type": "currency",
                        "currency": {
                            "fallback_value": "$100.99",
                            "code": "USD",
                            "amount_1000": 100990
                        }
                    },
                    {
                        "type": "date_time",
                        "date_time": {
                            "fallback_value": "February 25, 1977",
                            "day_of_week": 5,
                            "day_of_month": 25,
                            "year": 1977,
                            "month": 2,
                            "hour": 15,
                            "minute": 33, //#OR
                            "timestamp": 1485470276
                        }
                    }
                ]
            },
            {
                "type": "footer",
                "parameters": [
                    {
                        "type": "text",
                        "text": "text 1"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 0,
                "parameters": [
                    {
                        "type": "payload",
                        "payload": "Start"
                    }
                ]
            },
            {
                "type": "button",
                "sub_type": "quick_reply",
                "index": 1,
                "parameters": [
                    {
                        "type": "payload",
                        "payload": "End"
                    }
                ]
            }
        ]
    }
}

Location¶

Parameter	Data type	Description
longitude	double	Longitude of the location. Minimum value: -180 Maximum value: 180
latitude	double	Latitude of the location. Minimum value: -90 Maximum value: 90
name (optional)	string	Name of the location.
address (optional)	string	Address of the location. Displayed only if the `name` is specified.

Message example¶

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "location",
    "location": {
        "latitude": 74.1182263536133,
        "longitude": 69.9107435105422,
        "address": "location_address",
        "name": "location_name"
    }
}

Interactive¶

Parameter	Data type	Description
type	string	Values: ○ `list` - for list messages. ○ `button` - for reply buttons.
header (optional)	object	Header content displayed at the top of the message (InteractiveHeader object).
body	object	The body of the message (InteractiveBody object).
footer (optional)	object	Message footer (InteractiveFooter object).
action	object	The action the user should perform after reading the message (InteractiveAction object).

InteractiveHeader¶

Parameter	Data type	Description
type	string	Title type. Values: ○ `text` - for list messages and reply buttons. ○ `video`, `image`, `document` - for reply buttons.
text (optional)	string	Header text. Required if `"type": "text"`. Maximum length is 60 characters with emoji support.
video (optional)	object	Required for the `video` type. Contains the Media object.
image (optional)	object	Required for the `image` type. Contains the Media object.
document (optional)	object	Required for the `document` type. Contains the Media object.

InteractiveBody¶

Parameter	Data type	Description
text	string	Message text. Emoji, variables and links are supported. Maximum length is 1024 characters.

InteractiveFooter¶

Parameter	Data type	Description
text	string	Footer content. Emoji, variables, and links are supported. Maximum length is 60 characters.

InteractiveAction¶

Parameter	Data type	Description
button (optional)	string	Button content. Required for the `list` type. This value cannot be an empty string and must be unique in the message. Emoji and variables are not supported. The maximum length is 20 characters.
buttons (optional)	array[object]	Array of InteractiveActionButton objects. Required for the `button` type. Can contain a maximum of 3 objects.
sections (optional)	array[object]	Array of InteractiveActionSection objects. Required for the `list` type. Can contain a maximum of 10 objects.

InteractiveActionButton¶

Parameter	Data type	Description
type	string	Value: `reply`.
reply	object	The `reply` object contains: ○ `title` (string) button name. This value cannot be an empty string and must be unique in the message. Emoji and variables are not supported. Maximum length is 20 characters. ○ `id` (string) - the unique ID for the button. This ID is returned in the Webhook when the user clicks the button. The maximum length is 256 characters.

InteractiveActionSection¶

Parameter	Data type	Description
title (optional)	string	Section heading. Required if the message contains more than one `section` object. The maximum length is 24 characters.
rows (optional)	array[object]	Contains the list of InteractiveActionSectionRow strings. Required if the `type` parameter is set to `list`.

InteractiveActionSectionRow¶

Parameter	Data type	Description
title	string	Section title. The maximum length is 24 characters.
id	string	ID. The maximum length is 200 characters.
description (optional)	string	Unique ID for the string. The maximum length is 72 characters.

Message examples¶

List

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "interactive",
    "interactive": {
        "type": "list",
        "header": {
            "type": "text",
            "text": "your_header_content"
        },
        "body": {
            "text": "your_text_message_content"
        },
        "footer": {
            "text": "your_footer_content"
        },
        "action": {
            "button": "button_content",
            "sections": [
                {
                    "title": "your_section_title_content",
                    "rows": [
                        {
                            "id": "unique_row_identifier",
                            "title": "row_title_content",
                            "description": "row_description_content"
                        }
                    ]
                },
                {
                    "title": "your_section_title_content",
                    "rows": [
                        {
                            "id": "unique_row_identifier",
                            "title": "row_title_content",
                            "description": "row_description_content"
                        }
                    ]
                }
            ]
        }
    }
}

Reply buttons

{
    "from": "MySourceAddress",
    "to": "PhoneNumber",
    "type": "interactive",
    "interactive": {
        "type": "button",
        "body": {
            "text": "your_text_body_content"
        },
        "action": {
            "buttons": [
                {
                    "type": "reply",
                    "reply": {
                        "id": "unique_postback_id",
                        "title": "First Button’s Title"
                    }
                },
                {
                    "type": "reply",
                    "reply": {
                        "id": "unique_postback_id",
                        "title": "Second Button’s Title"
                    }
                }
            ]
        }
    }
}

Response parameters¶

Parameter	Data type	Description
code	string	Shows the result of message processing. 1. `OK` - processed successfully. 2. `REJECTED` - an error has occurred while processing the request.
messageId (optional)	string	Message ID. To be given with `"code": "OK"` only.
reasons (optional)	array[string, string]	An array of the errors that occurred while processing the message. To be given with `"code": "REJECTED"` only.
reasons.key	string	Error code.
reasons.ref (optional)	string	A reference to the parameter where the error has occurred.

Error codes¶

Key	Ref	Description
invalid	messages[i].to	The phone number is incorrect.
invalid	messages[i].callbackUrl	The URL is not in the `HTTP` or `HTTPS` format.
invalid	messages[i].templateButtonParams	The `text` parameter cannot be empty.
invalid	messages[i].templateButtonParams	The `payload` parameter cannot be empty.
invalid	messages[i].languageCode	The language code is incorrect.
not supported	messages[i].media.filename	The file name is not supported for this media type.
unsupported	messages[i].sticker.caption	Sticker description is not supported.
must.be.not.null	messages[i].audio	For the message type `audio`, the `audio` object cannot be empty.
must.be.not.null	messages[i].contacts	For the message type `contacts`, the `contacts` object cannot be empty.
must.be.not.null	messages[i].document	For the message type `document`, the `document` object cannot be empty.
must.be.not.null	messages[i].template	For a `template` message type, the `template` object cannot be empty.
must.be.not.null	messages[i].image	For message type `image`, the `image` object cannot be empty.
must.be.not.null	messages[i].location	For the message type `location`, the `location` object cannot be empty.
must.be.not.null	messages[i].text	For message type `text`, the `text` object cannot be empty.
must.be.not.null	messages[i].video	For the message type `video`, the `video` object cannot be empty.
must.be.not.null	messages[i].sticker	For the message type `sticker`, the `sticker` object cannot be empty.

Response examples¶

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": "3482512350952730368"
    }    
  ]
}

REJECTED

{
  "result": {
    "code":"REJECTED",
    "messageId":null,
    "reasons": [
      {
        "key":"invalid.to",
        "ref":"to"
      }
    ]
  }
}

Incoming messages¶

How to enable

To enable incoming messages from users, contact your account manager or technical support. You will also need to provide the URL of a web-server for processing incoming messages.

Parameters¶

Parameter	Data type	Description
incomingMessageId	integer	Incoming message ID.
to	string	The receiver's profile name.
from	string	The sender's phone number.
text	string	Message text.
profileName	string	The sender's profile name.
ts	integer	The time the message was received (timestamp) in milliseconds.

Example¶

{
    "incomingMessageId": 2834738753045023457,
    "to": "BusinessProfile",
    "from": "799900000000",
    "text": "Hello!",
    "profileName": "UserName", 
    "ts": 1670844823000
}

Callbacks¶

How to enable

To set up callbacks with message statuses, please contact your account manager or technical support.

Possible statuses¶

Code	Description
SENT	The message has been sent.
EXPIRED	The lifetime of the message has expired.
DELIVERED	The message has been delivered to the user.
SEEN	The message has been read by the user.
REJECTED	The message has been rejected by the operator or the message sending limit has been exceeded.
UNDELIVERABLE	The message has been rejected by the operator or the message template is missing.

Callback example¶

[
    {
        "messageId": 1,
        "ts": 1636976602504,
        "status": "DELIVERED",
        "errorCode": 0,
        "callbackData": "string"
    }
]