Перейти к содержанию

SMS

Отправка

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

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

Параметр Тип данных Описание
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 для отправки коллбэков.

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

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

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

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

Для получения входящих 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 Произошла неизвестная ошибка.

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

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

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

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

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

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

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

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

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