SMS

Отправка

Для отправки SMS-сообщения необходимо:

• Согласовать имя отправителя в личном кабинете.
• Вызвать POST /sms/messages, передавая параметры сообщения в теле запроса и данные авторизации в заголовке.

Параметры запроса

Параметр	Тип данных	Описание
includeSegmentId (optional)	boolean	Если true, то в ответе также будет указан массив с ID для каждого сегмента SMS-сообщения. По умолчанию false.
shortenUrl (optional)	boolean	При true сокращает длину ссылок в тексте сообщения. Если пользователь перешел по ссылке, система отправляет коллбэк со статусом CLICKED. К примеру, если параметр активен, ссылка https://www.example-url.com/my-example-param... будет преобразована в ссылку вида https://clickdo.integrationapi.net/link-hash. По умолчанию false.

Тело запроса

Параметр	Тип данных	Описание
messages	array[Message]	Массив сообщений. Одновременно можно отправлять до 32 тысяч сообщений.

Message

Параметр	Тип данных	Описание
from	string	Согласованное имя отправителя.
to	string	Номер телефона в международном формате, согласно стандарту E.164.
text	string	Текст сообщения: ○ до 17085 символов включительно при использовании кириллицы. ○ до 34170 символов включительно при использовании латиницы.
validity (optional)	integer	Срок жизни сообщения в секундах. Минимальное значение: 0 Максимальное значение: 259200, 3 суток По умолчанию: 0
scheduledTime (optional)	integer	Запланированное UTC время отправки сообщения.
priority (optional)	string	Приоритет отправки сообщения. LOW и MEDIUM - низкий и средний приоритеты, используются для рекламных сообщений. HIGH - высокий приоритет, используется для сервисного трафика. REALTIME - максимально возможный приоритет, используется для транзакционного трафика. При использовании любого другого значения сообщение будет отклонено.
callbackUrl (optional)	string	URL, на который система будет отправлять уведомления об изменениях статуса сообщения. Любой валидный URL со схемой HTTP или HTTPS.
options (optional)	object	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида "key": { "key1": "value1", "key2": "value2" }

Пример запроса

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

Параметры ответа

Параметр	Тип данных	Описание
code	string	Указывает на результат обработки сообщения. 1. OK - успешно обработано. 2. REJECTED - произошла ошибка во время обработки запроса.
messageId	string	ID сообщения. Указывается только при "code": "OK".
segmentsId	array[string]	Массив ID сегментов сообщения. Указывается только при "code": "OK".
reasons	array	Массив ошибок, произошедших во время обработки сообщения. Указывается только при "code": "REJECTED".
reasons.key	string	Код ошибки.
reasons.ref	string	Ссылка на параметр, в котором произошла ошибка.
reasons.defaultMessage	string	Сообщение с описанием ошибки.

Коды ошибок

Код	Параметр	Описание
not.available	messages[i].from	Неправильно указан отправитель.
to.format.invalid	messages[i].to	Неправильно указан номер телефона получателя.
scheduledTime.is.invalid	messages[i].scheduledTime	Неправильно указано запланированное время отправки сообщения.
text.length.too.long	messages[i].text	Превышена максимальная длина текста сообщения.
validity.is.invalid	messages[i].validity	Неправильно указан срок жизни сообщения.
priority.is.not.match	messages[i].priority	Неправильно указан приоритет отправки сообщения.
callbackUrl.format.invalid	messages[i].callbackUrl	Неправильно указан URL для отправки коллбэков.

Примеры ответов

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

Входящие сообщения

Как подключить

Для получения входящих SMS по HTTP свяжитесь с менеджером компании или обратитесь в техническую поддержку.

Для получения входящих SMS по SMPP необходимо иметь подключение по SMPP.

Параметры

Параметр	Тип данных	Описание
incomingMessageId	string	ID входящего сообщения в Devino.Online.
to	string	Имя или номер получателя.
from	string	Номер телефона отправителя.
text	string	Текст сообщения.
transactionId	string	ID транзакции от оператора.
prefix	string	Ключевое слово (префикс) в начале сообщения.
operator	string	Оператор связи.
countryName	string	Код страны.
ts	long	Время получения сообщения (timestamp) в миллисекундах.

Пример

{
  "incomingMessageId": "3777714415805253122",
  "to": "MyCompany",
  "from": "79101111111",
  "text": "Входящее сообщение",
  "transactionId": "a7d76677f699",
  "prefix": "2135",
  "operator": "MTS",
  "countryName": "ru",
  "ts": "1587721283000"
}

Коллбэки

Как подключить

Для настройки коллбэков со статусами сообщений необходимо обратиться к менеджеру компании или в техническую поддержку.

Возможные статусы

Код	Описание
ACCEPTED	Сообщение было принято.
SCHEDULED	Сообщение запланировано к отправке.
ENROUTE	Сообщение находится в процессе отправки оператору.
SENT	Сообщение было отправлено в сеть оператора.
DELIVERED	Сообщение доставлено абоненту.
EXPIRED	Истек срок жизни сообщения.
CLICKED	Получатель перешел по ссылке в сообщении.
UNDELIVERABLE	Сообщение невозможно доставить.
REJECTED	Сообщение было отклонено оператором или Devino.Online.
UNKNOWN	Произошла неизвестная ошибка.

Примеры коллбэков

DELIVERED

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

REJECTED

[
  {
    "messageId": "3597944866766620289",
    "ts": 1613404835977,
    "status": "REJECTED",
    "errorCode": 2005
  }
]

Запрос статуса

Помимо коллбэков возможно также запрашивать статус сообщений через запрос POST /sms-stat/statuses/get-by-ids, передавая массив ID сообщений. Одновременно можно передать не более 500 значений.

Статусы сообщений будут те же, что и в обычных коллбэках.

Пример запроса

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())

Пример ответа

{
  "result": [
    {
      "smsId": 3701172084729885700,
      "status": "DELIVERED",
      "statusDateTime": "2022-09-09 19:29:34"
    }
  ]
}