SMS¶
Sending¶
To send SMS messages it is required to:
- Approve a sender's name in personal account.
- Call POST /sms/messages, sending message parameters in the request body with the authorization data in the header.
Request parameters¶
Parameter | Data type | Description |
---|---|---|
includeSegmentId (optional) |
boolean | If true , then the response will also contain an array with IDs for each SMS message segment. False by default. |
shortenUrl (optional) |
boolean | If For example, if the parameter is enabled, the link
|
Request body¶
Parameter | Data type | Description |
---|---|---|
messages | array[Message] | The array of Message objects. You can send up to 32 thousand messages at the same time. |
Message¶
Parameter | Data type | Description |
---|---|---|
from | string | Approved sender’s name. |
to | string | Phone number in international format, according to E.164 standard. |
text | string | Message text: ○ up to 17085 characters using Cyrillic. ○ up to 34170 characters using Latin. |
validity (optional) |
integer | Lifetime of the message in seconds. Minimal value: 0 |
scheduledTime (optional) |
integer | Scheduled message sending time in UTC. |
priority (optional) |
priority | Message priority level.
|
callbackUrl (optional) |
string | The URL to which the system will send notifications about message status changes. Any valid URL with the |
options (optional) |
object | An object with the data which will be specified in the callback with the message status. Any |
Request example¶
{
"messages": [
{
"from": "sendersName",
"to": "79483547434",
"text": "Hello",
"validity": 0,
"scheduledTime": "2022-09-09T08:52:27.319Z",
"priority": "HIGH",
"callbackUrl": "https://www.callback-url.com/",
"options": {
"key1": "value1",
"key2": "value2"
}
}
]
}
Response parameters¶
Parameter | Data type | Description |
---|---|---|
code | string | Shows the result of message processing. 1. |
messageId | string | Message ID. To be given with "code": "OK" only. |
segmentsId | array[string] | An array with IDs for each SMS message segment. |
reasons | array | An array of the errors that occurred while processing the message. To be given with "code": "REJECTED" only. |
reasons.key | string | Error code. |
reasons.ref | string | Reference to the parameter where the error has occurred. |
reasons.defaultMessage | string | Message with error description. |
Error codes¶
Key | Ref | Description |
---|---|---|
not.available | messages[i].from | Wrong sender is provided. |
to.format.invalid | messages[i].to | Wrong recipient's phone number is provided. |
scheduledTime.is.invalid | messages[i].scheduledTime | Wrong scheduled time for sending message is provided. |
text.length.too.long | messages[i].text | The maximum message text length has been exceeded. |
validity.is.invalid | messages[i].validity | Wrong message lifetime is provided. |
priority.is.not.match | messages[i].priority | Wrong priority for message sending is provided. |
callbackUrl.format.invalid | messages[i].callbackUrl | Wrong URL for callbacks sending is provided. |
Response examples¶
{
"result": [
{
"code": "OK",
"messageId": "3701172084729885952",
"segmentsId": [
"3701172084729885952",
"3701172084729885953"
]
}
]
}
{
"result": [
{
"code": "REJECTED",
"messageId": null,
"segmentsId": null,
"reasons": [
{
"key": "to.format.invalid",
"ref": "to",
"defaultMessage": "Error: Invalid field value. Value: string"
}
]
}
]
}
Incoming messages¶
How to enable
To enable incoming SMS messages over HTTP, you need to contact the account manager or technical support.
To enable incoming SMS over SMPP, you need to have the SMPP connection.
Parameters¶
Parameter | Data type | Description |
---|---|---|
incomingMessageId | long | Incoming message ID in the Devino.Online. |
to | string | Recipient's name or number. |
from | string | Sender's phone number. |
text | string | Message text. |
transactionId | string | Transaction ID from the operator. |
prefix | string | Key word (prefix) at the beginning of the message. |
operator | string | Telecom operator. |
countryName | string | Country code. |
ts | long | Time of the receipt of the message (timestamp) in milliseconds. |
Example¶
{
"incomingMessageId": "3777714415805253122",
"to": "MyCompany",
"from": "79101111111",
"text": "Incoming Message",
"transactionId": "a7d76677f699",
"prefix": "2135",
"operator": "MTS",
"countryName": "ru",
"ts": "1587721283000"
}
Callbacks¶
How to enable
To set up callbacks with message statuses, please contact your account manager or technical support.
Possible statuses¶
| SCHEDULED | Сообщение запланировано к отправке. | | ENROUTE | Сообщение находится в процессе отправки оператору. |
Code | Description |
---|---|
ACCEPTED | The message has been accepted. |
SCHEDULED | The message is scheduled to be sent. |
ENROUTE | The message is in the process of being sent to the operator. |
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. |
CLICKED | The recipient has followed the link in the message. |
UNDELIVERABLE | Unable to deliver the message. |
REJECTED | The message has been rejected by the operator or Devino.Online. |
UNKNOWN | An unknown error has occurred. |
Callback examples¶
[
{
"messageId": "3597944866766620289",
"ts": 1613404835977,
"status": "DELIVERED",
"errorCode": 0
}
]
[
{
"messageId": "3597944866766620289",
"ts": 1613404835977,
"status": "REJECTED",
"errorCode": 2005
}
]
Getting statuses¶
In addition to callbacks it is also possible to request the status of messages using POST /sms-stat/statuses/get-by-ids, passing an array of the message IDs. You can send no more than 500 values at the same time.
Statuses of the messages will be the same as in regular callbacks.
Request example¶
curl -X POST https://api.devino.online/sms-stat/statuses/get-by-ids \
-H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-H 'Content-Type: application/json' \
-d '[ "3482512350952730368" ]'
import requests
message_ids = [ "3482512350952730368" ]
resp = requests.post(
'https://api.devino.online/sms-stat/statuses/get-by-ids',
json=message_ids
)
print(resp.json())
Response example¶
{
"result": [
{
"smsId": 3701172084729885700,
"status": "DELIVERED",
"statusDateTime": "2022-09-09 19:29:34"
}
]
}