Push#

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

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

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

  • заголовок;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметр

Тип данных

Описание

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-67, 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
Hostname входящего 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/extraOptions/ param_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/extraOptions/ 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.

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

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

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

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

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

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

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