Справочник по 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. Чтобы сделать тихими только некоторые платформы, вместо этого задайте silent внутри content для iOS или Android.
custom_data (объект): произвольный JSON, который передается в SDK клиента как параметр u. Очень большие целые числа могут потерять точность, см. Большие целые числа в пользовательских данных.
custom_data_raw (строка): строка, содержащая JSON-объект, которая передается в SDK клиента как параметр u. Числа в ней сохраняют точное значение. Взаимоисключающий с непустым custom_data. Недопустимое значение возвращает 400.
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" } }
  }
}

Большие целые числа в пользовательских данных

Целые числа больше 9007199254740992 теряют точность в custom_data. Чтобы сохранить их точными, используйте custom_data_raw.

custom_data — это google.protobuf.Struct (универсальный JSON-подобный объект). Он хранит каждое число как double — 64-битное число с плавающей точкой, которое точно представляет целые числа только до 9007199254740992. Бо́льшие целые числа округляются: 5190090000030465245 приходит на устройство как 5190090000030465000. Строки это не затрагивает.

Чтобы сохранить такие целые числа точными, передайте в custom_data_raw строку, содержащую JSON-объект:

{ "payload": { "silent": true, "custom_data_raw": "{\"pushUID\": 5190090000030465245}" } }

Правила для custom_data_raw:

Строка должна содержать JSON-объект. Массив, строка, null или невалидный JSON возвращают 400 (INVALID_ARGUMENT) с нарушением в поле payload.custom_data_raw.
Если в custom_data есть хотя бы один ключ и при этом задан custom_data_raw, запрос возвращает 400. Пустой объект custom_data игнорируется.
Как и custom_data, это поле заменяет пользовательские данные, сохраненные в пресете пуш-уведомлений preset.
Перед доставкой объект преобразуется обратно в текст JSON. Порядок ключей не сохраняется, пробелы удаляются. Числа сохраняют точное значение, но исходный текст не сохраняется байт в байт.
В /messaging/v2/notify/batch недопустимый custom_data_raw приводит к ошибке только своего элемента. Остальные элементы отправляются.

Как отправляется запрос:

REST: для /messaging/v2/notify и /messaging/v2/notify/batch ничего менять не нужно. Если custom_data содержит целое число, которое double не может представить точно, API автоматически сохраняет его без потерь. При этом custom_data_raw по-прежнему можно задать явно.
gRPC: клиент сам формирует Struct, поэтому точность теряется еще до отправки запроса. Заполняйте custom_data_raw вместо custom_data.

Куда доставляется уведомление:

Android: SDK передает u в приложение как строку через PushMessage.getCustomData(), поэтому все цифры сохраняются.
Веб-пуш: Web SDK разбирает u с помощью JSON.parse, а любое число в JavaScript — это double. Большие целые числа округляются в браузере независимо от API, поэтому передавайте их как строки.
Windows: toast-уведомление получает те же данные u, что и другие платформы, а целые числа, отправленные через custom_data_raw, приходят точными.

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

Кнопки

Каждая языковая запись может также содержать buttons — до 3 кнопок действий, которые отображаются под push-уведомлением на iOS, Android и Huawei. Другие платформы их игнорируют. Для кнопок нужен iOS SDK 7.2.10 или новее с Notification Service Extension и Android SDK 6.17.0 или новее.

Каждый PushButton содержит следующие поля:

id (string): ID кнопки, который приложение получает при нажатии. До 64 символов, без пробелов, уникален в пределах push-уведомления. Обязателен для ACTION_OPEN и ACTION_CUSTOM. Если не указать его для других действий, Pushwoosh задаёт btn_1, btn_2 и так далее.
label (string): текст кнопки, от 1 до 64 символов.
action (enum): ACTION_OPEN открывает приложение, ACTION_URL открывает url, ACTION_DEEPLINK открывает диплинк, ACTION_CUSTOM передаёт id в приложение, и приложение обрабатывает его само.
url (string): абсолютный адрес http или https для ACTION_URL или диплинк со схемой для ACTION_DEEPLINK.
platform_urls (map): диплинк для каждой платформы для ACTION_DEEPLINK с кодом платформы в качестве ключа: 1 iOS, 3 Android, 17 Huawei.
style (enum): STYLE_DEFAULT или STYLE_DESTRUCTIVE. Деструктивный стиль показывает кнопку красной на iOS.

{
  "localized_content": {
    "default": {
      "ios": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "android": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "buttons": [
        { "id": "track", "label": "Track order", "action": "ACTION_DEEPLINK", "url": "myapp://orders/42" },
        { "id": "cancel", "label": "Cancel order", "action": "ACTION_CUSTOM", "style": "STYLE_DESTRUCTIVE" }
      ]
    }
  }
}

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

Эти поля являются общими для блоков 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 заменяют друг друга на устройстве.
silent (логический): отправить iOS-пуш как тихий (data-only), при этом другие платформы в том же сообщении получат обычное уведомление. Задается внутри content, поэтому работает вместе с ним. Чтобы сделать тихими все платформы, вместо этого используйте silent верхнего уровня, который заменяет content. Достаточно задать его в любой локали, чтобы он применился ко всем локалям.

{
  "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 заменяют друг друга, пока устройство находится в офлайне.
silent (логический): отправить пуш на эту платформу как тихий (data-only), при этом другие платформы в том же сообщении получат обычное уведомление. Задается внутри content, поэтому работает вместе с ним. Чтобы сделать тихими все платформы, вместо этого используйте silent верхнего уровня, который заменяет content. Достаточно задать его в любой локали, чтобы он применился ко всем локалям. Блок baidu_android тоже принимает silent с тем же поведением.

{
  "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 не установлен, кроме случая, когда установлен image. Обязательно при наличии кнопки или карусели.
image (строка): публичный URL изображения. Игнорируется, если template_id установлен.
button_caption (строка): текст кнопки, до 30 символов. Устанавливается вместе с button_action. Требует body. Игнорируется, если template_id установлен.
button_action (строка): ссылка кнопки: URL http:// или https://, диплинк viber:// или токен Omni, например {lp-100} (плейсхолдер трекинговой ссылки, который Omni Messaging подставляет в момент отправки). Устанавливается вместе с button_caption.
carousel (объект): от 2 до 5 пролистываемых карточек, которые показываются под body. Нельзя сочетать с image, button_caption, button_action или template_id. См. Карусель.
template_id (строка): id предварительно утвержденного транзакционного шаблона. Если установлен, имеет приоритет над body.
template_lang (строка): локаль шаблона. Обязательно, если template_id установлен.
template_params (карта<string, string>): привязки ключ/значение, подставляемые в шаблон, например { "name": "John", "code": "123456" }.
all_devices (логический): false (по умолчанию) доставляет сообщение только на основное устройство пользователя; true доставляет на все устройства пользователя.

Должно быть установлено хотя бы одно из полей: body, image или 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
  }
}

Карусель

carousel.items содержит от 2 до 5 карточек. Чтобы вместо этого настроить карусель в journey, см. Отправка карусели. У каждой карточки есть такие поля:

title (строка): заголовок карточки, от 2 до 38 символов. Обязательно.
image (строка): публичный URL изображения http:// или https://. Обязательно.
primary_button (объект): основная кнопка. Обязательно.
secondary_button (объект): вторая кнопка. Необязательно.

У каждой кнопки два поля, и оба обязательны, если кнопка задана:

caption (строка): текст кнопки, до 10 символов для primary_button и до 12 для secondary_button.
action (строка): ссылка кнопки: URL со схемой (http://, https://, viber://) или токен Omni, например {lp-100}, — те же значения, что и для button_action.

Запрос, нарушающий любое из этих правил, отклоняется с ошибкой INVALID_ARGUMENT. В деталях google.rpc.BadRequest указывается поле, например viber.carousel.items[0].title.

Пример:

{
  "viber": {
    "body": "New arrivals are in. Swipe to see them.",
    "carousel": {
      "items": [
        {
          "title": "Running shoes",
          "image": "https://example.com/img/shoes.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/shoes" },
          "secondary_button": { "caption": "Details", "action": "{lp-100}" }
        },
        {
          "title": "Sports backpack",
          "image": "https://example.com/img/backpack.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/backpack" }
        }
      ]
    }
  }
}

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 (строка): сообщение в виде простого текста. Обязательно, если не задано message.
message (строка): полный объект message из Meta Send API в виде JSON-строки — с текстом, вложениями, шаблонами или быстрыми ответами. Если поле задано, Pushwoosh отправляет его вместо body.
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
  }
}

RCS

Добавление rcs в блок sms отправляет шаблон контента Twilio через RCS (Rich Communication Services) вместо body. Twilio доставляет шаблон как RCS-сообщение, а в качестве резервного варианта отправляет SMS, собранное из типа twilio/text шаблона, а не из body. Шаблон без типа twilio/text доходит только до телефонов с поддержкой RCS.

rcs.content_sid (строка): SID шаблона контента Twilio — HX и 32 шестнадцатеричных символа. Его можно получить через ListRcsTemplates или в Twilio Console.
rcs.content_variables (строка): JSON-объект с переменными шаблона, сериализованный в строку, например "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}". Значения поддерживают теги и персонализацию с помощью Liquid. Пропущенная переменная принимает значение по умолчанию из шаблона.

body по-прежнему обязателен в блоке sms с rcs.

Запрос отклоняется, если приложение не отправляет SMS через Twilio с собственными Account SID, Auth token и Messaging Service SID, заданными в конфигурации платформы SMS. Приложение, работающее на учетных данных Twilio от Pushwoosh, не может отправлять RCS.

Пресет SMS может содержать шаблон для каждой локали. Если в payload указан sms_preset, шаблон из пресета используется для всех локалей, для которых запрос не передает собственный rcs.content_sid.

{
  "sms": {
    "body": "Your order has shipped.",
    "rcs": {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "content_variables": "{\"1\": \"{FirstName|CapitalizeFirst|there}\", \"2\": \"A-1042\"}"
    }
  }
}

Список шаблонов RCS

ListRcsTemplates возвращает шаблоны контента Twilio приложения, которые можно отправить через RCS. Шаблоны считываются с помощью собственных учетных данных Twilio приложения.

GET https://rpc-api.svc-nue.pushwoosh.com/api/sms_presets:rcs_templates?application=XXXXX-XXXXX
Authorization: Api YOUR_API_TOKEN

application (строка, query): код приложения, формат XXXXX-XXXXX.

Ответ содержит массив templates. В него попадают только шаблоны, у которых есть хотя бы один тип контента RCS: twilio/card, twilio/carousel, twilio/quick-reply, twilio/call-to-action или twilio/media.

Поле	Тип	Описание
`content_sid`	строка	SID шаблона — значение для `rcs.content_sid`.
`friendly_name`	строка	Название шаблона в Twilio.
`language`	строка	Код языка шаблона.
`types`	массив строк	Типы контента Twilio, определенные в шаблоне, например `twilio/card` и `twilio/text`.
`variables`	объект	Переменные шаблона с их значениями по умолчанию.
`has_sms_fallback`	логический	`true`, если у шаблона есть тип `twilio/text` — SMS, которое получает телефон без RCS.

{
  "templates": [
    {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "friendly_name": "order_shipped_card",
      "language": "en",
      "types": ["twilio/card", "twilio/text"],
      "variables": { "1": "there", "2": "your order" },
      "has_sms_fallback": true
    }
  ]
}

ListRcsTemplates возвращает следующие ошибки:

HTTP-статус	Причина
`400 Bad Request`	У приложения нет собственных Account SID и Auth token Twilio (`FailedPrecondition`).
`401 Unauthorized`	Twilio отклонил учетные данные приложения (`Unauthenticated`).
`503 Service Unavailable`	Twilio Content API вернул другую ошибку (`Unavailable`).

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.
expires_in (продолжительность, например "604800s"): как долго запись хранится в Message Inbox, считая от даты отправки (запланированной send_date или момента запроса при немедленной отправке). Должна быть положительной. Игнорируется, если задана expiration_date.

Чтобы задать относительный срок хранения вместо фиксированной даты, передайте только expires_in:

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expires_in": "604800s"
}

Если для вашего аккаунта задан максимальный срок хранения записей в Message Inbox, expiration_date или expires_in за его пределами отклоняется.

Перечисление 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)