Skip to content

WHATSAPP

Sending

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

Request parameters

Parameter Data type Description
from string Sender name used when sending message
Only those sender names that are available for use by the user
to string Telephone number in international format.
According to the E.164 standard
text
(optional)
string Message Text
Up to 1000 UTF-8 characters
validity
(optional)
integer It is indicated only in case of sending a message according to the template. Possible meaning - a day.
contentUrl
(optional)
string Content URL
Any valid URL with an http or https scheme
contentName
(optional)
string Content name
Up to 100 characters
contentType
(optional)
string Content MimeType
Existing Mime Type
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.
templateId
(optional)
string The template ID in the provider system
templateParams
(optional)
object A set of parameters to fill the template, where the key is the position number of the value
For example:
languageCode
(optional)
string Language code, by default set 'EN'

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 PDF
office documents
.pdf
.do*
.xl
.ppt
.sx*
.od*
100 Mb
image image/jpeg
image/png
.jpeg
.jpg
*.png
16 Mb GIFs will automatically be converted to MP4 video on the WhatsApp side
video video/mp4
video/3gpp
.mp4
.3gp
*.3g2
5 Mb Only H.264 and AAC video codecs are supported
voice auidio/ogg .ogg 16 Mb Audio recorded on the device.
codecs=opus

Request example

POST /whatsapp/messages
Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
    "messages": [
        {
            "from": "MyCompany",
            "to": "79034567890",
            "text": "Code: 1234"
        }
    ]
}
curl -X POST /whatsapp/messages \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '{ 
    "messages": [ 
        { 
            "from": "MyCompany",
            "to": "79034567890",
            "text": "Code: 1234"
        }
    ]
}' https://api.devino.online/whatsapp/messages
import requests


messages = {
    "messages": [
        {
            "from": "MyCompany",
            "to": "79034567890",
            "text": "Code: 1234"
        }
    ]
}

resp = requests.post(
    'https://api.devino.online/whatsapp/messages',
    json=messages
)
print(resp.json())

Response example

{
    "result": [
        {
            "code": "OK",
            "messageId": "3482512350952730368"
        }
    ]
}
{
    "result": [
        {
            "code": "CODE",
            "reasons": [
                {
                    "key": "string",
                    "ref": "string"
                }
            ],
            "messageId": "string"
        }
    ]
}

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

Getting statuses

To get the status of WHATSAPP messages, you must specify callbackUrl parameter when sending a message using POST/whatsapp /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
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
}