WHATSAPP¶

Sending¶

To send WhatsApp messages it is required to:

Agree on sender's name in personal account.
Call POST /whatsapp/messages, sending message parameters in the request body with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
messages	array[Message]	Messages array.

Message¶

Parameter	Data type	Description
from	string	Approved sender’s name.
to	string	Phone number in international format, according to E.164 standard.
text (optional)	string	Message text. Maximum length is 4096 characters.
address (optional)	string	User address.
addressName (optional)	string	The name of the user's address.
addressUrl (optional)	string	The user's address URL.
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" }`
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.
contentName (optional)	string	Content title. Maximum length is 100 characters.
contentType (optional)	MIME Type	Content MIME Type. An existing MIME Type.
contentUrl (optional)	string	Content URL. Any valid URL with `HTTP` or `HTTPS` scheme.
languageCode (optional)	string	Language code. The default is `en`.
latitude (optional)	float	Latitude.
longitude (optional)	float	Longitude.
templateButtonParams (optional)	TemplateButtonParamList	Options for interactive buttons in the message.
templateId (optional)	string	The ID of the template in the provider's system.
templateParams (optional)	object	A set of parameters to fill with a pattern, where the key is the position number of the value. Example: `{ "1": "value1", "2": "value2" }` Attention! In values it is not allowed to use: line breaks, tabs and 4 spaces in a row.
whatsAppContacts (optional)	Contact	Contact information.

Contact¶

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 contact's company.
department (optional)	string	Name of the contact's department.
title (optional)	string	Contact's 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`.

TemplateButtonParamList¶

Attention

The name of the objects in the templateButtonParams array is the name of your button, as specified in the template.

Parameter	Data type	Description
parameters	TemplateButtonParam	Button options.
parameters.payload (optional)	string	The text message that will be sent to the chat when the button is clicked. For `QUICK_REPLY` buttons.
parameters.text (optional)	string	The suffix that is added to the button's URL. For `URL` buttons.
parameters.type	string	One of the parameter types is specified: `PAYLOAD` or `TEXT`, depending on the button type.
subType	string	Button type. Possible values: ○ `QUICK_REPLY` - a button that sends a text message to the chat. ○ `URL` - a button with a link.

MIME Type¶

Media	Supported content type	File extensions	Size restrictions	Comment
`audio`	`audio/acc` `audio/mp4` `audio/amr` `audio/mpeg`	`.acc` `.mp4` `.mp4a` `.amr` `.mpeg`	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 one audio stream or without audio stream are supported.

Request example¶

[ 
  { 
    "from": "MyCompany",
    "to": "79034567890",
    "text": "Code: 1234"
  },
  {
    "from":"MyCompany",
    "to":"79034567888",
    "templateId": "account_activated",
    "templateParams":{
      "1": "+7(495) 646 00 54",
      "2": "https://devino.online"
    },
    "languageCode": "ru",
    "callbackUrl":"https://test_callback_url.site"
  }     
]

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.

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