# 通知
`POST` `https://api.pushwoosh.com/messaging/v2/notify`
创建并计划单条消息。
## 请求结构
请求体是一个 `NotifyRequest`，包含以下两种类型之一：
- [`segment`](#notifysegment)：通过细分代码、[seglang](/zh/developer/api-reference/segmentation-filters-api/segmentation-language/) 表达式或结构化筛选表达式来定位受众细分。
- [`transactional`](#notifytransactional)：发送到明确的 hwid、用户 ID、推送令牌或测试设备列表。
```json title="Shape"
{
"segment": { ... } // 或
"transactional": { ... }
}
```
## NotifySegment
定位与受众细分或筛选表达式匹配的用户。
| 字段 | 类型 | 描述 |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | 发送时间和方式。必需。 |
| `application` | string | [应用程序代码](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `platforms` | array of [`Platform`](#platform-enum) | 消息定位的平台。 |
| `code` | string | [细分代码](/zh/developer/api-reference/api-identifiers/#segment--filter-code)。与 `expression` 和 `filter_expression` 互斥。 |
| `expression` | string | [Seglang](/zh/developer/api-reference/segmentation-filters-api/segmentation-language/) 表达式。 |
| `filter_expression` | `FilterExpression` | 结构化筛选表达式（高级）。 |
| `payload` | [`Payload`](/zh/developer/api-reference/messaging-api-v2/payload-reference/) | 推送 / SMS / Telegram / Kakao / LINE / WhatsApp / Viber 负载。与 `email_payload` 互斥。 |
| `email_payload` | [`EmailPayload`](/zh/developer/api-reference/messaging-api-v2/email-payload-reference/) | 电子邮件负载。 |
| `campaign` | string | 将此消息归属的[活动代码](/zh/developer/api-reference/api-identifiers/#campaign-code)。 |
| `frequency_capping` | [`FrequencyCapping`](#frequencycapping) | 每个用户的频率限制。 |
| `send_rate` | [`SendRate`](#sendrate) | 发送的节流控制。 |
| `message_type` | [`MessageType`](#messagetype-enum) | `MESSAGE_TYPE_MARKETING`（默认）或 `MESSAGE_TYPE_TRANSACTIONAL`。控制对照组筛选。 |
| `dynamic_content_placeholders` | map<string, string> | 替换内容中的占位符。 |
| `meta_data` | object | 转发到下游分析的自由格式元数据。 |
### 示例：发送到细分
```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": { "body": "Hello!" },
"android": { "body": "Hello!" }
}
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_MARKETING"
}
}'
```
## NotifyTransactional
发送到明确的收件人列表。
| 字段 | 类型 | 描述 |
|---|---|---|
| `schedule` | [`Schedule`](#schedule) | 必需。 |
| `application` | string | [应用程序代码](/zh/developer/api-reference/api-identifiers/#application-code)。 |
| `platforms` | array of [`Platform`](#platform-enum) | 消息定位的平台。 |
| `test_devices` | bool | 如果为 `true`，则仅发送到应用的测试设备。 |
| `hwids` | `{ "list": [string, ...] }` | 仅发送到这些 [hwid](/zh/developer/pushwoosh-knowledge-hub/device-identifiers/#hwid)。 |
| `users` | `{ "list": [string, ...] }` | 仅发送到这些[用户 ID](/zh/developer/pushwoosh-knowledge-hub/users-userids/)。 |
| `push_tokens` | `{ "list": [string, ...] }` | 仅发送到这些[推送令牌](/zh/developer/pushwoosh-knowledge-hub/device-identifiers/#push-token)。 |
| `payload` | [`Payload`](/zh/developer/api-reference/messaging-api-v2/payload-reference/) | 推送 / SMS / Telegram / Kakao / LINE / WhatsApp / Viber 负载。 |
| `email_payload` | [`EmailPayload`](/zh/developer/api-reference/messaging-api-v2/email-payload-reference/) | 电子邮件负载。 |
| `return_unknown_identifiers` | bool | 当为 `true` 时，响应的 `unknown_identifiers` 会列出未找到的标识符。 |
| `use_latest_user_device` | bool | 仅在定位 `users` 时适用。当为 `true` 时，消息将发送到每个用户最近活跃的设备——即具有最新“最后应用程序打开时间”的设备——而不是与该用户 ID 关联的所有设备。默认为 `false`（发送到每个设备）。 |
| `campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data` | | 见上文的 `NotifySegment`。 |
`test_devices`、`hwids`、`users` 和 `push_tokens` 是互斥的。必须且只能设置其中一个。
### 示例：通过用户 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": ["user-123", "user-456"] },
"payload": {
"content": {
"localized_content": {
"en": { "ios": { "body": "Your order has shipped." } }
}
}
},
"schedule": { "at": "2026-05-01T12:00:00Z" },
"message_type": "MESSAGE_TYPE_TRANSACTIONAL",
"return_unknown_identifiers": true,
"use_latest_user_device": true
}
}'
```
## 响应
```json
{
"result": {
"message_code": "XXXXX-XXXXX-XXXXX",
"unknown_identifiers": []
}
}
```
| 字段 | 类型 | 描述 |
|---|---|---|
| `message_code` | string | 唯一的[消息代码](/zh/developer/api-reference/api-identifiers/#message-code)。可与 [`/getMessageDetails`](/zh/developer/api-reference/messages-api/#getmessagedetails) 和消息统计端点一起使用。 |
| `unknown_identifiers` | array of string | 在账户上未找到的标识符。仅在 `transactional` 类型中设置了 `return_unknown_identifiers: true` 时填充。 |
## 共享类型
### Schedule
```json
{
"at": "2026-05-01T12:00:00Z",
"follow_user_timezone": true,
"past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}
```
| 字段 | 类型 | 描述 |
|---|---|---|
| `at` | timestamp | 绝对发送时间 (RFC 3339)。如果时间已过，消息将立即发送。最多可设置未来 14 天。 |
| `after` | duration | `at` 的替代方案。在“现在”之后经过此偏移量发送（例如 `"3600s"`）。 |
| `follow_user_timezone` | bool | 当为 `true` 时，每个设备将在其本地时区的 `at` 时间接收消息。 |
| `past_timezones_behaviour` | enum | `PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY`（默认）、`PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND` 或 `PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY`。仅在 `follow_user_timezone` 为 `true` 时有意义。 |
### FrequencyCapping
针对营销发送的每用户频率限制。要禁用限制，请完全省略 `frequency_capping`，或同时发送 `days: 0` 和 `count: 0`。
```json
{ "days": 7, "count": 3, "exclude": false, "avoid": true }
```
- `days`（整数，1–30，或 `0` 以禁用限制）：回溯窗口。必须与 `count` 一起发送——如果其中一个为 `0`，另一个也必须为 `0`；如果一个为 `0` 而另一个非零，则返回 `400`。
- `count`（整数，1 或更高，或 `0` 以禁用限制）：在 `days` 内允许的最大消息数。配对规则同上。
- `exclude`（布尔值）：硬性排除已达到上限的用户。
- `avoid`（布尔值）：软性避免已达到上限的用户（他们仍会计入分析）。
### SendRate
```json
{ "value": 500, "bucket": "1s", "avoid": false }
```
节流发送。`value` 是每个 `bucket` 的消息数；典型的 `bucket` 是 `"1s"`。
### Platform 枚举
`IOS`、`ANDROID`、`OSX`、`WINDOWS`、`AMAZON`、`SAFARI`、`CHROME`、`FIREFOX`、`IE`、`EMAIL`、`BAIDU_ANDROID`、`HUAWEI_ANDROID`、`SMS`、`WEB`、`KAKAO`、`TELEGRAM`、`LINE`、`WHATS_APP`、`VIBER`。
### MessageType 枚举
- `MESSAGE_TYPE_UNSPECIFIED`：等同于 `MESSAGE_TYPE_MARKETING`。
- `MESSAGE_TYPE_MARKETING`：受对照组筛选和频率限制的约束。
- `MESSAGE_TYPE_TRANSACTIONAL`：跳过对照组筛选和频率限制。用于订单确认、一次性密码 (OTP) 和类似的关键流程。
## 相关内容