Справочник по Payload

Справочник по сообщению Payload, используемому Notify при отправке через любой канал, кроме email (push, SMS, Telegram, Kakao, LINE, WhatsApp).

Payload

preset (string): код пресета, применяемый к этому сообщению.
content (LocalizedContent): содержимое сообщения. Взаимоисключающий с silent.
silent (bool): отправить silent push (только с данными). Взаимоисключающий с content.
custom_data (object): произвольный JSON, пересылаемый в SDK клиента в качестве параметра u.
open_action (OpenAction): действие, выполняемое при открытии уведомления пользователем.
open_actions (map<Platform, OpenAction>): переопределение open_action для конкретной платформы. Ключ — числовое значение перечисления Platform.
voip_push (bool): VoIP-уведомление для iOS.

LocalizedContent

Сопоставляет код локали с контентом для каждой платформы. Ключи — это двухбуквенные коды ISO 639-1 (например, "en", "es"), а также специальный ключ "default" для универсального перевода. Исключениями из ISO 639-1 являются "zh-Hant" и "zh-Hans" для традиционного и упрощенного китайского языка.

{
  "localized_content": {
    "default": {
      "ios":     { "title": "Hello", "body": "Tap to view" },
      "android": { "title": "Hello", "body": "Tap to view" }
    },
    "es": {
      "ios":     { "title": "Hola",  "body": "Toca para ver" },
      "android": { "title": "Hola",  "body": "Toca para ver" }
    }
  }
}

Выбор локали для устройства

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

Точное совпадение с языком устройства.
Ключ "default".
Ключ "en".
Любая другая локаль, присутствующая в сопоставлении.

Предоставьте хотя бы один из ключей, "default" или "en", чтобы у каждого устройства был детерминированный запасной вариант. Если вы не предполагаете вариантов для каждой локали, отправляйте только "default".

Каждая запись локали представляет собой объект Content с необязательными блоками для каждой платформы. Заполняйте только те платформы, на которые вы нацелены.

Блок платформы	Канал
`ios`	push для iOS
`android`	push для Android (FCM)
`huawei_android`	push для Huawei Android
`baidu_android`	push для Baidu Android
`mac_os`	push для macOS
`amazon`	push для Amazon (ADM)
`safari`	web push для Safari
`chrome`	web push для Chrome
`firefox`	web push для Firefox
`ie`	web push для Internet Explorer
`windows`	push для Windows (tile / toast / badge)
`telegram`	сообщение Telegram
`kakao`	сообщение Kakao
`line`	сообщение LINE
`whatsapp`	сообщение WhatsApp

Общие поля push-уведомлений

Эти поля являются общими для блоков ios, android, huawei_android, baidu_android, mac_os, amazon, safari, chrome и firefox (поддержка может отличаться. Неиспользуемые поля игнорируются соответствующей платформой).

title (string): заголовок уведомления.
body (string): текст уведомления.
time_to_live (duration, например, "3600s"): как долго push-сервер должен хранить уведомление для устройства, находящегося в офлайне.
sound (string): имя звукового файла.
sound_enabled (bool): включить или отключить звук.
badges (string): количество на значке (iOS) или аналог.
root_params (object): необработанные переопределения полезной нагрузки для конкретной платформы.
inbox (Inbox): запись в Message Inbox.

iOS (`ios`)

subtitle (string): подзаголовок уведомления iOS.
is_critical (bool): критическое оповещение (требует специального разрешения).
attachment (string): URL медиавложения.
thread_id (string): идентификатор потока для сгруппированных уведомлений.
trim_content (bool): обрезать контент, чтобы он поместился.
category_id (string): идентификатор UNNotificationCategory для интерактивных действий.
interruption_level (string): passive, active, time-sensitive или critical.
collapse_id (string): идентификатор сворачивания APNs. Уведомления с одинаковым collapse_id заменяют друг друга на устройстве.

Android (`android`, `huawei_android`, `baidu_android`)

icon (string): маленькая иконка уведомления.
banner (string): URL большого изображения.
delivery_priority (NORMAL | HIGH): приоритет доставки FCM.
vibration (bool): вибрация при получении.
led_color (string, hex): цвет светодиода уведомления.
icon_background_color (string, hex): цвет фона иконки.
show_on_lockscreen (bool): показывать на экране блокировки.
custom_icon (string): URL пользовательской иконки.
priority (NotificationPriority): приоритет в трее уведомлений.
group_id (string): ключ группы уведомлений.
collapse_key (string): ключ сворачивания FCM. Уведомления с одинаковым collapse_key заменяют друг друга, пока устройство находится в офлайне.

macOS (`mac_os`)

Использует общие поля push-уведомлений, а также subtitle и action (URL, открываемый при нажатии на уведомление).

Amazon (`amazon`)

Использует общие поля push-уведомлений, а также custom_icon и priority (NotificationPriority).

Safari (`safari`)

action (string): URL, открываемый при нажатии на уведомление.
url_arguments (array of string): аргументы URL для Safari, подставляемые в шаблон URL для Web Push.

Chrome (`chrome`)

icon, image (string): URL-адреса маленькой иконки и большого изображения.
duration (duration): таймер автоматического закрытия.
button_text1 / button_url1, button_text2 / button_url2: до двух кнопок действий.

Firefox (`firefox`)

Использует только title, body, icon, root_params и inbox.

Windows (`windows`)

Windows использует другую структуру:

{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}

type может быть TILE, TOAST или BADGE.
template (структурированный) или raw ({ "content": "<raw xml>" }) — должен быть указан ровно один.

Telegram (`telegram`)

body (string): текст сообщения.
content_variables (string): переменные в виде JSON-строки для шаблона на стороне бота.

Kakao (`kakao`)

content (string): содержимое сообщения.
template (string): код утвержденного шаблона.
content_variables (string): привязки переменных шаблона в виде JSON-строки.

LINE (`line`)

content (string): простой текст сообщения.
template (string): код шаблона LINE, настроенного в Pushwoosh Control Panel (используется для отправки изображений, каруселей или flex-сообщений). Для rich-контента предварительно настройте шаблон в Control Panel и укажите ссылку на него здесь.

Должно быть установлено хотя бы одно из полей: content или template.

WhatsApp (`whatsapp`)

Сообщения WhatsApp проходят через Meta и подчиняются правилам обмена сообщениями Meta. Ключевое различие заключается между произвольным текстом (доставляется только в течение 24-часового окна обслуживания клиентов, открытого входящим сообщением от пользователя) и утвержденными шаблонами (требуются для инициирования исходящего диалога и для любого сообщения вне 24-часового окна).

content (string): текст сообщения в свободной форме. Доставляется Meta только в течение 24-часового окна.
content_id (string): имя предварительно утвержденного шаблона Meta (например, "hello_world"). Требуется для инициирования исходящего диалога или любого сообщения вне 24-часового окна.
language (string): локаль шаблона, которая должна точно соответствовать локали, утвержденной в Meta (например, "en_US", "en_GB"). Имеет смысл только вместе с content_id. Это не зависит от внешнего ключа LocalizedContent. Внешний ключ выбирает контент для устройства, а language выбирает локаль шаблона Meta для этого контента.
content_variables (string): JSON-объект, сопоставляющий плейсхолдеры в теле сообщения, например, "{\"1\":\"John\"}".
button_url_variables (string): JSON-объект, сопоставляющий плейсхолдеры URL кнопок по индексу кнопки, например, "{\"0\":\"https://...\"}".
header_variables (string): JSON-объект, сопоставляющий плейсхолдеры заголовка по типу, например, "{\"image\":\"https://...\"}".

Должно быть установлено хотя бы одно из полей: content или content_id.

SMS

SMS использует общий поток сообщений. Блок платформы sms зарезервирован. Предоставьте текст через общее поле body в любом заполненном блоке платформы. ID отправителя и другие параметры провайдера берутся из конфигурации SMS приложения. См. Конфигурация SMS.

OpenAction

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

Ровно одно из:

rich_media (RichMedia): открыть страницу Rich Media.
deep_link: открыть deep link: { "code": "flow-code", "params": { "key": "value" } }.
link (Link): открыть URL.

RichMedia

{ "code": "XXXXX-XXXXX" }        // по коду Rich Media
{ "url":  "https://..." }        // по удаленному URL

Link

{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}

shortener может быть NONE (по умолчанию) или BITLY.

Inbox

Настраивает, как сообщение отображается в Message Inbox.

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}

image_url (string): изображение, отображаемое в записи в inbox.
expiration_date (timestamp): когда запись удаляется из inbox.

Перечисление NotificationPriority

Управляет приоритетом уведомлений на целевом устройстве, от PRIORITY_MIN (самый низкий) до PRIORITY_MAX (самый высокий).

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

Пример: Отправка push-уведомления в сегмент

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "title": "Hello",   "body": "Hello, world!" },
              "android": { "title": "Hello",   "body": "Hello, world!" }
            },
            "es": {
              "ios":     { "title": "¡Hola!",  "body": "¡Hola, mundo!" },
              "android": { "title": "¡Hola!",  "body": "¡Hola, mundo!" }
            }
          }
        },
        "open_action": { "link": { "url": "https://example.com/promo" } }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

Пример: Транзакционный push по User ID

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "ios":     { "title": "Your order", "body": "Order #42 has shipped." },
              "android": { "title": "Your order", "body": "Order #42 has shipped." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Справочник по Payload

Payload

LocalizedContent

Выбор локали для устройства

Общие поля push-уведомлений

iOS (ios)

Android (android, huawei_android, baidu_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

WhatsApp (whatsapp)

SMS