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 (without "+") |
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 | any valid MIME-type | 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¶
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
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 |
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 |
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
}