SMS¶

Отправка¶

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

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

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

Параметр	Тип данных	Описание
includeSegmentId (optional)	boolean	Если `true`, то в ответе также будет указан массив с ID для каждого сегмента SMS-сообщения. По умолчанию `false`.
shortenUrl (optional)	boolean	Флаг, который сокращает длину ссылки: если `true`, то ссылка будет сокращена. По умолчанию `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	Произошла неизвестная ошибка.

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

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

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

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

curl

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

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