Push#

Через HTTP API поддерживается отправка только текстовых push-сообщений.

Время жизни push-сообщений: от 30 до 86400 секунд (24 часа).
Время жизни сообщения настраивается на стороне Сервис-провайдера по согласованию с Партнёром.

Запрос на отправку сообщений#

В 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

Текст сообщения в кодировке UTF-8.

Подробнее

Максимальная длина: 1000 символов.

serviceId

да

string

Идентификатор сервиса (логин), от имени которого происходит отправка сообщения.

Подробнее

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

pass

да

string

Пароль для авторизации в сервисе.

Подробнее

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

ptag

нет

string

Идентификатор сообщения в системе Партнёра.

Подробнее

Может содержать от 1 до 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).

Если параметр не задан или имеет другое значение, будет применён формат простой текст (text/plain), см. Ответ на запрос.

partnerMsgId

нет

string

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

Подробнее

Допустимая длина: от 1 до 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 version="1.0" encoding="utf-8"?>
<response>
    <code>200</code>
    <text>OK</text>
    <payload>
        <id>4095284976</id>
    </payload>
</response>

Статусы доставки сообщений#

Для получения статусов сообщений необходимо настроить Сервис получения статусов доставки.

Коды ошибок доставки#

Коды ошибок доставки, в зависимости от типа сообщения, приведены в соответствующей вкладке в разделе Описание кодов ошибок (параметр unifiedExtStatus).