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

SMS

Для отправки сообщений Вам понадобятся:

Отправка

Для отправки SMS-сообщения используйте вызов POST /sms/messages

Запрос

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

Параметр Тип данных Описание и Допустимые значения
includeSegmentId
(optional)
boolean Если true, то в ответе для каждого также будет указан массив идентификаторов для каждого сегмента сообщения. По умолчанию false.
shortenUrl
(optional)
boolean Флаг, который сокращает длинну ссылки: если true, то ссылка будет сокращена. По умолчанию false.

Тело запроса

Параметр Тип данных Описание и Допустимые значения
messages array[Message] Массив объектов Message

Message

Параметр Тип данных Описание и Допустимые значения
from string Имя отправителя
Не более 11 латинских символов или 15 цифр
to string Номер телефона в международном формате, согласно стандарту E.164
text string Текст сообщения
validity
(optional)
integer Срок жизни сообщения в секундах
Минимальное значение: 1
Максимальное значение: 259200, 3 суток
По умолчанию: 172800, 2 суток
priority
(optional)
priority Приоритет отправки сообщения
От 0 до 3, где:
0 - низкий приоритет
3 - наивысший
0 - по умолчанию
callbackUrl
(optional)
string URL, на который система будет отправлять уведомления об изменениях статуса сообщения
Любой валидный URL со схемой http или https
options
(optional)
object Объект с данными, которые необходимы внешним системам при получении статусов сообщений
Любой массив вида: “key”:
{“key1”: “value1”,“key2”: “value2” }

Ответ

Параметр Тип данных Описание и допустимые значения
code string Указывает на результат обработки сообщения.
1. OK - Успешно обработано
2. REJECTED - Произоошла ошибка во время обработки запроса.
reasons
(optional)
object[string, string] Массив ошибок, произошедших во время обработки сообщения.
Указывается только при code=REJECTED
reasons.key string Код ошибки.
reasons.ref
(optional)
string Ссылка на параметр, в котором произошла ошибка.
messageId
(optional)
string Идентификатор сообщения.
Указывается только при code=OK
description
(optional)
string Описание ошибки.
Указывается только при code=REJECTED
segmentsId
(optional)
array[string] Массив идентификаторов для каждого сегмента сообщения. До 255 элементов включительно.

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

curl -X POST 'https://api.devino.online/sms/messages' \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '{ 
    "messages": [ 
        { 
            "from": "MyCompany",
            "to": "79034567890",
            "text": "Code: 1234"
        },
        { 
            "from": "TAXI", 
            "to": " 89034567890", 
            "text": "Code: 1234"
        }
    ]
}' /* (1) */ 

{
    "result": [
        {
            "code": "OK",
            "messageId": "3482512350952730368"
        },
        {
            "code": "REJECTED",
            "messageId": null,
            "segmentsId": null,
            "reasons": [ 
                {
                    "key": "not.available",
                    "ref": "messages[0].from"
                } // (2)
            ],
            "description": "Error: Source address in not available. Source address: TAXI"
        }
    ]
}
  1. В некоторых случаях значение to может быть исправлено, но не стоит на это полагаться. Получателем первого и второго сообщений по итогу будет один абонент.
  2. Для каждого сообщения указываются все ошибки запроса, если такое возможно, чтобы вы могли их сразу устранить.

Коды ошибок

Key Ref Описание
billing.error Требуется оплата
forbidden Отправка запрещена
unknown Неизвестная ошибка
invalid messages[i].to Неправильно указан номер телефона
invalid messages[i].validity Неправильно указан срок жизни
invalid messages[i].callbackUrl Неправильно указан URL
length.too.long messages[i].to Превышена максимальная длина номера телефона
length.too.long messages[i].text Превышена максимальная длина текста сообщения
must.be.not.null messages Массив messages не может быть пустым
not.available messages[i].from Неправильно указан отправитель
too.many.messages messages Превышен максимальный размер массива messages

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

Помимо Webhook есть возможность запрашивать статус сообщений, используя POST /sms-stat/statuses/get-by-ids, передавая не более 500 идентификаторов идентификаторов сообщений в теле запроса с указанием данных авторизации в заголовке.

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

curl -X POST \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '[ "3482512350952730368" ]' \
https://api.devino.online/sms-stat/statuses/get-by-ids
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": 3482512350952730368,
      "status": "DELIVERED",
      "statusDateTime": "2020-11-11 11:20:35"
    }
  ]
}
{
  "description": "string",
  "reasons": [
    {
      "key": "string",
      "params": [
        {}
      ],
      "ref": "string"
    }
  ],
  "result": [
    {
      "smsId": 0,
      "status": "STATUS",
      "statusDateTime": "2020-11-11 11:23:06"
    }
  ]
}

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

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

Webhooks

Входящие уведомления

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

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

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

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

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

Параметры

Параметр Тип данных Описание
incomingMessageId long Индификатор входящего сообщения в Devino
to string Адрес получателя
from string Адрес отправителя
text string Текст сообщения
transactionId string Идентификатор входящего сообщения от оператора
countryName string Страна
operator string Оператор
prefix string Префикс
ts long Timestamp с миллисекундами получения сообщения

Уведомления об изменении статусов

При формировании статуса сообщения будет отправлен POST-запрос на URL, указанный при отправке сообщения в параметре callbackUrl. В ответ на запрос ожидается 200 Ok.

В случае, если на запрос вернётся 500 Internal Error, то будут предприниматься попытки доставки статуса 5 раз с интервалом в минуту.

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

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

Параметр Тип данных Статус Описание и Допустимые значения
messageId long any Уникальный идентификатор сообщения на платформе
ts int any Указывает на время события в миллисекундах
status enum any Код статуса доставки SMS сообщения
Подробнее см. раздел Возможные статусы
errorCode
(optional)
int rejected
undeliverable
Код причины недоставки сообщения

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

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