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

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

Payload

preset (строка): код пресета пуш-уведомлений (формат XXXXX-XXXXX), который будет применен к этому сообщению.
sms_preset (строка): код (формат XXXXX-XXXXX) сохраненного пресета SMS. Его текст для каждой локали подставляется в поле sms.body соответствующей локали. Указанный в sms.body текст для определенной локали переопределяет пресет для этой локали. Пресет должен принадлежать тому же приложению, что и сообщение.
content (LocalizedContent): содержимое сообщения. Взаимоисключающий с silent.
silent (логический): отправить тихое (data-only) пуш-уведомление. Взаимоисключающий с content.
custom_data (объект): произвольный JSON, который передается в SDK клиента как параметр u.
open_action (OpenAction): действие, которое выполняется, когда пользователь открывает уведомление.
open_actions (карта<Platform, OpenAction>): переопределение open_action для конкретной платформы. Ключ — это числовое значение перечисления Platform.
voip_push (логический): 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 push
`android`	Android (FCM) push
`huawei_android`	Huawei Android push
`mac_os`	macOS push
`amazon`	Amazon (ADM) push
`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 message
`kakao`	Kakao message
`line`	LINE message
`viber`	Viber message
`whatsapp`	WhatsApp message
`fb_messenger`	Facebook Messenger message
`sms`	SMS message

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

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

title (строка): заголовок уведомления.
body (строка): тело уведомления.
time_to_live (продолжительность, например "3600s"): как долго сервер пуш-уведомлений должен хранить уведомление для устройства, находящегося в офлайне.
sound (строка): имя звукового файла.
sound_enabled (логический): включить или отключить звук.
badges (строка): количество на значке (iOS) или аналог.
root_params (объект): “сырые” переопределения полезной нагрузки для конкретной платформы.
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 (строка): подзаголовок уведомления iOS.
is_critical (логический): критическое оповещение (требует специального разрешения).
attachment (строка): URL медиавложения.
thread_id (строка): идентификатор цепочки для сгруппированных уведомлений.
trim_content (логический): обрезать контент, чтобы он поместился.
category_id (строка): идентификатор UNNotificationCategory для интерактивных действий.
interruption_level (строка): passive, active, time-sensitive или critical.
collapse_id (строка): идентификатор сворачивания 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`)

icon (строка): маленькая иконка уведомления.
banner (строка): URL большого изображения.
delivery_priority (NORMAL | HIGH): приоритет доставки FCM.
vibration (логический): вибрация при получении.
led_color (строка, hex): цвет светодиода уведомления.
icon_background_color (строка, hex): цвет фона иконки.
show_on_lockscreen (логический): показывать на экране блокировки.
custom_icon (строка): URL пользовательской иконки.
priority (NotificationPriority): приоритет в трее уведомлений.
group_id (строка): ключ группировки уведомлений.
collapse_key (строка): ключ сворачивания 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 (строка): URL, открываемый при нажатии на уведомление.
url_arguments (массив строк): аргументы 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 (строка): URL-адреса маленькой иконки и большого изображения.
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 (строка): текст сообщения.
content_variables (строка): переменные в виде JSON-строки для шаблона на стороне бота.

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

Kakao (`kakao`)

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

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

LINE (`line`)

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

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

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

Viber (`viber`)

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

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

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

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

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

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

Facebook Messenger (`fb_messenger`)

Сообщения Facebook Messenger проходят через Meta и подчиняются правилам обмена сообщениями Meta: контент в свободной форме доставляется только в течение 24-часового окна обслуживания клиентов, открытого входящим сообщением от пользователя. Вне этого окна установите message_tag в один из утвержденных Meta вариантов использования, иначе Meta отклонит отправку.

body (строка): сообщение в виде простого текста. Facebook Messenger не поддерживает шаблоны или кнопки, поэтому это единственное поле для контента.
message_tag (строка): требуется вне 24-часового окна. Одно из: CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT.

{
  "fb_messenger": {
    "body": "Hello from Pushwoosh",
    "message_tag": "ACCOUNT_UPDATE"
  }
}

Для этого канала нет отдельного идентификатора устройства: hwid, push_token и user_id разрешаются в одно и то же значение — Page-Scoped ID (PSID) получателя в Meta. Чтобы нацелиться на конкретный диалог, используйте любой из них в NotifyTransactional.

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": ["FB_MESSENGER"],
      "hwids": { "list": ["<recipient-psid>"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "fb_messenger": { "body": "Hello from Pushwoosh" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

SMS (`sms`)

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

body (строка): текст 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." } }
      }
    }
  }
}

MMS

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

subject (строка): тема MMS. Требует хотя бы одной записи в file_urls — тема без вложений будет отклонена. До 40 символов ASCII или 13 символов, если тема содержит не-ASCII символы.
file_urls (массив строк): до 3 URL-адресов вложений. Каждый должен быть абсолютным https URL, заканчивающимся на .jpg или .gif — .jpeg и .png отклоняются валидацией, даже для подлинного файла JPEG или PNG, потому что провайдер не может их декодировать. Каждый файл также должен быть размером 200 КБ или меньше; AbleMobile отклонит всю отправку, если какое-либо вложение будет тяжелее.
message_at (целое число): индекс в 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 (строка): изображение, отображаемое в записи в Message Inbox.
expiration_date (метка времени): когда запись будет удалена из Message Inbox.

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

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

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

Всегда отправляйте priority как одно из строковых значений выше. API также принимает числовые эквиваленты перечисления (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"
    }
  }'

Пример: транзакционный пуш по 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)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

Viber (viber)

WhatsApp (whatsapp)

Facebook Messenger (fb_messenger)

SMS (sms)

MMS