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 互斥。如果只想让部分平台静默，请改为在 content 中为 iOS 或 Android 设置 silent。
custom_data (object)：作为 u 参数转发到客户端 SDK 的自由格式 JSON。非常大的整数可能会丢失精度，请参阅自定义数据中的大整数。
custom_data_raw (string)：包含 JSON 对象的字符串，作为 u 参数转发到客户端 SDK。其中的数字会保持精确值。与非空的 custom_data 互斥。无效值会返回 400。
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" } }
  }
}

自定义数据中的大整数

大于 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 通过 PushMessage.getCustomData() 以字符串形式将 u 传递给应用，因此每一位数字都会保留。
Web 推送：Web SDK 使用 JSON.parse 解析 u，而每个 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 推送
`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 消息

按钮

每个语言条目还可以包含 buttons，即在 iOS、Android 和 Huawei 上显示在推送下方的最多 3 个操作按钮。其他平台会忽略它们。按钮需要 iOS SDK 7.2.10 或更高版本并配合 Notification Service Extension，以及 Android SDK 6.17.0 或更高版本。

每个 PushButton 包含以下字段：

id（string）：点击时应用收到的按钮 ID。最多 64 个字符，不含空格，在同一推送中唯一。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）：用于 ACTION_URL 的绝对 http 或 https 地址，或用于 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 (string)：通知标题。
body (string)：通知正文。
time_to_live (duration，例如 "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 的通知会在设备上相互替换。
silent (bool)：将 iOS 推送作为静默（仅数据）推送发送，同一消息中的其他平台仍会收到常规通知。在 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 (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 的通知会相互替换。
silent (bool)：将发往此平台的推送作为静默（仅数据）推送发送，同一消息中的其他平台仍会收到常规通知。在 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 (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 时为必需，除非设置了 image。带有按钮或轮播时为必需。
image (string)：公开的图片 URL。设置 template_id 时会被忽略。
button_caption (string)：按钮文本，最多 30 个字符。需与 button_action 一起设置。需要 body。设置 template_id 时会被忽略。
button_action (string)：按钮链接：http:// 或 https:// URL、viber:// 深层链接，或 Omni 令牌，例如 {lp-100}（由 Omni Messaging 在发送时解析的跟踪链接占位符）。需与 button_caption 一起设置。
carousel (object)：显示在 body 下方的 2–5 张可滑动卡片。不能与 image、button_caption、button_action 或 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、image 或 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
  }
}

轮播

carousel.items 包含 2 到 5 张卡片。如需改为在 journey 中设置轮播，请参阅发送轮播。每张卡片包含以下字段：

title (string)：卡片标题，2–38 个字符。必需。
image (string)：公开的 http:// 或 https:// 图片 URL。必需。
primary_button (object)：主按钮。必需。
secondary_button (object)：第二个按钮。可选。

每个按钮有两个字段，当按钮存在时，两者均为必需：

caption (string)：按钮文本，primary_button 最多 10 个字符，secondary_button 最多 12 个字符。
action (string)：按钮链接：带协议的 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 (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)：纯文本消息。除非设置了 message，否则为必需。
message (string)：以 JSON 字符串形式提供的完整 Meta Send API message 对象，可包含文本、附件、模板或快速回复。设置后，Pushwoosh 会发送它而不是 body。
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
  }
}

RCS

向 sms 块添加 rcs 后，会通过 RCS（Rich Communication Services，富通信服务）发送 Twilio 内容模板，而不是发送 body。Twilio 将模板作为 RCS 消息投递，回退时发送的 SMS 由模板的 twilio/text 类型构建，而不是由 body 构建。没有 twilio/text 类型的模板只能送达支持 RCS 的手机。

rcs.content_sid (string)：Twilio 内容模板的 SID，格式为 HX 后跟 32 个十六进制字符。可以通过 ListRcsTemplates 或 Twilio Console 获取。
rcs.content_variables (string)：序列化为字符串的模板变量 JSON 对象，例如 "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}"。值支持标签和 Liquid 个性化。未提供的变量会使用模板的默认值。

在包含 rcs 的 sms 块中，body 仍然是必填项。

只有当应用通过 Twilio 发送 SMS，并且在 SMS 平台配置中设置了自己的 Account SID、Auth token 和 Messaging Service SID 时，请求才会被接受。使用 Pushwoosh 提供的 Twilio 凭据的应用无法发送 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 返回该应用可通过 RCS 发送的 Twilio 内容模板，使用应用自己的 Twilio 凭据读取。

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

application (string, query)：应用代码，格式为 XXXXX-XXXXX。

响应包含一个 templates 数组。只会列出至少包含一种 RCS 内容类型的模板：twilio/card、twilio/carousel、twilio/quick-reply、twilio/call-to-action 或 twilio/media。

字段	类型	描述
`content_sid`	string	模板 SID，即 `rcs.content_sid` 的值。
`friendly_name`	string	模板在 Twilio 中的名称。
`language`	string	模板语言代码。
`types`	array of string	模板定义的 Twilio 内容类型，例如 `twilio/card` 和 `twilio/text`。
`variables`	object	模板变量及其默认值。
`has_sms_fallback`	boolean	当模板包含 `twilio/text` 类型（即不支持 RCS 的手机收到的 SMS）时为 `true`。

{
  "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`	应用没有自己的 Twilio Account SID 和 Auth token（`FailedPrecondition`）。
`401 Unauthorized`	Twilio 拒绝了应用的凭据（`Unauthenticated`）。
`503 Service Unavailable`	Twilio Content API 返回了其他错误（`Unavailable`）。

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)：条目从收件箱中移除的时间。
expires_in (duration，例如 "604800s")：条目在收件箱中保留的时长，从发送日期起算（即计划的 send_date，立即发送时则为请求时刻）。必须为正值。设置了 expiration_date 时将被忽略。

如需设置相对有效期而非固定日期，请仅发送 expires_in：

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

如果您的账户设置了收件箱最长有效期，超出该期限的 expiration_date 或 expires_in 将被拒绝。

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

RCS