Справочник по 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): отправить тихое (silent) пуш-уведомление (только с данными). Взаимоисключающий с content.
custom_data (object): произвольный JSON, который пересылается в SDK клиента как параметр u.
open_action (OpenAction): действие, которое выполняется, когда пользователь открывает уведомление.
open_actions (map<Platform, OpenAction>): переопределение open_action для конкретной платформы. Ключ — это числовое значение Platform enum.
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 web push
`chrome`	Chrome web push
`firefox`	Firefox web push
`ie`	Internet Explorer web push
`windows`	Windows push (tile / toast / badge)
`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): “сырые” переопределения payload для конкретной платформы.
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 для Web Push.

{
  "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 присутствует.

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

Встроенный (inline) — установить 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." } }
      }
    }
  }
}

MMS

Добавление subject и file_urls в блок sms превращает сообщение в MMS. Только у AbleMobile есть конечная точка MMS — другие SMS-провайдеры игнорируют оба поля и доставляют только body в виде простого текста.

subject (string): тема MMS. Требует хотя бы одной записи в file_urls — тема без вложений будет отклонена. До 40 ASCII-символов или 13 символов, если тема содержит не-ASCII символы.
file_urls (array of string): до 3 URL-адресов вложений. Каждый должен быть абсолютным https URL, заканчивающимся на .jpg или .gif — .jpeg и .png отклоняются валидацией, даже для подлинного файла JPEG или PNG, потому что провайдер не может их декодировать. Каждый файл также должен быть размером 200 КБ или меньше; AbleMobile отклонит всю отправку, если какое-либо вложение будет тяжелее.
message_at (int): индекс в file_urls (начиная с 0), после которого отображается текст тела SMS.

subject и file_urls поддерживают персонализацию Liquid, так же как и body.

{
  "sms": {
    "body": "Your order has shipped.",
    "subject": "Order update",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

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

URL диплинка и значения params поддерживают синтаксис персонализации Liquid — выражения обрабатываются перед открытием диплинка.

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 enum

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

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

Всегда отправляйте priority как одно из строковых значений выше. API также принимает числовые эквиваленты enum (1-5, в указанном выше порядке), но это сопоставление является внутренней деталью protobuf, а не поддерживаемым контрактом — не полагайтесь на него. Нераспознанное значение priority (строка с опечаткой или число вне диапазона) не отклоняется: API молча отбрасывает его, и уведомление отправляется без поля priority вообще, вместо того чтобы возвращать ошибку.

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

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)

MMS