SMS

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

• учетная запись devino.online;
• согласованное имя отправителя;
• API Key для авторизации.

Отправка

Для отправки 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

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": 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 раз с интервалом в минуту.

Delivered

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

Rejected

[
  {
    "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	Произошла неизвестная ошибка.