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 \
-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
}