Payload 参考

用于通过任何非电子邮件渠道（推送、SMS、Telegram、Kakao、LINE、Viber、WhatsApp、Facebook Messenger）发送时，Notify 使用的 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)：作为 u 参数转发到客户端 SDK 的自由格式 JSON。
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 推送
`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 消息
`viber`	Viber 消息
`whatsapp`	WhatsApp 消息
`fb_messenger`	Facebook Messenger 消息
`sms`	SMS 消息

通用推送字段

这些字段由 ios、android、huawei_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)：消息收件箱条目。

{
  "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`)

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（结构化）或 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\"}"
  }
}

Facebook Messenger (`fb_messenger`)

Facebook Messenger 消息通过 Meta 发送，并受 Meta 的消息规则约束：自由格式内容仅在用户发送入站消息后打开的 24 小时客户服务窗口内投递。在该窗口之外，需设置 message_tag 为 Meta 批准的用例之一，否则 Meta 会拒绝发送。

body (string)：纯文本消息。Facebook Messenger 不支持模板或按钮，因此这是唯一的内容字段。
message_tag (string)：在 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 都解析为相同的值，即收件人的 Meta 页面范围 ID (PSID)。在 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 (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." } }
      }
    }
  }
}

MMS

向 sms 块添加 subject 和 file_urls 会将消息转换为 MMS。只有 AbleMobile 有 MMS 端点——其他 SMS 提供商会忽略这两个字段，只发送纯文本 body。

subject (string)：MMS 主题。file_urls 中至少需要一个条目——没有附件的主题会被拒绝。最多 40 个 ASCII 字符，如果主题包含非 ASCII 字符，则为 13 个字符。
file_urls (array of string)：最多 3 个附件 URL。每个都必须是绝对的 https URL，以 .jpg 或 .gif 结尾——.jpeg 和 .png 会被验证拒绝，即使是真正的 JPEG 或 PNG 文件，因为提供商无法解码它们。每个文件也必须小于等于 200 KB；如果任何附件过大，AbleMobile 会拒绝整个发送。
message_at (int)：file_urls 中的索引（从 0 开始），SMS 正文文本将显示在该索引之后。

subject 和 file_urls 与 body 一样，支持 Liquid 个性化。

{
  "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)：打开一个富媒体页面。
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" }        // 通过富媒体代码
{ "url":  "https://..." }        // 通过远程 URL

Link

{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}

shortener 是 NONE（默认）或 BITLY。

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

示例：向细分发送推送

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