Payload 参考

本文档是关于 Notify 在通过任何非电子邮件渠道（推送、SMS、Telegram、Kakao、LINE、Viber、WhatsApp）发送消息时使用的 Payload 消息的参考。

Payload

preset (string)：要应用于此消息的推送预设代码（格式为 XXXXX-XXXXX）。
sms_preset (string)：已保存的 SMS 预设的代码（格式为 XXXXX-XXXXX）。其每个区域设置的文本会解析到每个区域设置的 sms.body 中。为给定区域设置指定的内联 sms.body 会覆盖该区域设置的预设。预设必须属于与消息相同的应用程序。
content (LocalizedContent)：消息内容。与 silent 互斥。
silent (bool)：发送静默（仅数据）推送。与 content 互斥。
custom_data (object)：自由格式的 JSON，作为 u 参数转发到客户端 SDK。
open_action (OpenAction)：用户打开通知时触发的操作。
open_actions (map<Platform, OpenAction>)：对 open_action 的分平台覆盖。键是数字 Platform 枚举值。
voip_push (bool)：iOS VoIP 通知。

{
  "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`	华为 Android 推送
`baidu_android`	百度 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, e.g. "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)：通知 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 的通知会相互替换。

{
  "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)：替换到 Web Push URL 模板中的 Safari URL 参数。

{
  "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 (structured) 或 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)：在 Pushwoosh 控制面板中配置的 LINE 模板代码（用于发送图片、轮播或弹性消息）。对于富内容，请在控制面板中预先配置模板并在此处引用。

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

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

Viber (`viber`)

Viber 消息可以是自由文本正文，也可以是通过 id 和语言引用的预批准交易模板 (Omni Messaging / MStat)。

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:<phone> (E.164) 的形式指定 Viber 收件人的 hwid，例如 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)：自由格式消息文本。仅在 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 必须至少设置一个。

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

SMS (`sms`)

SMS 在每个区域设置的 Content 中有自己的平台块，与 ios、android 和其他消息渠道并列。

body (string)：该区域设置的 SMS 文本。当 sms 块存在时必需。

有两种方式提供文本：

内联 — 在 localized_content 中为每个区域设置 sms.body。
从预设 — 将 payload 级别的 sms_preset 设置为已保存的 SMS 预设的代码（格式为 XXXXX-XXXXX）。其每个区域设置的内容会解析到预设定义的每个区域设置的 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." } }
      }
    }
  }
}

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

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 枚举

控制目标设备上的通知优先级，从 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)

Viber (viber)

WhatsApp (whatsapp)

SMS (sms)