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

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

Payload

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

{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}

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`	Пуш-уведомление iOS
`android`	Пуш-уведомление Android (FCM)
`huawei_android`	Пуш-уведомление Huawei Android
`baidu_android`	Пуш-уведомление Baidu Android
`mac_os`	Пуш-уведомление macOS
`amazon`	Пуш-уведомление Amazon (ADM)
`safari`	Веб-пуш Safari
`chrome`	Веб-пуш Chrome
`firefox`	Веб-пуш Firefox
`ie`	Веб-пуш Internet Explorer
`windows`	Пуш-уведомление Windows (плитка / всплывающее / значок)
`telegram`	Сообщение Telegram
`kakao`	Сообщение Kakao
`line`	Сообщение LINE
`viber`	Сообщение Viber
`whatsapp`	Сообщение WhatsApp
`sms`	SMS-сообщение

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

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

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

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}

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 заменяют друг друга на устройстве.

{
  "ios": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}

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 заменяют друг друга, пока устройство находится в офлайне.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}

macOS (`mac_os`)

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

{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}

Amazon (`amazon`)

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

{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}

Safari (`safari`)

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

{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}

Chrome (`chrome`)

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

{
  "chrome": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Open",
    "button_url1": "https://example.com/promo"
  }
}

Firefox (`firefox`)

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

{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}

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-строки для шаблона на стороне бота.

{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}

Kakao (`kakao`)

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

{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}

LINE (`line`)

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

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

{
  "line": {
    "content": "Hello from Pushwoosh",
    "template": "promo_carousel"
  }
}

Viber (`viber`)

Сообщение Viber может быть либо текстом в свободной форме, либо предварительно утвержденным транзакционным шаблоном (Omni Messaging / MStat), на который ссылаются по id и языку.

body (string): простое текстовое сообщение. Обязательно, если template_id не установлен.
template_id (string): id предварительно утвержденного транзакционного шаблона. Если установлен, имеет приоритет над body.
template_lang (string): локаль шаблона. Обязательно, если template_id установлен.
template_params (map<string, string>): привязки ключ/значение, подставляемые в шаблон, например, { "name": "John", "code": "123456" }.
all_devices (bool): false (по умолчанию) доставляет только на основное устройство пользователя; true доставляет на все устройства пользователя.

Должно быть установлено хотя бы одно из полей body или template_id. Если template_id установлен, template_lang является обязательным.

Адресуйте получателей Viber как hwid в формате viber:<phone> (E.164), например viber:+1234567890.

Простой текст:

{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}

Транзакционный шаблон:

{
  "viber": {
    "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe",
    "template_lang": "en",
    "template_params": {
      "name": "John",
      "code": "123456",
      "expires_in": "5 minutes"
    },
    "all_devices": false
  }
}

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.

{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}

SMS (`sms`)

У SMS есть свой собственный блок платформы внутри Content каждой локали, наряду с ios, android и другими каналами обмена сообщениями.

body (string): текст SMS для данной локали. Обязательно, если присутствует блок sms.

Есть два способа предоставить текст:

Встроенный — установите sms.body для каждой локали в localized_content.
Из пресета — установите на уровне payload поле sms_preset в код (формат XXXXX-XXXXX) сохраненного пресета SMS. Его контент для каждой локали подставляется в sms.body для каждой локали, которую определяет пресет. Встроенный sms.body для локали переопределяет пресет для этой локали, так что вы можете повторно использовать пресет и при этом настраивать отдельные языки.

{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Your order has shipped." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}

OpenAction

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

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

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

{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}

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): изображение, отображаемое в записи входящих сообщений.
expiration_date (timestamp): когда запись удаляется из входящих.

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

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

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

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

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"
    }
  }'

Пример: Транзакционное пуш-уведомление по 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

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

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

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)

Viber (viber)

WhatsApp (whatsapp)

SMS (sms)