Payload 参考

当通过任何非电子邮件渠道（推送、SMS、Telegram、Kakao、LINE、WhatsApp）发送时，Notify 使用的 Payload 消息的参考。

Payload

preset (string): 应用于此消息的 preset 代码。
content (LocalizedContent): 消息内容。与 silent 互斥。
silent (bool): 发送静默（仅数据）推送。与 content 互斥。
custom_data (object): 作为 u 参数转发到客户端 SDK 的自由格式 JSON。
open_action (OpenAction): 用户打开通知时触发的操作。
open_actions (map<Platform, OpenAction>): open_action 的各平台覆盖。键是数字 Platform 枚举值。
voip_push (bool): iOS VoIP 通知。

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`	华为 Android 推送
`baidu_android`	百度 Android 推送
`mac_os`	macOS 推送
`amazon`	亚马逊 (ADM) 推送
`safari`	Safari 网页推送
`chrome`	Chrome 网页推送
`firefox`	Firefox 网页推送
`ie`	Internet Explorer 网页推送
`windows`	Windows 推送 (tile / toast / badge)
`telegram`	Telegram 消息
`kakao`	Kakao 消息
`line`	LINE 消息
`whatsapp`	WhatsApp 消息

通用推送字段

这些字段由 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 条目。

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 的通知会在设备上相互替换。

Android (`android`, `huawei_android`, `baidu_android`)

icon (string): 通知小图标。
banner (string): 大图 URL。
delivery_priority (NORMAL | HIGH): FCM 传递优先级。
vibration (bool): 接收时振动。
led_color (string, hex): 通知 LED 颜色。
icon_background_color (string, hex): 图标背景颜色。
show_on_lockscreen (bool): 在锁屏上显示。
custom_icon (string): 自定义图标的 URL。
priority (NotificationPriority): 托盘内优先级。
group_id (string): 通知组密钥。
collapse_key (string): FCM 折叠密钥。当设备离线时，具有相同 collapse_key 的通知会相互替换。

macOS (`mac_os`)

使用通用推送字段以及 subtitle 和 action（用户点击通知时打开的 URL）。

Amazon (`amazon`)

使用通用推送字段以及 custom_icon 和 priority (NotificationPriority)。

Safari (`safari`)

action (string): 用户点击通知时打开的 URL。
url_arguments (array of string): 替换到 Web Push URL 模板中的 Safari URL 参数。

Chrome (`chrome`)

icon, image (string): 小图标和大图 URL。
duration (duration): 自动关闭计时器。
button_text1 / button_url1、button_text2 / button_url2：最多两个操作按钮。

Firefox (`firefox`)

仅使用 title、body、icon、root_params 和 inbox。

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 字符串化变量。

Kakao (`kakao`)

content (string): 消息内容。
template (string): 已批准的模板代码。
content_variables (string): JSON 字符串化的模板变量绑定。

LINE (`line`)

content (string): 纯文本正文。
template (string): 在 Pushwoosh Control Panel 中配置的 LINE 模板代码（用于发送图片、轮播或 flex 消息）。对于富内容，请在 Control Panel 中预先配置模板并在此处引用。

content 或 template 必须至少设置一个。

WhatsApp (`whatsapp`)

WhatsApp 消息通过 Meta 发送，并受 Meta 的消息规则约束。关键区别在于自由格式文本（仅在用户发送入站消息后打开的 24 小时客户服务窗口内发送）和已批准的模板（用于出站发起和 24 小时窗口外的任何消息）。

content (string): 自由格式消息文本。仅在 24 小时窗口内由 Meta 发送。
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): 映射按钮 URL 占位符的 JSON 对象，以按钮索引为键，例如 "{\"0\":\"https://...\"}"。
header_variables (string): 映射标题占位符的 JSON 对象，以类型为键，例如 "{\"image\":\"https://...\"}"。

content 或 content_id 必须至少设置一个。

SMS

SMS 使用通用消息流。sms 平台块是保留的。通过任何已填写的平台块上的通用 body 字段提供文本。发件人 ID 和其他提供商选项来自应用的 SMS 配置。请参阅 SMS 配置。

OpenAction

定义用户打开消息时执行的操作。

必须且只能是以下之一：

rich_media (RichMedia): 打开一个 Rich Media 页面。
deep_link: 打开一个深度链接：{ "code": "flow-code", "params": { "key": "value" } }。
link (Link): 打开一个 URL。

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

示例：向 segment 发送推送

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)

WhatsApp (whatsapp)

SMS