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"
}
]
}
- В некоторых случаях значение
to
может быть исправлено, но не стоит на это полагаться. Получателем первого и второго сообщений по итогу будет один абонент. - Для каждого сообщения указываются все ошибки запроса, если такое возможно, чтобы вы могли их сразу устранить.
Коды ошибок¶
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 | Произошла неизвестная ошибка. |