FlashingCall (Voice Code)#

При передаче сообщения FlashingCall (Voice Code) через HTTP-интеграцию действуют следующие ограничения:

  • текст сообщения – до 2000 символов;

  • текст должен обязательно содержать четырёх-, либо шестизначный цифровой код, используемый для звонка абоненту (в противном случае запрос будет отклонён с ошибкой 400, Invalid request, Flashing Call text should contain a 4(6)-digit code);

  • время жизни FlashingCall-сообщений – от 1 до 5 минут включительно.

Для отправки Voice Code необходимо указать тип сообщения FlashingCall и передать запрос, содержащий код. Указанный код (без сопутствующего текста) будет передан поставщику, который вставит его в текст шаблона сообщения. Результатом такого запроса будет звонок на телефон абонента. Когда абонент снимет трубку, он услышит голосовое сообщение, которое будет содержать код из четырёх цифр. Для подключения данной услуги необходимо обратиться в Службу технической поддержки и согласовать текст шаблона голосового сообщения.

Запрос на отправку сообщений FlashingCall (Voice Code)#

В HTTP API допустимы POST и GET запросы.

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

POST-запрос с сообщением на латинице “test“ в простом текстовом формате.

POST /login HTTP/1.1
Host: 10.10.10.10:9080
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Content-Length: 58
serviceId=login&pass=123&clientId=79161234567&message=test

Параметры запросов#

Параметры применимы для POST и GET запросов.

В таблице обязательные параметры выделены жирным шрифтом.

Параметр

Тип

Описание

clientId

string
Номер телефона абонента, до 25 символов.
Примеры: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.

message

string
Сообщение для отправки абоненту.
Партнёр должен передать в данном параметре:

  • для метода GET — текст должен быть в кодировке UTF-8 при передаче текстового сообщения;

  • для метода POST — текст должен быть в кодировке UTF-8, указанный в заголовке запроса.

Максимально допустимая длина сообщения для FlashingCall (Voice Code): 2000 символов.

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

При отправке FlashingCall сообщений следует учесть, что текст сообщения обязательно должен содержать четырёх-, либо шестизначный цифровой код, который используется для звонка абоненту. В противном случае будет возвращено сообщение c ошибкой: 400, Invalid request, Flashing Call text should contain a 4-digit code.

serviceId

string

Идентификатор сервиса (логин), от имени которого происходит отправка сообщения. Логин serviceId заводится Сервис-провайдером при подключении сервиса и сообщается Партнёру.

pass

string

Пароль для авторизации в сервисе. Пароль заводится Сервис-провайдером при подключении сервиса и сообщается Партнёру.

ptag

string

Идентификатор сообщения в системе Партнёра. Может содержать от одного до 50 символов. Допустимые символы: 0…9a…zA…Z-

Это может быть любой идентификатор в системе Партнёра.

Примечание

Например, уникальный идентификатор сообщения или идентификатор подразделения, инициирующего запрос на отправку. В отличие от параметра partnerMsgId, который нужен для контроля повторных отправок и дублирования, Сервис-провайдер не контролирует значения, переданные в параметре ptag (проверяется только соответствие формату).

Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках запроса на получение статуса доставки сообщения (этот функционал подробно описан в разделе «Сервис получения статусов доставки сообщений»).

sending_time

string
Локальное время отправки сообщения абоненту.
Задается в формате hh_hh, где два значения часа задают временной промежуток, в который должно быть отправлено сообщение.

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

Если параметр указан, то его значение не может быть пустым.

Примечание

Например, при значении параметра sending_time=10_20, сообщение будет отправлено в период с 10:00 до 20:00 по местному времени в часовом поясе абонента.

Часовой пояс абонента определяется не по фактическому местоположению абонента.
Если Партнёр не передает параметр time_zone, то часовой пояс абонента определяется по номеру телефона.
Если Партнёр передает в параметре time_zone часовой пояс, то сообщение будет отправлено абоненту по местному времени этого часового пояса.

time_zone

string

Часовой пояс абонента. Задается в формате ±hh:mm. Подробнее о формате см. ISO 8601.

Если Партнёр передает в этом параметре часовой пояс, то сообщение будет отправлено абоненту по местному времени этого часового пояса, иначе часовой пояс абонента определяется по номеру телефона абонента.

Примечание

Абонент с хабаровским номером находится в Москве. Возможны следующие варианты отправки:

  1. Получены значения: sending_time=10_20, time_zone=+04:00 (московское время).

    Сообщение будет отправлено в период с 10:00 до 20:00 по московскому времени.

  2. Получено значение sending_time=10_20 и не передан параметр time_zone. Сообщение будет отправлено в период с 10:00 до 20:00 по хабаровскому времени.

Для нулевой зоны обязательно указание знака, неважно «+» или «–«.
Знак «+» при кодировании URL преобразуется в «%2B».
Например, часовой пояс +04:00 передается так time_zone= %2B04:00.

source

string

Имя отправителя. Сообщение абоненту будет отправлено с сервисного имени, указанного в данном параметре.

Данный параметр не является обязательным. Если параметр отсутствует в запросе, то сообщение будет отправлено абоненту с имени по умолчанию (настройка на стороне Сервис-провайдера).

Важно

Использование данного параметра недоступно для Партнёра по умолчанию. Функционал может быть включен после согласования с Сервис-провайдером. В этом случае для Партнёра настраивается список разрешенных имен отправителей, либо включается функционал динамической подписи.

output

string

Формат ответа на запрос.

Если output=xml, то ответ на запрос будет сформирован в виде XML (подробнее в разделе «Ответ в формате XML»).

Во всех остальных случаях (параметр не задан или имеет другое значение) – используется формат по умолчанию: plain-текст (подробнее в разделе «Ответ на запрос»).

partnerMsgId

string

Уникальный идентификатор сообщения в системе Партнёра. Допустимая длина: от одного до 50 символов.

Данный параметр используется для контроля повторных отправок и дублирования. Партнёр может отправить запрос на отправку сообщения с одним и тем же partnerMsgId несколько раз.

При этом:

  • отправка сообщения абоненту будет выполнена только один раз (по первому запросу);

  • в ответах на данные запросы Сервис-провайдер вернет Партнёру один и тот же идентификатор сообщения в системе Сервис-провайдера (тот же, что на первый запрос).

Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках запроса на получение статуса доставки сообщения (этот функционал подробно описан в разделе «Сервис получения статусов доставки сообщений»).

Использование данного параметра недоступно по умолчанию. Подключение данного функционала нужно согласовать со своим курирующим менеджером.

Ответ на запрос#

После получения и обработки запроса Сервис-провайдер синхронно возвращает Партнёру ответ.
По умолчанию ответ от Сервис-провайдера приходит в формате text/plain.
По согласованию с Партнёром ответ может быть сформирован в формате XML.

Примечание

Сервис-провайдер отправляет сообщения абонентам только при успешной обработке запроса.

Ответ при успешной отправке запроса#

На успешный запрос Сервис-провайдер возвращает Партнёру:

  • HTTP-код «200 OK»;

  • идентификатор сообщения в системе Сервис-провайдера.

OK
4095284974

Ошибки при отправке запроса#

При передаче ошибочного запроса в теле ответа может возвращаться короткое текстовое сообщение об ошибке.

Пример ответа в случае возникновения ошибки неверного сочетания serviceId/pass:

Invalid password

Ответ в формате XML#

Для получения ответа в формате XML Партнеру в теле запроса необходимо передать параметр output=xml.
В таком случае Сервис-провайдер синхронно отвечает на запрос одним из следующих HTTP-кодов:

  • 200 – запрос успешно обработан;

  • 500 – внутренняя ошибка сервера, технические проблемы на стороне Сервис-провайдера.

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

Пример ответа в формате XML при успешной отправке запроса (HTTP-код 200) .
Описание содержания ответа приведено во вкладке «Элементы XML».
<?xml version="1.0" encoding="utf-8"?>
<response>
    <code>200</code>
    <text>OK</text>
    <payload>
        <id>4095284976</id>
    </payload>
</response>