Push#

Отправка push-уведомлений#

В мобильных и веб push-уведомлениях доступна передача текста и, опционально, дополнительных параметров.

Примеры дополнительных параметров:

  • заголовок;

  • изображения;

  • кнопки выбора действия;

  • HTML-страницы;

  • шаблоны для передачи чувствительных данных;

  • параметры для обогащения данных;

  • данные без предварительной обработки (в формате JSON);

  • клиентские данные для статистики;

  • данные для обновления виджета Live Activity;

  • признак главного приложения;

  • подписки мобильного приложения;

  • указание провайдеров (APNS, FCM, HMS, RuStore, PWA) для передачи данных.

Примеры запросов на отправку push-уведомлений#

Для формирования тестового запроса с вашими параметрами Внешняя ссылка Открыть генератор запросов

Описание параметров useTimeDiff ; destAddr.

 1 {
 2    "login":"ВАШ_ЛОГИН",
 3    "password":"ВАШ_ПАРОЛЬ",
 4    "id":"8770630",
 5    "extraParam":"param1=value1,param2=value2",
 6    "registeredDelivery":"1",
 7    "notifyUrl":"URL_для_передачи_статусов",
 8    "useTimeDiff":true,
 9    "scheduleInfo":{
10       "timeBegin":"10:00",
11       "timeEnd":"12:00",
12       "weekdaysSchedule":"123",
13       "deadline": "2029-12-31T16:29:30+0300"
14       },
15    "destAddr":"Номер_Абонента",
16    "message":{
17       "type":"Push",
18       "data":{
19          "externalUserId": "ID_абонента",
20          "text":"Текст уведомления",
21          "serviceNumber":"НОМЕР_ОТПРАВИТЕЛЯ",
22          "ttl":10,
23          "ttlUnit": "SECONDS"
24       }
25    }
26 }

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

Звездочкой (*) отмечены параметры, которые не работают при отправке веб push-сообщений.

Параметр

Обязат.

Тип данных

Описание

login

да

string

Имя Партнера в системе.

password

да

string

Пароль Партнера в системе.

extraParam

нет

string

Дополнительные параметры, передаваемые в виде param1=value1,param2=value2, где:

  • param1 и param2 — названия параметров;

  • value1 и value2 — значения.

Подробнее

Символ запятой в названии параметра использоваться не может, но может входить в его значение — в этом случае он должен удваиваться. Пример: строка место=абзаково,название=гостевой дом-2,координаты=53.8085896,,58.6362112, c=23.02.09,по=05.03.09.

useTimeDiff

нет

boolean

Учитывание часового пояса при запуске рассылки.

Подробнее

Если true, то отправка сообщения осуществляется абоненту согласно расписанию рассылки и его часовому поясу.

Если false, то сообщение отправляется согласно расписанию инициатора рассылки UTC+3, без учёта часового пояса получателя сообщения.

Значение по умолчанию: false.

scheduleInfo

нет

object

Расписание рассылки.

Подробнее

Если не указано, отправляется сразу же, в момент получения запроса.

scheduleInfo/
timeBegin

нет

string

Время начала.

Подробнее

Например, 10:00.

scheduleInfo/
timeEnd

нет

string

Время окончания.

Подробнее

Например, 21:00.

scheduleInfo/
weekdaysSchedule

нет

string

Дни рассылки.

Подробнее

Задаются цифрами от 1 (понедельник) до 7 (воскресенье), например, 12345.

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

scheduleInfo/
deadline

нет

string

Дата окончания рассылки.

Подробнее

Например, 2024-09-10T16:29:30+0300.

id

нет

string

Уникальный идентификатор на стороне Партнёра.

Подробнее

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

Партнёр может вызывать Сервис-провайдера (запрос на отправку сообщения) с одним и тем же id несколько раз. При этом: отправка сообщения абоненту будет выполнена только один раз (по первому запросу).

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

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

shortenLinks

нет

boolean

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

Подробнее

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

  • true — для сокращения ссылок (значение по умолчанию);
  • false — сокращение ссылки не требуется.

Если параметр в запросе не приходит, но при этом сервис Партнёру доступен, то ссылки будут сокращаться по умолчанию.

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

Примечание

Возможность пользоваться данным сервисом предварительно оговаривается и настраивается Сервис-Провайдером.

destAddr

нет

string

Номер телефона абонента.

Подробнее

Для Push-сообщений является обязательным при отсутствии параметра message/data/externalUserId.

Содержит код страны, код оператора и номер телефона.

Для РФ код может быть 8, 7 или +7.

Примеры номеров: 72101234567, +72101234567, 8-210-123-45-6, 82101234567.

message

да

object

Параметры отправляемого сообщения.

message/type

да

enum

Тип сообщения. Передается значение PUSH.

message/data

да

object

Параметры отправляемых данных.
message/data/
externalUserId

нет

string

ID пользователя для отправки Push-сообщения (логин, email, UID).

message/data/ttl

нет

integer

Срок жизни сообщения.

Подробнее

Допустимый диапазон, секунд: от 30 до 86400.

Примечание

При ttl = 0 или отсутствии параметра в запросе берётся значение из настроек по умолчанию, которые задаются при настройке интеграции отдельно для каждого клиента.

Если ttl не указан в данных местах, то запрос будет отклонён системой и будет выведена ошибка.
message/data/
ttlUnit

нет

enum

Единица измерения периода доставки сообщения.

Подробнее

Передается только вместе с ttl.

Допустимые значения:

  • SECONDS;
  • MINUTES;
  • HOURS.
message/data/
serviceNumber

нет

string

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

message/data/text

да

string

Текст отправляемого сообщения.

Подробнее

Количество символов: не более 1000.

Запрос с заголовком title

message/data/title

нет

string

Заголовок для текстового сообщения.

Подробнее

Количество символов: не более 80.

Запрос с признаком главного приложения (primaryOn)
message/data/
primaryOn

нет

boolean

Признак главного приложения, установленного на устройство абонента.

Подробнее

Допустимые значения:

  • true - отправка только на основное устройство пользователя;
  • false - отправка на все устройства пользователя;

Если параметр отсутствует, то передается тоже на все устройства пользователя.

registeredDelivery

нет

integer

Необходимость отчётов о доставке.

Подробнее

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

  • 0 — статусы не нужны;
  • 1 — нужны статусы (по умолчанию);
  • 2 — нужны только статусы НЕ ДОСТАВЛЕНО.

notifyUrl

нет

string

Имя хоста входящего API для получения отчета о доставке (см. Сервис получения статусов доставки сообщений).

Подробнее

Этот параметр в запросе необязательный, но при его отправке нужно учесть следующее:

  • если парметр указан, он не может быть пустым;
  • длина строки notifyUrl не должна превышать 2048 символов.

При невыполнении любого из указанных условий будет сгенерирована ошибка, запрос не будет выполнен.

Запрос с указанием категории содержимого – изображений, HTML-ссылок и кнопок (contentCategory)
message/data/
content

нет

object

Параметры для отправки изображений, HTML-ссылок и кнопок.
message/data/
content/
contentCategory

нет

enum

Категория содержимого по ссылке contentUrl.

Подробнее

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

  • IMAGE — для передачи в contentUrl ссылки на изображение;
  • HTML — для передачи в contentUrl ссылки для перехода. При переходе в Push-сообщение передаваемая ссылка откроется в webView.
message/data/
content/
contentUrl

нет

string

URL-адрес изображения или HTML.

Подробнее

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

Требования к изображению при contentCategory = IMAGE

  • форматы изображения: JPEG, PNG, GIF, BMP;
  • размер изображения: не более 1 МБ;
  • соотношение сторон: 2:1.
Запрос для отображения кнопок (actions)
message/data/
content/actions

нет

array

Массив, в котором передаются кнопки. Описание атрибутов кнопки приведено в таблице ниже.

Подробнее

Кнопки позволяют:

  • открыть сообщение;
  • перейти по заданной ссылке.
message/data/
content/actions/
title

нет

string

Надпись на кнопке.

Подробнее

Количество символов, не более: 64.

message/data/
content/actions/
action

нет

string

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

Подробнее

Определяет действие, которое будет выполняться при клике на кнопку.

Параметр настраивается в мобильном приложении.

Количество символов, не более: 64.

Допустимые значения:

  • open-app (открыть приложение);
  • link (перейти по заданной ссылке).
message/data/
content/actions/
options

нет

string

Дополнительные параметры кнопки.

Подробнее

Набор зависит от ОС, определяется разработчиком мобильного приложения. Параметр настраивается в мобильном приложении.

Количество символов, не более: 300.

В случае кнопки с action = link может быть указан URL-адрес для перехода.

Запрос с подписками (deviceSubscriptions)
message/data/
deviceSubscriptions

нет

array

Передаваемый массив с перечнем подписок мобильного приложения.

Запрос с данными для приложения (customPayload)
message/data/
customPayload

нет

JSON Object

Данные, которые передаются в исходном виде для дальнейшей обработки на уровне клиентского приложения.
Запрос с данными для статистики (callbackData)
message/data/
callbackData

нет

string

Клиентские данные для статистики.

Подробнее

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

Запрос с обогащенными данными (extraOptions)
message/data/
extraOptions

нет

array

Массив объектов дополнительных данных от партнера.

Подробнее

Содержит два обязательных параметра: param_name и param_value.

message/data/
extraOptioparam_name

да

string

Передача признака сообщения.

Подробнее

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

  • RICH — данные для альтернативного варианта отправки данных с контентом для мобильного приложения;
  • LIVE_ACTIVITY — данные для обновления виджета Live Activity на устройствах с операционной системой iOS;
  • SECURE — параметры для передачи чувствительных данных в push-уведомлении.
  • SENDING_PLATFORMS — параметры для передачи push-уведомлений на определенные типы платформ (APNS, FCM, HMS, RuStore).
message/data/
extraOptions/
param_value

да

string

В зависимости от переданного в param_name признака данные в param_value будут отличаться.
param_name=RICH
message/data/
extraOptions/
param_value/title

нет

string

Заголовок сообщения.

Подробнее

Если приходит, то происходит подмена присланного заголовка или задается заголовок вместо пустого.

message/data/
exraOptions/
param_value/message

нет

string

Текст сообщения.

Подробнее

Если приходит в RICH, то происходит подмена присланного текста.

message/data/
extraOptions/
param_value/
content-category

нет

string

Тип контента.

Подробнее

Если приходит, то заменяется вместе с url. Если URL пустой, то content-category игнорируется.

message/data/
extraOptions/
param_value/
content-url

нет

string

Ссылка для контента.

Подробнее

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

message/data/
extraOptions/
param_value/
custom-payload

нет

string

Пользовательские данные.

Подробнее

Если приходит, то заменяют присланные ранее или задаются новые данные, если не было прислано ранее.

message/data/
extraOptions/
param_value/actions

нет

array

Список кнопок.

Подробнее

Если приходят не пустые данные, то происходит замена присланного ранее контента.

param_name=LIVE_ACTIVITY
message/data/
extraOptions/
param_value/aps/
stale_date *

нет

timestamp

timestamp в формате ISO 860 — дата и время, когда Live Activity считается устаревшим.
message/data/
extraOptions/
param_value/aps/
dismissal_date *

нет

timestamp

timestamp в формате ISO 8601 — дата и время, когда Live Activity закрывается на экране блокировки.

Подробнее

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

message/data/
extraOptions/
param_value/aps/
timestamp *

да

timestamp

timestamp в формате ISO 8601.
message/data/
extraOptions/
param_value/aps/
event *

да

string

Событие для обновления Live Activity.

Подробнее

Принимает следующие значения:

  • update (для обновления);
  • end (для деактивации).
message/data/
extraOptions/
param_value/aps/
content_state *

нет

object

Данные, которые будут отображаться в виджете Live Activity.

Подробнее

Параметры передаются разработчиком виджета.

Данный блок не валидируется.

В demo приложении реализовано:

  • deliveryStatus — статус активити:
    • 1 — старт новой активити (при передаче в запросе придет обычное push-уведомление);
    • 2 — обновление запущенной активити с event = update;
    • 3 — завершение запущенной активити с event = end;
  • deliveryTime — время доставки push-уведомления;
  • alert — содержит данные для отображения в виджете (реализуется на стороне мобильного приложения).
param_name=SECURE
message/data/
extraOptions/
param_value

нет

string

Наименования параметров с чувствительными данными (param_name = SECURE).

Подробнее

При отправке через облачных провайдеров чувствительные данные, передаваемые в push-уведомлении, маскируются при помощи шаблонов (подстановки в тексте и заголовке уведомления).

Требования к наименованию параметров с данными для подстановки:

  • текст должен быть на латинице;
  • использование спец. символов недопустимо.

На примере выше (запрос с обогащенными данными SECURE) в тексте и заголовке сообщения указаны переменные %name%, %card% и %data%.

Соответственно, эти значения обязательно должны быть переданы в param_value для дальнейшей подстановки.

param_name=SENDING_PLATFORMS
message/data/
extraOptions/
param_value

нет

string

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

Подробнее

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

  • Android;
  • IOS;
  • Huawei;
  • RuStore;
  • Pwa (для отправки веб push-уведомлений).

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

После отправки сообщения Сервис-провайдер синхронно возвращает ответ. В случае успешной отправки возвращается HTTP-код 200 OK.

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

1  {
2     "mtNum": "7390612217"
3     "id": "8770599"
4  }

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

Для ошибочных результатов HTTP-код ответа будет отличный от 200 OK (см. Коды ошибок отправки).

1 {
2     "error": {
3        "code": 1,
4        "description": "Service is unavailable"
5     }
6 }

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

Код

Описание

HTTP-код

1

Service is unavailable

503

2

Invalid IP-address

403

3

Too many connections

429

4

Invalid request

400

5

Invalid login

401

6

Invalid password

401

7

serviceNumber is not defined

400

8

destAddr is not correct

406

9

Message type is not correct

406

10

Prohibited sending duplicates

409

11

Invalid TTL

406

100

100

500

Статусы доставки push-уведомлений#

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

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

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