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

Details¶

To get the sent messages detailed information, you need to call GET /sms-stat/detail, sending filter parameters with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
limit	integer	The number of messages in the search results.
offset	integer	Search results offset. For example, if the number `5` is specified in the parameter, the received array of messages will be displayed only from the 5 in the pull.
taskId (optional)	integer	Message campaign ID for which you want to get the details. Used in required combination with the other parameters.
triggerId (optional)	integer	Message campaign trigger ID. Used in required combination with the other parameters.
dateTimeFrom (optional)	datetime	Start date of the message search. Used in required combination with the other parameters. The format is `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo (optional)	datetime	End date of the message search. Used in required combination with the other parameters. The format is `YYYY-MM-DD+hh:mm:ss`.
messageIds (optional)	array[integer]	Message IDs for which you want to get the details. Used in required combination with the other parameters.
bySegments (optional)	boolean	If `true`, then each message will be divided into segments (if there is more than 1 segment). Each segment will have its own ID (the `SEGMENT_ID` field). If `false`, then each message will be displayed as it is, with the number of segments (the `SEGMENTS_COUNT` field).
calculateTotalCount (optional)	boolean	If `true`, the response will contain the total number of messages and pages matching the request parameters (`total` and `pages` parameters).
countryId (optional)	integer	Country ID.
mogId (optional)	integer	Mobile operator group ID.
order (optional)	string	How to display the request results. Possible values: ○ `ASC` - in ascending order. ○ `DESC` - in descending order.
orderField (optional)	string	Field by which to sort the request results.
outFields (optional)	array[string]	Fields to be shown in request results. Fields that are not specified in this parameter will be excluded.
recipient (optional)	string	Recipient's phone number.
searchText (optional)	string	Retrieve messages containing this keyword.
sourceAddress (optional)	string	Approved sender's name.
status (optional)	string	The messages status in the request results. Possible values: ○ `DELIVERED` - the message has been delivered to the user. ○ `IN_PROGRESS` - the message is in the process of being sent to the operator. ○ `REDIRECT` - the recipient has followed the link in the message. ○ `REJECTED` - the message has been rejected by the operator or Devino.Online. ○ `UNDELIVERED` - unable to deliver the message.
timeOffset (optional)	integer	Recipient's time zone.
userId (optional)	integer	Campaign sender user ID.

Parameters combinations¶

To get the correct request results, you should use one of these parameters combinations in accordance with the list:

Message campaign ID: taskId
Message campaign ID and trigger ID: taskId, triggerId
Start and end dates for the message search: dateTimeFrom, dateTimeTo
Message campaign ID, trigger ID; start and end dates for the message search: taskId, triggerId, dateTimeFrom, dateTimeTo
Message IDs: messageIds

Fields for `orderField` and `outFields` parameters¶

Used in the orderField parameter to sort the search results and in the outFields parameter to filter fields.

Field name	Description
COMPANY_ID	Company ID.
COMPANY_NAME	Company name.
CONTACT_ID	Recipient ID from the contact list.
COUNTRY_ID	Country ID.
COUNTRY_NAME	Country name.
ERROR_CODE	Error code.
EVENT_DATE_TIME	Date and time the status of the message was last updated.
MESSAGE_ID	Message ID.
MOG_ID	Mobile operator group ID.
MOG_NAME	Mobile operator group name.
MO_ID	Mobile operator ID.
MO_NAME	Mobile operator name.
PRICE	Message segment price.
PROVIDER_MESSAGE_ID	Operator's message ID.
RECIPIENT	Recipient's phone number.
RECIPIENT_ZONE_NAME	Recipient's time zone.
ROUTE	Route through which the message was sent (for example: `SMSGW101`).
SEGMENT_COUNT	The number of message segments.
SEGMENT_ID	Segment ID.
SENT_DATE_TIME	Date and time the message was sent.
SOURCE_ADDRESS	Sender's name.
STATUS	Message status.
TASK_ID	Campaign ID.
TASK_NAME	Campaign name.
TASK_TYPE	Campaign type.
TEMPLATE	Message template name.
TEMPLATE_ID	Message template ID.
TEXT	Message text.
TRAFFIC	Traffic type. Possible values: ○ `ADVERTISING` - advertising traffic. ○ `AUTHORIZATION` - authorization traffic. ○ `INCOMING` - incoming traffic. ○ `SERVICE` - service traffic. ○ `TRANSACTIONAL` - transactional traffic.
TRIGGER_CONTACT_GROUP	The name of the contact list to which the campaign was sent.
IS_CONTACT_GROUP_DELETED	Whether the contact list, the contact from which the message was sent, has been deleted.
TRIGGER_ID	Campaign trigger ID.
USER_ID	Sender's user ID.
USER_LOGIN	Sender's user login.

Request examples¶

With dates

curl -X GET https://api.devino.online/sms-stat/detail?calculateTotalCount=true&dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-02-24+00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

With task ID and trigger ID

curl -X GET https://api.devino.online/sms-stat/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

Parameter	Data type	Description
data	array[object]	An array of objects with detailed information on each message. The parameters are defined by the fields that were set in the original request.
size	integer	Number of items per page and messages in search results. Set by `limit` parameter.
offset	integer	Search results offset. For example, if the number `5` is specified in the parameter, the received array of messages will be displayed only from the 5 in the pull.
number	integer	The number of the received page. Defined by the `offset` parameter. ○ If the `offset` parameter value is `0` with any `limit` parameter value, then the page number will be `1`. ○ If the `offset` will be greater than `0` but less than the `limit` parameter value, the page number will be `2`. For example, with `"offset": 5` and `"limit": 10` the `number` parameter value will be `2`. ○ If the `offset` will be greater than `limit`, the page number will be determined by integer division of `offset` by `limit` plus 1 (`offset` / `limit` + 1). For example, with `"offset": 1000` and `"limit": 50`, the `number` parameter value will be `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Whether the displayed page exists.
total	integer	The total number of messages for which the details can be received.
pages	integer	The total number of pages for which the details can be received. Determined by integer division of the `total` parameter by `limit` (`total` / `limit`).
more	boolean	Indicator: whether there are pages after the current one specified in the `number` parameter.

Response example¶

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "sentDateTime": "2022-12-14 05:55:32",
        "segmentId": "234567865432456787634",
        "sourceAddress": "sendersName",
        "recipient": "79001112233",
        "status": "DELIVERED",
        "eventDateTime": "2022-12-14 05:54:52",
        "companyId": 234,
        "companyName": "MyCompany",
        "userId": 88,
        "userLogin": "79991112233",
        "countryId": 12,
        "countryName": "Russia",
        "mogId": 0,
        "mogName": "MOG",
        "moId": 234,
        "moName": "Operator Name",
        "taskId": 88888888,
        "taskName": "SimpleCampaign",
        "taskType": "SIMPLE",
        "triggerId": 2345678,
        "text": "Hello",
        "errorCode": 0,
        "traffic": "ADVERTISING",
        "recipientZoneName": "UTC +03:00",
        "triggerContactGroup": "contactGroup",
        "isContactGroupDeleted": "No"
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Message statistics¶

To get the general statistics on message statuses, you need to call GET /sms-stat/statistics/of-group, sending filter parameters with the authorization data in the header.

Request parameters¶

Parameter	Data type	Description
groupBy	string	Results grouping: ○ `NONE` - no grouping ○ `YEAR` - by year ○ `MONTH` - by month ○ `WEEK` - by week ○ `DAY` - by day ○ `HOUR` - by hour
startDate	datetime	Start of the date range. The format is `YYYY-MM-DDThh%3Amm%3Ass`.
endDate	datetime	End of the date range. The format is `YYYY-MM-DDThh%3Amm%3Ass`.
taskId (optional)	integer	Campaign ID for which the statistics is needed.
triggerId (optional)	integer	Campaign trigger ID for which the statistics is needed.
timeOffset (optional)	integer	Recipient's time zone. The format is offset in minutes, for example, `180` for Moscow (GMT+3).

Request example¶

curl -X GET https://api.devino.online/sms-stat/statistics/of-group?startDate=2022-10-06+13:45:30&endDate=2023-02-06+13:45:30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters¶

Parameter	Data type	Description
messages	array[MessageStatusObject]	The number of messages for the selected period, grouped by status.
segments	array[MessageStatusObject]	The number of message segments for the selected period, grouped by status.

MessageStatusObject¶

The object contains information about the number of messages with statuses:

Code	Description
accepted	The message has been accepted.
scheduled	The message is scheduled to be sent.
enrouted	The message is in the process of being sent to the operator.
sent	The message has been sent to the operator network.
deleted	The message has been deleted.
delivered	The message has been delivered to the user.
expired	The lifetime of the message has expired.
seen	The message has been read by the user.
clicked	The recipient has followed the link in the message.
rejected	The message has been rejected by the operator or Devino.Online.
undeliverable	Unable to deliver the message.
unknown	An unknown error has occurred.

Each status includes the parameters:

Parameter	Data type	Description
date	string	Statistics collection date depending on the value of the `groupBy` parameter.
amount	integer	The number of messages.

Response example¶

{
  "result": {
    "messages": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 100
        }
      ],
      "sent": [
        {
          "date": "2022-12-01 00:00:00",
          "amount": 2
        }
      ],
      "deleted": [],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 67
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 1
        },
        {
          "date": "2022-12-01 00:00:00",
          "amount": 72
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 3
        }
      ],
      "enrouted": [],
      "expired": [],
      "seen": [],
      "clicked": [],
      "rejected": [],
      "scheduled": [],
      "undeliverable": [],
      "unknown": []
    },
    "segments": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 4
        }
      ]
      ...
    }
  }
}

SMS¶

Sending¶

Request parameters¶

Request body¶

Message¶

Request example¶

Response parameters¶

Error codes¶

Response examples¶

Incoming messages¶

Parameters¶

Example¶

Callbacks¶

Possible statuses¶

Callback examples¶

Getting statuses¶

Request example¶

Response example¶

Details¶

Request parameters¶

Parameters combinations¶

Fields for orderField and outFields parameters¶

Request examples¶

Response parameters¶

Response example¶

Message statistics¶

Request parameters¶

Request example¶

Response parameters¶

MessageStatusObject¶

Response example¶

Fields for `orderField` and `outFields` parameters¶