# Справочник по Payload Справочник по сообщению `Payload`, используемому в [`Notify`](/ru/developer/api-reference/messaging-api-v2/notify/) при отправке через любой не-email канал (пуш-уведомления, SMS, Telegram, Kakao, LINE, Viber, WhatsApp). ## Payload - `preset` (string): код [пресета пуш-уведомлений](/ru/product/content/push-presets/) (формат `XXXXX-XXXXX`), который будет применен к этому сообщению. - `sms_preset` (string): код (формат `XXXXX-XXXXX`) сохраненного [SMS-пресета](/ru/product/content/sms-presets/). Его текст для каждой локали подставляется в [`sms.body`](#sms-sms) соответствующей локали. Указанный в запросе `sms.body` для определенной локали переопределяет пресет для этой локали. Пресет должен принадлежать тому же приложению, что и сообщение. - `content` ([`LocalizedContent`](#localizedcontent)): содержимое сообщения. Взаимоисключающий с `silent`. - `silent` (bool): отправить тихое (только с данными) пуш-уведомление. Взаимоисключающий с `content`. - `custom_data` (object): произвольный JSON, пересылаемый в SDK клиента в качестве параметра `u`. - `open_action` ([`OpenAction`](#openaction)): действие, которое срабатывает, когда пользователь открывает уведомление. - `open_actions` (map<Platform, `OpenAction`>): переопределение `open_action` для конкретной платформы. Ключ — это числовое значение перечисления `Platform`. - `voip_push` (bool): VoIP-уведомление для iOS. ```json { "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](https://www.loc.gov/standards/iso639-2/php/code_list.php) (например, `"en"`, `"es"`), а также специальный ключ `"default"` для универсального перевода. Исключениями из ISO 639-1 являются `"zh-Hant"` и `"zh-Hans"` для традиционного и упрощенного китайского. ```json { "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" } } } } ``` ### Выбор локали для устройства Контент, доставляемый на устройство, выбирается в следующем порядке: 1. Точное совпадение с языком устройства. 2. Ключ `"default"`. 3. Ключ `"en"`. 4. Любая другая локаль, присутствующая в сопоставлении. Предоставьте хотя бы один из ключей `"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 (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): необработанные переопределения полезной нагрузки для конкретной платформы. - `inbox` ([`Inbox`](#inbox)): запись в [Message Inbox](/ru/developer/guides/message-inbox/mobile-message-inbox/). ```json { "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` заменяют друг друга на устройстве. ```json { "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`](#notificationpriority-enum)): приоритет в трее. - `group_id` (string): ключ группы уведомлений. - `collapse_key` (string): ключ сворачивания FCM. Уведомления с одинаковым `collapse_key` заменяют друг друга, пока устройство находится в офлайн-режиме. ```json { "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, открываемый при нажатии на уведомление). ```json { "mac_os": { "title": "Hello", "body": "Tap to view", "subtitle": "New update", "action": "https://example.com/promo" } } ``` ## Amazon (`amazon`) Использует общие поля пуш-уведомлений, а также `custom_icon` и `priority` ([`NotificationPriority`](#notificationpriority-enum)). ```json { "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 веб-пуша. ```json { "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`: до двух кнопок действий. ```json { "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`. ```json { "firefox": { "title": "Hello", "body": "Tap to view", "icon": "https://cdn.example.com/icon.png" } } ``` ## Windows (`windows`) Windows использует другую структуру: ```json { "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": "" }`) — ровно один из них. ## Telegram (`telegram`) - `body` (string): текст сообщения. - `content_variables` (string): переменные в виде JSON-строки для шаблона на стороне бота. ```json { "telegram": { "body": "Hello from Pushwoosh", "content_variables": "{\"name\":\"John\"}" } } ``` ## Kakao (`kakao`) - `content` (string): содержимое сообщения. - `template` (string): код утвержденного шаблона. - `content_variables` (string): привязки переменных шаблона в виде JSON-строки. ```json { "kakao": { "content": "Hello from Pushwoosh", "template": "welcome_v1", "content_variables": "{\"name\":\"John\"}" } } ``` ## LINE (`line`) - `content` (string): тело сообщения в виде простого текста. - `template` (string): код шаблона LINE, настроенного в Панели управления Pushwoosh (используется для отправки изображений, каруселей или flex-сообщений). Для rich-контента предварительно настройте шаблон в Панели управления и укажите его здесь. Должно быть установлено хотя бы одно из полей: `content` или `template`. ```json { "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:<телефон>` (E.164), например, `viber:+1234567890`. Простой текст: ```json { "viber": { "body": "Hello from Pushwoosh" } } ``` Транзакционный шаблон: ```json { "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`. ```json { "whatsapp": { "content_id": "hello_world", "language": "en_US", "content_variables": "{\"1\":\"John\"}" } } ``` ## SMS (`sms`) SMS имеет свой собственный блок платформы внутри [`Content`](#localizedcontent) каждой локали, наряду с `ios`, `android` и другими каналами обмена сообщениями. - `body` (string): текст SMS для данной локали. Обязательно, если присутствует блок `sms`. Есть два способа предоставить текст: - **Встроенный** — установите `sms.body` для каждой локали в `localized_content`. - **Из пресета** — установите на уровне payload поле [`sms_preset`](#payload) в код (формат `XXXXX-XXXXX`) сохраненного [SMS-пресета](/ru/product/content/sms-presets/). Его контент для каждой локали подставляется в `sms.body` для каждой локали, которую определяет пресет. Встроенный `sms.body` для локали переопределяет пресет для этой локали, так что вы можете повторно использовать пресет и при этом настраивать отдельные языки. ```json { "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`](#richmedia)): открыть страницу [Rich Media](/ru/product/content/in-apps/). - `deep_link`: открыть диплинк: `{ "code": "flow-code", "params": { "key": "value" } }`. - `link` ([`Link`](#link)): открыть URL. ```json { "open_action": { "deep_link": { "code": "flow-code", "params": { "promo": "summer" } } } } ``` URL диплинка и значения `params` поддерживают синтаксис [персонализации Liquid](/ru/developer/guides/personalization/liquid-templates/) — выражения обрабатываются перед открытием диплинка. ### RichMedia ```json { "code": "XXXXX-XXXXX" } // по коду Rich Media { "url": "https://..." } // по удаленному URL ``` ### Link ```json { "url": "https://example.com/promo", "shortener": "BITLY" } ``` `shortener` может быть `NONE` (по умолчанию) или `BITLY`. ## Inbox Настраивает, как сообщение будет отображаться в Message Inbox. ```json { "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` ## Пример: отправка пуш-уведомления в сегмент ```bash 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 ```bash 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" } }' ```