Skip to content

Direct WA API

Sending

To send WHATSAPP-notifications it is required to call POST /whatsapp/v2/messages sending message parameters in the body with authorization data in the heading.

Request parameters

Attention

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

Response parameters for incoming messages

Parameter Data type Description
from string Sender address
to string Telephone number in international format (without "+")
recipient_type
(optional)
string The type of recipient the message is being sent to.
Supported value: individual.
callbackUrl
(optional)
string URL, which the system will send notifications of changes in the message status.
Any valid URL with an http or https scheme.
callbackData
(optional)
string The data to be specified in the callback with the message status.
preview_url
(optional)
boolean Only used with messages of text type.Allows for URL previews in text messages.
False by default.
type
(optional)
string The type of message you would like to send.
Обязательный параметр для шаблонов сообщений.
Supported values:
-text — default;
-image;
-audio;
-video;
-document;
-contact;
-location;
-template — used to create message templates;
-interactive.
text
(optional)
object Required for messages of text type.
Contains a Text object.
audio
(optional)
object Required when type is set to audio.
The Media object containing audio.
document
(optional)
object Required when type is set to document.
The Media object containing a document.
image
(optional)
object Required when type is set to image.
The Media object containing an image.
video
(optional)
object Required when type is set to video.
The Media object containing a video.
contacts
(optional)
array[object] List of contacts sent by user.
Required when type is set to contacts.
Inside Contact, you can nest the following objects: addresses, emails, name, org, phone и urls.
template
(optional)
object Only used with message templates.
Contains a Template object.
location
(optional)
object Required when type is set to location.
Contains a Location object.
interactive
(optional)
object Required when type is set to interactive.
Contains a Interactive object.

Text

Parameter Data type Description
body string Contains the text of the message, which can contain URLs and formatting.
A text message can be a max of 4096 characters long.

Example text messages:

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

Media

Note

The body of a valid request can only contain one object (audio, document, image, video)

Parameter Data type Description
link string The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.
caption
(optional)
string Name of the media file.
Use with image, or video.
Do not use with audio or document media.
filename
(optional)
string Describes the filename for the specific document.
Use only with document media.
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
document Any valid MIME-type 100 Mb
image image/jpeg
image/png
.jpeg
.jpg
*.png
5 Mb
video video/mp4
video/3gpp
.mp4
.3gp
*.3g2
16 Mb Only H.264 video codec and AAC audio codec is supported.
Only videos with a single audio stream are supported.

Example audio messages:

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

Example document messages:

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

Example video messages:

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

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

Contact

Note

Can accept multiple contacts

Parameter Data type Description
name object Full contact name —see ContactName object.
addresses
(optional)
array[object] Full contact address(es) —see ContactAddress object.
birthday
(optional)
string YYYY-MM-DD formatted string.
emails
(optional)
array[object] Contact email address(es) —see ContactEmail object.
org
(optional)
object Contact organization information —see ContactCompany object.
phones
(optional)
array[object] Contact phone number(s) —see ContactPhone object.
urls
(optional)
array[object] Contact URL(s) —see 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 number and name
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

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 business title

ContactEmail

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

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 URL
type
(optional)
string Standard Values: HOME, WORK

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

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.
Only displayed if name is present.

Example:

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

Template

Parameter Data type Description
name string Name of 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 TemplateComponent object containing the parameters of the message.

TemplateLanguage

Parameter Data type Description
policy string The language policy the message should follow.
Default: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.
Used when type is set to button.
index
(optional)
string Position index of the button. You can have up to 3 buttons using index values of 0-2.
Used when type is set to button.

TemplateComponentParameter

Parameter Data type Description
type string Values: payload,text, currency, date_time, image, document, video.
For the type header, the following values are used:
-text;
-image;
-video;
-document.
For the typebodythe values are used:
-text;
-currency;
-date_time.
For thefooter type, the values are used:
-text.
For the button type, the following values are used:
-text;
-payload.
payload
(optional)
string Developer-defined payload that will be returned when the button is clicked in addition to the display text on the button.
Required for quick_reply buttons.
text
(optional)
string For type header no more than 60 characters with variable support.
For type body no more than 1024 characters with support for emoji and variables.
For type footer no more than 60 characters.
Required for button with sub_type url. For url, a developer-supplied suffix that is appended to the given button URL. No more than 20 characters.
document
(optional)
object The Media object containing a document.
Currently only PDF format is supported.
image
(optional)
object The Media object containing an image.
video
(optional)
object The Media object containing a video.

Note

Variables can be added to the template. Variables allow you to add unique information such as customer name, address, order number, etc. 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.

An example of a 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"
                    }
                ]
            }
        ]
    }
}

An example of a template message with a button containing 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"
                    }
                ]
            }
        ]
    }
}

Interactive

Parameter Data type Description
type string Values:
-list - for messages from the list;
-button - for reply buttons.
header
(optional)
object Header content displayed at the top of the message. See the description of the InteractiveHeader header object.
body object The body of the message. See the description of the InteractiveBody body object.
footer
(optional)
object Message footer. See the description of the InteractiveFooter object.
action object The action to be taken by the user after reading the message. See the description of the InteractiveAction object.

InteractiveHeader

Parameter Data type Description
type string Title type. Values:
-text - for messages from the list and reply buttons;
-video - for reply buttons;
-image - for reply buttons;
-document - for answer buttons.
text
(optional)
string Header text.
Required if the type parameter is set to text.
Maximum length 60 characters with emoji support.
video
(optional)
object Required if the type parameter is set to video. Contains the Media object for this video.
image
(optional)
object Required if the type parameter is set to image. Contains the Media object for this video.
document
(optional)
object Required if the type parameter is set to document. Contains the Media object for this video.

InteractiveBody

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

InteractiveFooter

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

InteractiveAction

Parameter Data type Description
button
(optional)
string Button content.
Required if the type parameter is set to list.
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 if the type parameter is set to button.
Can contain a maximum of 3 objects.
sections
(optional)
array[object] Array of InteractiveActionSection objects.
Required if the type parameter is set to list.
Can contain a maximum of 10 objects.
InteractiveActionButton
Parameter Data type Description
type string Value: reply.
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 of 20 characters.
id string The unique identifier 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 a 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 identifier for the string. The maximum length is 72 characters.

An example of interactive messages from the 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"
                        }
                    ]
                }
            ]
        }
    }
}

Example of interactive messages for response 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"
                    }
                }
            ]
        }
    }
}

Request example

curl -X POST  'https://api.devino.online/whatsapp/v2/messages' \
 -H 'Authorization: Key AAaaAAAaaaaaaAAaAAAaa0AaAA==' \
 -H 'Content-Type: application/json' \
 -H 'X-Api-Key: 00a00aaa-a00a-0000-0000-a000aa00a000'\
 -d '{
     "from": "MySourceAddress",
     "to": "PhoneNumber",
     "type": "template",
     "template": {
         "name": "template_name",
         "language": {
             "code": "ru",
             "policy": "deterministic"
         }
     }
}

Example of a request to send messages

curl -X POST  'https://api.devino.online/whatsapp/v2/messages/batch' \
 -H 'Authorization: Key AAaaAAAaaaaaaAAaAAAaa0AaAA==' \
 -H 'Content-Type: application/json' \
 -H 'X-Api-Key: 00a00aaa-a00a-0000-0000-a000aa00a000'\
 -d '{
    "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"
        }
    ]
}

Response example

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

Response parameters

Parameter Data type Description
code string Points out the result of message processing.
1. OK - Processed successfully
2. REJECTED - An error has occurred while processing the request.
reasons
(optional)
Array[String, String] An array of the errors which 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 occurred.
messageId
(optional)
string Message ID.
To be given with code=OK only
description
(optional)
string Error description.
To be given with code=REJECTED only

Error codes

Key Ref Description
billing.error Payment is required
forbidden Sending is prohibited
unknown Unknown error
invalid messages[i].to Wrong phone number is provided
invalid messages[i].validity Wrong lifetime is provided
invalid messages[i].callbackUrl Wrong URL is provided
invalid messages[i].contentUrl Wrong content URL is provided
invalid messages[i].contentType Wrong content type is provided
invalid messages[i].from Wrong sender is provided
invalid messages[i].languageCode Wrong language code is provided
length.too.long messages[i].to The maximum phone number length has been exceeded
length.too.long messages[i].text The maximum message text length has been exceeded
length.too.long messages[i].languageCode The language code is too long
length.too.short messages[i].contentName Content name too short
length.too.short messages[i].languageCode Language code too short
must.be.not.null messages[i].to No recipient specified
must.be.not.null messages The ‘messages’ array cannot be empty
must.be.not.null messages[i].from No sender specified
must.be.not.null messages[i] Text and content field not specified
not.available messages[i].from Invalid sender address
too.many.messages messages The maximum size of the ‘messages’ array has been exceeded

WhatsApp API error codes

Getting statuses

To get the status of WHATSAPP messages, you must specify callbackUrl parameter when sending a message using POST /whatsapp/v2/messages method.

Response parameters for statuses

Parameter Data type Description
messageId long Message ID
ts long UNIX time
status string Message status
errorCode string Error code
ip string IP address
browser string Browser name
os string Operating system name
userAgent string UserAgent
options string Data that was specified in callbackData in sending request

Response example for getting status

[
    {
        "messageId": 1,
        "ts": 0,
        "status": "DELIVERED",
        "errorCode": 0,
        "ip": "127.0.0.1",
        "browser": "string",
        "os": "string",
        "userAgent": "string",
        "options": "string"
    }
]

Error codes

Code Description
2000 The recipient operator is not defined
2001 Rejected as spam
2002-2004 Billing error
2005 Not enough money
2006-2008 Billing error
2009 Rejected as duplicate
2010, 2011 Expired time of life
2012 Billing error
2017 Rejected as spam
2300 The text message length limit has been exceeded
2301 Too many messages were sent in a short period of time. Retry the sending
2302 Rejected as spam
2303 The specified MIME-Type is not supported or the image is too large (more than or equal to 5MB)
2304 Exceeded the text message length limit
2305 User has not used or is no longer using WhatsApp
2307 Occurs when you try to send a message to the phone number of the business account from which you are sending this message
2308 The number of specified template parameters does not match their expected number
2309, 2310 The template does not exist for the specified language or locale
2311 Exceeding the length of the template parameter
2312 The message was sent out of the dialogue and without specifying a template
2313 Unknown error

Getting incoming messages

Attention

To receive incoming WHATSAPP messages, you must:

  • contact the company manager or contact technical support,
  • tell the URL to send incoming WHATSAPP messages.

Response parameters for incoming messages

Parameter Data type Description
incomingMessageId long Message ID
to string Address of the recipient
from string Sender address
ts long Points out the time for creating message with milliseconds
text
(optional)
string Message text
contentUrl
(optional)
string Content URL in the message
contentType
(optional)
string Content type in the message
contentName
(optional)
string Content name in the message
profileName
(optional)
string Sender profile mame
whatsAppGeoLocation
(optional)
WhatsAppGeolocation Geolocation sent by user
whatsAppContacts
(optional)
List[WhatsAppContact] List of contacts sent by user

WhatsAppGeolocation

Note

Incoming messages with current location data are not currently supported.

Parameter Data type Description
latitude double Latitude
longitude double Longitude
address string Address where the user is located
addressName string User location name
addressurl string URL, where did the user get their location

WhatsAppContact

Note

All elements of Array have a data type of string.

Parameter Data type Description
addresses Array Full contact addresses. Each address can contain the fields street,city, state, zip, country, countryCode and type.
birthday string Contact's birthday in YYYY-MM-DD format.
emails Array Email Addresses. Each address can contain email and type.
contactName Array The full name of the contact. Each contactName object can contain the fields firstName, middleName, lastName, formattedName, namePrefix and nameSuffix.
contactCompany Array Information about the company of the contact. Each object can contain the fields company,department and title.
phones Array Contact phone numbers. Each object can contain the fields phone,waId and type.
urls Array Contact URL. Each object can contain the url andtype fields.

Response example for incoming message

{
    "incomingMessageId": 0,
    "to": "str",
    "from": "str",
    "text": "str",
    "contentUrl": "str",
    "contentType": "str",
    "contentName": "str",
    "profileName": "str",
    "ts": 0
}