Работа с входящими SMS сообщениями (HTTP для приёма)

Назначение документа

Документ предназначен для использования в качества руководства для разработчиков и сотрудников технической поддержки. Руководство содержит описание функционала работы с входящими SMS-сообщениями. Функционал позволяет осуществлять:

  • Получение входящих SMS-сообщений;
  • Отображение входящих SMS-сообщений за определенный период в «Личном кабинете»;
  • Отправку ответного SMS, включая:
  • Отправку общего ответного SMS-сообщения;
  • Отправку индивидуального ответного SMS-сообщения;
  • Отображение отправленных ответных SMS в «Личном кабинете»;
  • Отображение перечня входящих номеров в «Личном кабинете»;
  • Создание Клиентом группы для входящих сообщений в «Личном кабинете»;
  • Экспорт входящих сообщений в файл формата *.csv.

Предупреждение

Внимание! Для использования данного вида интеграции необходимо обратиться к своему менеджеру, либо в техническую поддержку support@devinotele.com для настройки доступа.

Настройка приёма SMS-сообщения

Общие положения

«Прием входящих SMS» - это услуга, позволяющая получить обратную связь от Абонентов Клиента через SMS сообщения на закрепленный за Клиентом номер. На сообщение, присланное Абонентом, можно отправить Ответное сообщение. Клиент может осуществлять «Прием входящих SMS» следующими способами:

  • По протоколу http через API «Сервиса доставки SMS» платформы;
  • Передачей входящего сообщения по протоколу http на внешний обработчик Клиента;
  • По протоколу SMPP.

Для начала использования услуги получения sms-сообщений от Абонентов Клиенту необходимо: 1. Зарегистрироваться в Личном кабинете; 2. Заключить договор; 3. Подать заявку на подключение входящего номера, указав при этом необходимые параметры:

  • Логин;
  • Номер;
  • Текст ответного сообщения (опционально, если необходимо отправлять Ответные сообщения);
  • URL для приема входящих SMS-сообщений (опционально, если необходимо отправлять входящие SMS по протоколу http внешнему обработчику);
  • Примечание (опционально, примечание к заявке на подключение нового входящего номера).

По протоколу HTTP

Возможно получение входящих sms-сообщений за период по протоколу HTTP с использованием предоставляемого API платформы. Для этого необходимо пройти процедуру предварительной аутентификации и получить идентификатор сессии. После этого платформа вернет данные входящих SMS в соответствии со значениями параметров, которые необходимо передать ей в GET-запросе следующего формата:

application/x-www-form-urlencoded
https://integrationapi.net/rest/Sms/In?
sessionId=<Идентификатор сессии>&
minDateUTC=<Дата и время начала периода>&
maxDateUTC=<Дата и время окончания периода>

Ниже приведен пример запроса:

application/x-www-form-urlencoded
https://integrationapi.net/rest/Sms/In?
sessionId=Z5CYSZEKDL1DPICU37WEHQVOYKP0T1GSLHX1&
minDateUTC=2011-01-01T00:00:00&
maxDateUTC=2011-01-11T00:00:00
Параметр Тип данных Описание
Обязательные
sessionId String Идентификатор сессии (36 символов). Обязательный.
maxDateUTC DateTime Дата и время окончания периода, за который происходит выборка входящих сообщений (например, 2010-06-02T19:14:00).
Необязательные
minDateUTC DateTime Дата и время начала периода, за который происходит выборка входящих сообщений (например, 2010-06-01T19:14:00).

После получения запроса платформа проверит валидность идентификатора сессии, даты-времени начала и окончания периода выборки. Если все проверки пройдены успешно, то платформа вернет перечень сообщений и их параметров за период в json-файла следующего формата:

HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
[{"Data":<Текст сообщения>,
"SourceAddress":<Адрес отправителя>,
"DestinationAddress":<Номер получателя>,
"ID":<Идентификатор сообщения>,
"CreatedDateUtc":<Дата создания>}]

Например:

HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
[{"Data":"test1",
"SourceAddress":"79260000000",
"DestinationAddress":"79160000000",
"ID":539187174,
"CreatedDateUtc":"\/Date(1294045911213)\/"},
{"Data":"test2",
"SourceAddress":"79260000001",
"DestinationAddress":"79160000000",
"ID":539187214,
"CreatedDateUtc":"\/Date(1294045911353)\/"}]

Если какая-нибудь проверка не проходит успешно, то платформа возвращает Код ошибки в виде JSON следующего формата:

{
    Code: <Код ошибки>
    Desc: <”Текст ошибки”>
}

Например:

{
    Code: 9
    Desc: "The parameters dictionary contains a null entry for parameter
    'maxDateUtc' of non-nullable type 'DateTime' for method
    'System.Web.Mvc.ActionResult In(System.String, DateTime, DateTime)' in
    'RestService.Controllers.SmsController'. An optional parameter must be a
    reference type, a nullable type, or be declared as an optional parameter.
    Parameter name: parameters"
}

Через внешний обработчик

Возможен прием входящих SMS сообщений на короткие номера через внешний обработчик. Для этого Клиент при создании запроса на подключение входящего номера должен указать адрес обработчика (параметр «URL для приема входящих SMS-сообщений»). Если внешний обработчик не отвечает или возвращает ошибку, платформа повторяет попытку отправить запрос еще 4 раза через равные промежутки в 60 секунд.

_images/vhod1.jpg

Рис. 1. Создание запроса на добавление входящего номера в “Личном кабинете”

_images/vhod2.jpg

Рис. 2. Создание запроса на добавление входящего номера в подсистеме администрирования

По протоколу SMPP

Возможен прием входящих SMS сообщений по протоколу SMPP на заранее согласованный с менеджером номер посредством приема пакетов Deliver_SM в рамках открытой SMPP сессии.

Настройка отправки ответного SMS-сообщения

Общие положения

«Ответное SMS-сообщение» - это услуга, позволяющая отправлять ответное сообщение Абоненту, приславшему сообщение на короткий или федеральный номер.

Общее ответное SMS

Для подключение услуги «Общее ответное SMS» Клиенту необходимо создать запрос. В запросе должен быть указан текст общего ответного SMS-сообщения. Если текст указан, то после подтверждения заявки Менеджером и активации услуги все Абоненты, приславшие SMS сообщение на входящий номер Клиента, получат ответное SMS-сообщение с текстом, указанным в запросе.

_images/vhod3.jpg

Рис. 3. Поле для ввода текста общего ответного SMS-сообщения при создании заявки на добавление нового “Входящего номера” через «Личный кабинет»

_images/vhod4.jpg

Рис. 4. Поле для ввода текста общего ответного SMS-сообщения при создании заявки на добавление нового “Входящего номера” через подсистему администрирования

Индивидуальное ответное SMS

Если входящие SMS-сообщения передаются на внешний обработчик, становится возможна отправка индивидуального ответного SMS-сообщения. Для этого, когда платформа посылает запрос внешнему обработчику со следующими параметрами:

application/x-www-form-urlencoded
<Адрес внешнего обработчика (ExternalHandler)>?
sourcePhone=<Номер Абонента, которому требуется ответить>&
number=<Номер с которого будет прислан ответ>&
prefix=<Префикс>&
text=<Текст>&
messageId=<Идентификатор сообщения>

Например:

application/x-www-form-urlencoded
<Адрес внешнего обработчика (ExternalHandler)>?
sourcePhone=79089876534&
number=2435&
prefix= loto&
text= Играйте с нами в лото!&
messageId=235515

Внешнему обработчику необходимо отправить ответ платформе (в течение 1 минуты) со следующими параметрами:

HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
{sms=<Текст ответного сообщения>}

Если платформа получит ответ, то абонент с номером «sourcePhone» (из запроса платформы) получит ответное SMS-сообщение с номера отправителя «number» (из запроса платформы) и текстом «sms» (из ответа внешнего обработчика).