Skip to content

SMS

Sending

To send SMS messages it is required to:

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 true, the system converts URLs in the message into shorter links. If user follows the link, the system will send a callback with the CLICKED status.

For example, if the parameter is enabled, the link https://www.example-url.com/my-example-param... will be converted to https://clickdo.integrationapi.net/link-hash.

False by default.

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
Maximal value: 259200, 3 days
Default value: 0

scheduledTime
(optional)
integer Scheduled message sending time in UTC.
priority
(optional)
priority

Message priority level.

LOW and MEDIUM - low and medium priority levels that are used for promotional messages.
HIGH - high priority that is used for service traffic.
REALTIME - maximum possible priority that is used for transactional traffic.
If any other value is used, the message will be rejected.

callbackUrl
(optional)
string

The URL to which the system will send notifications about message status changes.

Any valid URL with the HTTP or HTTPS scheme.

options
(optional)
object

An object with the data which will be specified in the callback with the message status.

Any "key" array:
{ "key1": "value1", "key2": "value2" }

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. OK - processed successfully.
2. REJECTED - an error has occurred while processing the request.

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"
    }
  ]
}