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

Описание¶

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

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

Внимание

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

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

Прием входящих SMS позволяет получить обратную связь от абонентов клиента через SMS сообщения на закрепленный за клиентом номер. На сообщение, присланное абонентом, можно отправить ответное сообщение.

Клиент может осуществлять прием входящих SMS:

По протоколу HTTP через API сервиса доставки SMS-платформы
Передачей входящего сообщения по протоколу HTTP на внешний обработчик клиента
По протоколу SMPP

Для начала использования услуги получения SMS-сообщений от абонентов клиенту необходимо:

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

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

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

Параметр	Тип данных	Описание
sessionId обязательный	string	ID сессии (36 символов).
maxDateUTC обязательный	DateTime	Дата и время окончания периода, за который происходит выборка входящих сообщений (например, `2010-06-02T19:14:00`).
minDateUTC	DateTime	Дата и время начала периода, за который происходит выборка входящих сообщений (например, `2010-06-01T19:14:00`).

Формат запроса:

application/x-www-form-urlencoded
https://integrationapi.net/rest/Sms/In?
sessionId=<ID сессии>&
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

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

HTTP/1.1 200 OK
Cache-Control: private
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
[
  {
    "Data":<Текст сообщения>,
    "SourceAddress":<Адрес отправителя>,
    "DestinationAddress":<Номер получателя>,
    "ID":<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-сообщений).

Если внешний обработчик не отвечает в течении 30 секунд, будет выполнена повторная попытка отправки. Если обработчик возвращает ошибку, платформа повторяет попытку отправить запрос через 300 секунд.

Создание запроса на добавление входящего номера в личном кабинете:

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

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

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

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

Описание¶

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

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

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

Поле для ввода текста общего ответного SMS-сообщения:

При создании заявки на добавление нового входящего номера через личный кабинет:

При создании заявки на добавление нового входящего номера через подсистему администрирования:

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

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

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

Например:

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: text/plain; charset=utf-8
{sms=<Текст ответного сообщения>}

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