# Payload 参考

`Payload` 消息的参考，由 [`Notify`](/zh/developer/api-reference/messaging-api-v2/notify/) 在通过任何非电子邮件渠道（推送、SMS、Telegram、Kakao、LINE、Viber、WhatsApp）发送时使用。

<Aside type="note">
对于电子邮件，请参阅 [电子邮件 payload 参考](/zh/developer/api-reference/messaging-api-v2/email-payload-reference/)。
</Aside>

## Payload

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

```json
{
  "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](https://www.loc.gov/standards/iso639-2/php/code_list.php) 双字母代码（例如 `"en"`、`"es"`），外加特殊键 `"default"` 用于包罗万象的翻译。ISO 639-1 的例外是 `"zh-Hant"` 和 `"zh-Hans"`，分别代表繁体和简体中文。

```json
{
  "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" }
    }
  }
}
```

### 设备的区域设置选择

发送到设备的内容按以下顺序选择：

1.  与设备语言完全匹配。
2.  键 `"default"`。
3.  键 `"en"`。
4.  映射中存在的任何其他区域设置。

至少提供 `"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`](#inbox))：[消息收件箱](/zh/developer/guides/message-inbox/mobile-message-inbox/) 条目。

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

```json
{
  "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`](#notificationpriority-enum))：托盘内优先级。
- `group_id` (string)：通知组密钥。
- `collapse_key` (string)：FCM 折叠密钥。当设备离线时，具有相同 `collapse_key` 的通知会相互替换。

```json
{
  "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）。

```json
{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}
```

## Amazon (`amazon`)

使用通用推送字段以及 `custom_icon` 和 `priority` ([`NotificationPriority`](#notificationpriority-enum))。

```json
{
  "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 参数。

```json
{
  "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`：最多两个操作按钮。

```json
{
  "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`。

```json
{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}
```

## Windows (`windows`)

Windows 使用不同的结构：

```json
{
  "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 字符串化变量。

```json
{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}
```

## Kakao (`kakao`)

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

```json
{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}
```

## LINE (`line`)

- `content` (string)：纯文本正文。
- `template` (string)：在 Pushwoosh 控制面板中配置的 LINE 模板代码（用于发送图片、轮播或弹性消息）。对于富内容，请在控制面板中预先配置模板并在此处引用。

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

```json
{
  "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&lt;string, string&gt;)：替换到模板中的键/值绑定，例如 `{ "name": "John", "code": "123456" }`。
- `all_devices` (bool)：`false`（默认）仅发送到用户的主设备；`true` 发送到用户的所有设备。

`body` 或 `template_id` 必须至少设置一个。当设置 `template_id` 时，`template_lang` 是必需的。

将 Viber 收件人地址设为 `viber:<phone>` (E.164) 形式的 hwid，例如 `viber:+1234567890`。

纯文本：

```json
{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}
```

事务性模板：

```json
{
  "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` 必须至少设置一个。

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

## SMS (`sms`)

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

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

有两种方式提供文本：

- **内联** — 在 `localized_content` 中为每个区域设置 `sms.body`。
- **从预设** — 将 payload 级别的 [`sms_preset`](#payload) 设置为已保存的 [SMS 预设](/zh/product/content/sms-presets/) 的代码（格式 `XXXXX-XXXXX`）。其每个区域设置的内容会解析到预设定义的每个区域设置的 `sms.body` 中。一个区域设置的内联 `sms.body` 会覆盖该区域设置的预设，因此您可以重用预设并仍然调整个别语言。

```json
{
  "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`](#richmedia))：打开一个 [富媒体](/zh/product/content/in-apps/) 页面。
- `deep_link`：打开一个深层链接：`{ "code": "flow-code", "params": { "key": "value" } }`。
- `link` ([`Link`](#link))：打开一个 URL。

```json
{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}
```

深层链接 URL 和 `params` 值支持 [Liquid 个性化](/zh/developer/guides/personalization/liquid-templates/) 语法 — 表达式在打开深层链接之前被解析。

### RichMedia


```json
{ "code": "XXXXX-XXXXX" }        // 按富媒体代码
{ "url":  "https://..." }        // 按远程 URL
```

### Link


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

`shortener` 是 `NONE`（默认）或 `BITLY`。

## Inbox

配置消息在消息收件箱中的显示方式。

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

<Aside type="caution">
始终将 `priority` 作为上述字符串值之一发送。API 也接受该枚举的数字等价物（1-5，与上述顺序匹配），但该映射是内部 protobuf 细节，不是受支持的合约 — 不要依赖它。

无法识别的 `priority` 值（拼写错误的字符串或超出范围的数字）不会被拒绝：API 会静默地丢弃它，并且通知会在完全没有 `priority` 字段的情况下发送，而不是返回错误。
</Aside>

## 示例：向一个细分发送推送

```bash
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 发送事务性推送

```bash
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"
    }
  }'
```