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 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¶

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": "3701172084729885952",
      "segmentsId": [
        "3701172084729885952",
        "3701172084729885953"
      ]
    }
  ]
}

REJECTED

{
  "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¶

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¶

DELIVERED

[
  {
    "messageId": "3597944866766620289",
    "ts": 1613404835977,
    "status": "DELIVERED",
    "errorCode": 0
  }
]

REJECTED

[
  {
    "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

curl -X POST https://api.devino.online/sms-stat/statuses/get-by-ids \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '[ "3482512350952730368" ]'

Python

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