SMS#

Допустимые типы данных при передаче запроса:

  • текстовые данные – передаются как текстовое SMS-сообщение;

  • двоичные данные – передаются в теле SMS-сообщения.

Время жизни SMS-сообщений: от 1 до 2880 минут (не более 48 часов).
Время жизни сообщения настраивается на стороне Сервис-провайдера по согласованию с Партнёром.

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

Метод: GET.

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

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

http://partner.ru/login?clientId=79161234567&message=test&pass=123&serviceId=login

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

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

Параметр

Тип

Описание

clientId

string

Номер телефона абонента, до 25 символов.

Примеры: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.

message

string

Сообщение для отправки абоненту.

Подробнее

Текст в данном параметре должен быть в кодировке UTF-8.

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

serviceId

string

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

Подробнее

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

pass

string

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

Подробнее

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

ptag

string

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

Подробнее

Допустимые символы: 0...9a...zA...Z-

Количество символов: от одного до 50.

Это может быть любой идентификатор в системе Партнёра. Например, уникальный идентификатор сообщения или идентификатор подразделения, инициирующего запрос на отправку.

В отличие от параметра 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.

flash

string

Признак отправки Flash-SMS.

Подробнее

Если параметр flash=1, абоненту будет оправлено Flash-SMS.

Если параметр отсутствует или не равен «1», будет отправлено обычное SMS-сообщение.

Максимальная длина SMS-сообщений с установленным признаком flash:

  • 70 символов (для кириллического текста);
  • 140 символов (для текста в формате unicode).

source

string

Сервисное имя отправителя.

Подробнее

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

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

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

output

string

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

Подробнее

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

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

partnerMsgId

string

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

Подробнее

Количество символов: от одного до 50.

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

При этом:

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

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

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

smsPriority

integer

Параметр указывает на приоритет сообщения.

Подробнее

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

Возможные значения:

  • 0 – самый низкий приоритет;
  • 1 – нормальный приоритет;
  • 2 – высокий приоритет.

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

shortenLinks

boolean

Параметр указывает, требуется ли сокращать ссылки в тексте сообщения.

Подробнее

Используется только для одиночных сообщений.

В случае каскадной доотправки необходимо использовать параметр shorten_list (см. Каскадные сообщения).

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

Подробнее: см. Сервис сокращения ссылок.

Запросы с двоичными данными#

При передаче двоичных данных в тексте сообщения передается последовательность байт в шестнадцатеричной системе счисления.

Для передачи двоичных данных в запросе необходимо указать дополнительные параметры (см. ниже).

Метод: GET.

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

http://partner.ru/login?clientId=79161234567&message=0605040b8423f0dc0601ae02056a0045c60b03687474703a2f2f7761702e7A616772757A6B612e636F6D0001035A616772757A6B6155524C000101&serviceId=login&pass=123&smpp_encoding=245&smpp_esm_class=64

Параметры для передачи двоичных данных в запросе#

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

Параметр

Тип

Описание

message

string

Сообщение для отправки абоненту.

Подробнее

При отправке двоичных данных параметр содержит последовательность байт в шестнадцатеричной системе счисления (стандартный HEX Decimal).

Наличие иных символов в тексте недопустимо.

Для передачи двоичного сообщения текст должен быть в кодировке UTF-8.

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

smpp_encoding

integer

Интерпретация данных.

Подробнее

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

Для определенных разновидностей сообщений указывается один из параметров (или оба одновременно).

Множество значений этих параметров задается протоколом SMPP версии 3.4.

При отправке двоичного сообщения абоненту во всех его частях проставляются указанные значения параметров smpp_encoding и smpp_esm_class.

Если не установлен ни один из параметров smpp_encoding и smpp_esm_class, сообщение обрабатывается как текстовое.

smpp_esm_class

integer

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

После получения и обработки запроса Сервис-провайдер синхронно возвращает Партнёру ответ.
По умолчанию ответ от Сервис-провайдера приходит в формате 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>