Skip to content

SMS

Sending

To send an SMS message it is required to call POST /sms/messages sending message parameters in the body with authorization data in the heading.

Request parameters

Query-params:

Parameter Data type Description
includeSegmentId(optional) boolean If true, then the response for each will also indicate an array of identifiers for each message segment. False by default.

Body:

Parameter Data type Description
messages array[Message] The array of Message objects

Message

Parameter Data type Description
from string The sender’s name. Up to 11 Latin characters or 15 digits
to string Phone number in the international format in accordance with E. 164 standard
text string The message text
validity
(optional)
integer Lifetime of the message in seconds
Minimum value: 1
Maximum value: 259200, 3 days
Default value: 172800, 2 days
priority
(optional)
priority Message priority level.
Between 0 and 3, where:
0 - low priority
3 - highest priority
0 - default priority level
callbackUrl
(optional)
string URL the system will send notifications on the message status changes to. Any valid HTTP or HTTPS URL
options
(optional)
object An object of data external systems need while receiving message statuses
Any “key” array: {“key1”: “value1”,“key2”: “value2” }

Request example

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


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

resp = requests.post(
    'https://api.devino.online/sms/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)
object[string, string] An object of the errors which occurred while processing the message.
To be given with code=REJECTED only.
reasons.key string An 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.
segmentsId
(optional)
array[string] An array of identifiers for each message segment. Up to 255 elements inclusive.
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
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
must.be.not.null messages The ‘messages’ array cannot be empty
invalid messages[i].from Wrong sender is provided
too.many.messages messages The maximum size of the ‘messages’ array has been exceeded

Getting status

While creating the message status a POST request will be sent to the URL provided when sending the message in the callbackUrl parameter. 200 Ok is expected as the answer to the request.

In case the answer to the request is 500 Internal Error, there will be made 5 attempts to deliver the status with 1 minute interval.

Request example

{ 
   "messageId": "string",
   "status": "string",
   "ts": 0,
   "errorCode": 0
}

Request parameters

Parameter Data type Status Description
messageId long any A unique message ID on the platform
ts int any Points out the time for creating the ‘status’ object
status enum any Delivery status code for the Viber message
For more information see Possible statuses
errorCode
(optional)
int rejected
undeliverable
A code for the reason for non-delivery of the message

Possible statuses

Parameter Description
scheduled The message has been scheduled.
enroute The message is in the queue for sending.
sent The message has been sent to the operator network.
delivered The message has been delivered to the user.
expired The lifetime of the message has expired.
undeliverable Unable to deliver the message.
rejected The message has been rejected by the operator or Devino.
deleted The message has been deleted from the queue for sending.
unknown An unknown error has occurred.