SMS¶

Отправка¶

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

Согласовать имя отправителя в личном кабинете.
Вызвать POST /sms/messages, передавая параметры сообщения в теле запроса и данные авторизации в заголовке.

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

Параметр Тип данных Описание

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)	string	Запланированное 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 для отправки коллбэков.

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

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": "3701172084729885952",
      "segmentsId": [
        "3701172084729885952",
        "3701172084729885953"
      ]
    }
  ]
}

REJECTED

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

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

DELIVERED

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

REJECTED

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

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

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

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

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

curl

curl -X POST https://api.devino.online/sms-stat/statuses/get-by-ids \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '[ "3482512350952730368" ]'

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": 3701172084729885700,
      "status": "DELIVERED",
      "statusDateTime": "2022-09-09 19:29:34"
    }
  ]
}

Детализация¶

Для получения детальных сведений об отправленных сообщениях необходимо вызвать GET /sms-stat/detail, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
limit	integer	Количество сообщений в результатах поиска.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив сообщений будет отображаться, начиная с 5 позиции.
taskId (optional)	integer	ID рассылки, по которой нужно получить детализацию. Можно узнать при создании сценария рассылки. Используется в обязательной комбинации параметров.
triggerId (optional)	integer	ID триггера рассылки. Можно узнать при получении сценария рассылки. Используется в обязательной комбинации параметров.
dateTimeFrom (optional)	datetime	Дата начала поиска сообщений. Используется в обязательной комбинации параметров. Формат `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo (optional)	datetime	Дата окончания поиска сообщений. Используется в обязательной комбинации параметров. Формат `YYYY-MM-DD+hh:mm:ss`.
messageIds (optional)	array[integer]	ID сообщений, по которым нужно получить детализацию. Используется в обязательной комбинации параметров.
bySegments (optional)	boolean	Если `true`, то каждое сообщение будет разбито на сегменты (если сегментов больше 1). У каждого сегмента будет свой ID (поле `SEGMENT_ID`). Если `false`, то сообщение будет отображаться целиком, с указанием количества сегментов (поле `SEGMENTS_COUNT`).
calculateTotalCount (optional)	boolean	Если `true`, в ответе будет указано общее количество сообщений и страниц, подходящих под параметры запроса (параметры `total` и `pages`).
countryId (optional)	integer	ID страны.
mogId (optional)	integer	ID группы мобильных операторов.
order (optional)	string	В каком порядке выводить результаты запроса. Возможные значения: ○ `ASC` - в возрастающем порядке. ○ `DESC` - в убывающем порядке.
orderField (optional)	string	Поле, по которому будут отсортированы результаты запроса.
outFields (optional)	array[string]	Поля в результатах поиска. Неуказанные в этом параметре поля будут исключены.
recipient (optional)	string	Номер телефона получателя.
searchText (optional)	string	Поиск ключевого слова в текстах сообщений. Доступен поиск одного слова на английском языке.
sourceAddress (optional)	string	Согласованное имя отправителя.
status (optional)	string	Статус сообщений в результатах поиска. Возможные значения: ○ `DELIVERED` - сообщение доставлено получателю. ○ `IN_PROGRESS` - сообщение находится в процессе отправки. ○ `REDIRECT` - получатель перешел по ссылке в сообщении. ○ `REJECTED` - сообщение было отклонено оператором или Devino.Online. ○ `UNDELIVERED` - сообщение не доставлено.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT+3).
userId (optional)	integer	ID пользователя, проводившего рассылку.

Комбинации параметров¶

Для корректной работы метода в запросе необходимо использовать одну из этих комбинаций параметров в соответствии со списком:

ID рассылки: taskId
ID рассылки и триггера: taskId, triggerId
Даты начала и окончания поиска сообщений: dateTimeFrom, dateTimeTo
ID рассылки, триггера; даты начала и окончания поиска сообщений: taskId, triggerId, dateTimeFrom, dateTimeTo
ID сообщений: messageIds

Поля для параметров `orderField` и `outFields`¶

Используются в параметрах orderField для сортировки результатов поиска и outFields для фильтрации полей.

Название поля	Описание
COMPANY_ID	ID компании.
COMPANY_NAME	Название компании.
CONTACT_ID	ID получателя из списка контактов.
COUNTRY_ID	ID страны.
COUNTRY_NAME	Название страны.
ERROR_CODE	Код ошибки.
EVENT_DATE_TIME	Дата и время последнего обновления статуса сообщения.
MESSAGE_ID	ID сообщения.
MOG_ID	ID группы мобильных операторов.
MOG_NAME	Название группы мобильных операторов.
MO_ID	ID мобильного оператора.
MO_NAME	Название мобильного оператора.
PRICE	Стоимость сегмента сообщения.
PROVIDER_MESSAGE_ID	ID сообщения у оператора.
RECIPIENT	Номер телефона получателя.
RECIPIENT_ZONE_NAME	Часовой пояс получателя.
ROUTE	Маршрут, по которому было отправлено сообщение (например: `SMSGW101`).
SEGMENT_COUNT	Количество сегментов в сообщении.
SEGMENT_ID	ID сегмента.
SENT_DATE_TIME	Дата и время отправки.
SOURCE_ADDRESS	Имя отправителя.
STATUS	Статус сообщения.
TASK_ID	ID рассылки.
TASK_NAME	Название рассылки.
TASK_TYPE	Тип рассылки.
TEMPLATE	Название шаблона сообщения.
TEMPLATE_ID	ID шаблона сообщения.
TEXT	Текст сообщения.
TRAFFIC	Тип трафика. Возможные значения: ○ `ADVERTISING` - рекламный трафик. ○ `AUTHORIZATION` - авторизационный трафик. ○ `INCOMING` - входящий трафик. ○ `SERVICE` - сервисный трафик. ○ `TRANSACTIONAL` - транзакционный трафик.
TRIGGER_CONTACT_GROUP	Название списка контактов, по которому проходила рассылка.
IS_CONTACT_GROUP_DELETED	Удален ли список контактов, контакту которого было отправлено сообщение.
TRIGGER_ID	ID триггера рассылки.
USER_ID	ID пользователя, отправившего сообщения.
USER_LOGIN	Логин пользователя, отправившего сообщения.

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

С датами

curl -X GET https://api.devino.online/sms-stat/detail?calculateTotalCount=true&dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-02-24+00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

С ID рассылки и триггера

curl -X GET https://api.devino.online/sms-stat/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Параметры ответа¶

Параметр	Тип данных	Описание
data	array[object]	Массив объектов с детальной информацией по каждому сообщению. Параметры определяются полями, которые были заданы в изначальном запросе.
size	integer	Количество элементов на странице и сообщений в результатах поиска. Задается параметром `limit`.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив сообщений будет отображаться, начиная с 5 позиции.
number	integer	Номер полученной страницы. Определяется параметром `offset`. ○ Если значение параметра `offset` будет `0` при любом значении параметра `limit`, то номер полученной страницы будет `1`. ○ Если `offset` будет больше `0`, но меньше, чем значение параметра `limit`, номер страницы будет `2`. Например, при `"offset": 5` и `"limit": 10`, значение параметра `number` будет `2`. ○ Если `offset` будет больше чем `limit`, то номер страницы будет определяться целочисленным делением `offset` на `limit` плюс 1 (`offset` / `limit` + 1). Например, при `"offset": 1000` и `"limit": 50`, значение параметра `number` будет `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Существует ли отображаемая страница.
total	integer	Общее количество сообщений, по которым можно получить детализацию.
pages	integer	Общее количество страниц, по которым можно получить детализацию. Определяется целочисленным делением параметра `total` на `limit` (`total` / `limit`).
more	boolean	Индикатор: существуют ли страницы после текущей, указанной в параметре `number`.

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

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "sentDateTime": "2022-12-14 05:55:32",
        "segmentId": "234567865432456787634",
        "sourceAddress": "sendersName",
        "recipient": "79001112233",
        "status": "DELIVERED",
        "eventDateTime": "2022-12-14 05:54:52",
        "companyId": 234,
        "companyName": "MyCompany",
        "userId": 88,
        "userLogin": "79991112233",
        "countryId": 12,
        "countryName": "Russia",
        "mogId": 0,
        "mogName": "MOG",
        "moId": 234,
        "moName": "Operator Name",
        "taskId": 88888888,
        "taskName": "SimpleCampaign",
        "taskType": "SIMPLE",
        "triggerId": 2345678,
        "text": "Hello",
        "errorCode": 0,
        "traffic": "ADVERTISING",
        "recipientZoneName": "UTC +03:00",
        "triggerContactGroup": "contactGroup",
        "isContactGroupDeleted": "No"
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Статистика сообщений¶

Для получения общей статистики по статусам сообщений необходимо вызвать GET /sms-stat/statistics/of-group, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
groupBy	string	Группировка результатов: ○ `NONE` - без группировки ○ `YEAR` - по годам ○ `MONTH` - по месяцам ○ `WEEK` - по неделям ○ `DAY` - по дням ○ `HOUR` - по часам
startDate	datetime	Дата начала периода сбора статистики. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
endDate	datetime	Дата окончания периода сбора статистики. Формат - `YYYY-MM-DDThh%3Amm%3Ass`.
taskId (optional)	integer	ID рассылки, по которой нужно получить статистику.
triggerId (optional)	integer	ID триггера рассылки, по которому нужно получить статистику.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT+3).

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

curl -X GET https://api.devino.online/sms-stat/statistics/of-group?startDate=2022-10-06T13%3A45%3A30&endDate=2023-02-06T13%3A45%3A30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Параметры ответа¶

Параметр	Тип данных	Описание
messages	array[MessageStatusObject]	Количество сообщений по выбранному периоду, сгруппированных по статусам.
segments	array[MessageStatusObject]	Количество сегментов сообщений по выбранному периоду, сгруппированных по статусам.

MessageStatusObject¶

Объект содержит информацию о количестве сообщений со статусами:

Код	Описание
accepted	Сообщение было принято.
scheduled	Сообщение запланировано к отправке.
enrouted	Сообщение находится в процессе отправки оператору.
sent	Сообщение было отправлено в сеть оператора.
deleted	Сообщение было удалено.
delivered	Сообщение доставлено абоненту.
expired	Истек срок жизни сообщения.
seen	Сообщение было прочитано получателем.
clicked	Получатель перешел по ссылке в сообщении.
rejected	Сообщение было отклонено оператором или Devino.Online.
undeliverable	Сообщение невозможно доставить.
unknown	Произошла неизвестная ошибка.

Каждый статус включает в себя параметры:

Параметр	Тип данных	Описание
date	string	Дата сбора статистики в зависимости от значения параметра `groupBy`.
amount	integer	Количество сообщений.

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

{
  "result": {
    "messages": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 100
        }
      ],
      "sent": [
        {
          "date": "2022-12-01 00:00:00",
          "amount": 2
        }
      ],
      "deleted": [],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 67
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 1
        },
        {
          "date": "2022-12-01 00:00:00",
          "amount": 72
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 3
        }
      ],
      "enrouted": [],
      "expired": [],
      "seen": [],
      "clicked": [],
      "rejected": [],
      "scheduled": [],
      "undeliverable": [],
      "unknown": []
    },
    "segments": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 4
        }
      ]
      ...
    }
  }
}

SMS¶

Отправка¶

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

Тело запроса¶

Message¶

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

Параметры ответа¶

Коды ошибок¶

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

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

Параметры¶

Пример¶

Коллбэки¶

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

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

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

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

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

Детализация¶

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

Комбинации параметров¶

Поля для параметров orderField и outFields¶

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

Параметры ответа¶

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

Статистика сообщений¶

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

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

Параметры ответа¶

MessageStatusObject¶

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

Поля для параметров `orderField` и `outFields`¶