SMS#

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

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

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

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

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

В 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, указанный в заголовке запроса.

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

Важно

При отправке SMS-сообщений с установленным признаком flash длина сообщения не должна превышать 70 символов (для кириллического текста) или 140 символов (для текста в формате unicode).

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.

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 (см. Каскадные сообщения).

Важно

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

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

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

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

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

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

{
    POST /login HTTP/1.1
    Host: 10.241.0.194:9080
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
    Content-Length: 208
    serviceId=login&pass=123&clientId=79161234567&message=0605040b8423f0dc0601ae02056a0045c60b03687474703a2f2f7761702e7A616772757A6B612e636F6D0001035A616772757A6B6155524C000101&smpp_encoding=245&smpp_esm_class=64
}

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

Примечание

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

Параметр

Тип

Описание

message

string
При отправке двоичных данных параметр содержит последовательность байт в шестнадцатеричной системе счисления (стандартный HEX Decimal).
Наличие иных символов в тексте недопустимо.
Для передачи двоичного SMS-сообщения (GET или POST) текст должен быть в кодировке UTF-8.
Максимально допустимая длина сообщения для SMS: 2000 символов.

smpp_encoding

integer
Для корректной доставки двоичного SMS-сообщения следует передать в запросе дополнительные параметры, обеспечивающие верную интерпретацию данных после отправки с использованием протокола SMPP версии 3.4.
Для определенных разновидностей сообщений указывается один из параметров (или оба одновременно).
Множество значений этих параметров задается протоколом SMPP версии 3.4 в разделах для параметров smpp_encoding и smpp_esm_class.
При отправке двоичного сообщения абоненту во всех его частях проставляются указанные значения параметров 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>
}