SMS¶
Отправка¶
Для отправки SMS-сообщения необходимо:
- Согласовать имя отправителя в личном кабинете.
- Вызвать POST /sms/messages, передавая параметры сообщения в теле запроса и данные авторизации в заголовке.
Параметры запроса¶
Параметр | Тип данных | Описание |
---|---|---|
includeSegmentId (optional) |
boolean | Если true , то в ответе также будет указан массив с ID для каждого сегмента SMS-сообщения. По умолчанию false . |
shortenUrl (optional) |
boolean | При К примеру, если параметр активен, ссылка По умолчанию |
Тело запроса¶
Параметр | Тип данных | Описание |
---|---|---|
messages | array[Message] | Массив сообщений. Одновременно можно отправлять до 32 тысяч сообщений. |
Message¶
Параметр | Тип данных | Описание |
---|---|---|
from | string | Согласованное имя отправителя. |
to | string | Номер телефона в международном формате, согласно стандарту E.164. |
text | string | Текст сообщения: ○ до 17085 символов включительно при использовании кириллицы. ○ до 34170 символов включительно при использовании латиницы. |
validity (optional) |
integer | Срок жизни сообщения в секундах. Минимальное значение: 0 |
scheduledTime (optional) |
integer | Запланированное UTC время отправки сообщения. |
priority (optional) |
string | Приоритет отправки сообщения.
|
callbackUrl (optional) |
string | URL, на который система будет отправлять уведомления об изменениях статуса сообщения. Любой валидный URL со схемой |
options (optional) |
object | Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида |
Пример запроса¶
{
"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. |
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"
}
]
}