Notify

POST https://api.pushwoosh.com/messaging/v2/notify

创建并计划发送单条消息。

请求结构

请求正文是一个 NotifyRequest，它有两种类型，且只能是其中一种：

• segment：通过 segment code 定位受众 segment，或者在不先创建 segment 的情况下，通过 seglang 表达式或结构化筛选表达式定位。
• transactional：发送到明确的 hwids、user IDs、push tokens 或测试设备列表。

Shape

{
  "segment": { ... },      // OR
  "transactional": { ... },
  "transaction_id": "unique-uuid"
}

字段	类型	描述
transaction_id	string	可选。请求的幂等性密钥——对 segment 和 transactional 都有效。在 5 分钟内使用相同的 transaction_id 重复调用将返回原始的 message_code，而不会发送重复的消息。请为每次逻辑发送使用 UUID 或其他唯一值。

提示

传递一个 X-Request-ID 标头，将创建的消息与您的请求关联起来，以实现端到端追踪——请参阅请求 ID。

只检查密钥，不检查有效负载

去重仅匹配 transaction_id。如果重试时重复使用了相同的 transaction_id，但发送了不同的 segment / transactional 正文，系统仍会返回原始的 message_code，而新的正文将被静默丢弃——系统不会将其与第一个请求进行比较。切勿在逻辑上不同的消息之间重复使用 transaction_id。

提示

这与旧版 Messages API 上的 transactionId 使用相同的去重机制，共享相同的 5 分钟存储窗口，因此重试的请求在 /createMessage 和 Notify 中都会被去重。它与 PW_Conversion 收入事件上的 transaction_id 属性无关，Pushwoosh 会按原样存储该属性，而不会用它来去重。

NotifySegment

定位与受众 segment 或筛选表达式匹配的用户。code、expression 或 filter_expression 中必须设置且只能设置一个。对于 expression 和 filter_expression，无需事先创建 segment——表达式仅为本次发送进行内联评估。

在代码和内联表达式之间进行选择

只有通过 code 引用的已保存 segment 才能使用高速发送预编译。expression 和 filter_expression 在发送时进行评估，并且从不进行预编译。

字段	类型	描述
schedule	Schedule	发送的时间和方式。必需。
application	string	Application code。
platforms	array of Platform	消息定位的平台。
code	string	预先保存的 segment 的 Segment code。与 expression 和 filter_expression 互斥。
expression	string	Seglang 表达式，仅为本次发送进行评估——无需保存 segment。与 code 和 filter_expression 互斥。
filter_expression	FilterExpression	逻辑与 expression 相同，但为结构化对象而非 seglang 字符串。与 code 和 expression 互斥。FilterExpression 模式未公开记录——如果您需要结构化形式，请向 Pushwoosh 支持团队索取。
payload	Payload	推送 / 短信 / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger 的有效负载。与 email_payload 互斥。
email_payload	EmailPayload	电子邮件有效负载。
campaign	string	将此消息归因于的 Campaign code。
campaign_name	string	此消息的内部名称，作为 Message History 及其导出中的行标题显示。与上面的 campaign 无关，不会对消息分组或影响投递。最多 255 个字符，会被裁剪。省略此字段或留空，则行标题取自负载本身的内容。
frequency_capping	FrequencyCapping	每用户的频率限制。
send_rate	SendRate	发送的节流。
message_type	MessageType	MESSAGE_TYPE_MARKETING（默认）或 MESSAGE_TYPE_TRANSACTIONAL。控制对照组筛选。
dynamic_content_placeholders	map<string, string>	替换内容中的占位符。
meta_data	object	转发到下游分析的自由格式元数据。
use_latest_user_device	bool	当为 true 时，将消息发送到每个用户最近活跃的设备（即具有最新“最后应用打开时间”的设备），而不是发送到 segment 匹配的每个设备。范围限定于 platforms：只考虑这些平台上的设备，如果没有设备有“最后应用打开时间”数据，则使用第一个匹配的设备，而不是放弃发送。默认为 false（发送到每个设备）。

示例：发送到 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":     { "body": "Hello!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

发送到明确的收件人列表。

字段	类型	描述
schedule	Schedule	必需。
application	string	Application code。
platforms	array of Platform	消息定位的平台。
test_devices	bool	如果为 true，则仅发送到应用的测试设备。
hwids	{ "list": [string, ...] }	仅发送到这些 hwids。
users	{ "list": [string, ...] }	仅发送到这些 user IDs。
push_tokens	{ "list": [string, ...] }	仅发送到这些 push tokens。
payload	Payload	推送 / 短信 / Telegram / Kakao / LINE / WhatsApp / Viber / Facebook Messenger 的有效负载。
email_payload	EmailPayload	电子邮件有效负载。
return_unknown_identifiers	bool	当为 true 时，响应的 unknown_identifiers 会列出未找到的标识符。
use_latest_user_device	bool	仅在定位 users 时适用。行为与上面的 NotifySegment 中相同——每个用户发送一条消息，而不是每个设备一条，范围限定于 platforms。默认为 false。
campaign, campaign_name, frequency_capping, send_rate, message_type, dynamic_content_placeholders, meta_data		请参阅上面的 NotifySegment。

test_devices、hwids、users 和 push_tokens 是互斥的。必须设置且只能设置一个。

示例：按 user IDs 进行事务性发送

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

响应

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

字段	类型	描述
message_code	string	唯一的 message code。可与 /getMessageDetails 和消息统计端点一起使用。
unknown_identifiers	array of string	在账户上未找到的标识符。仅当在 transactional 类型上设置了 return_unknown_identifiers: true 时才会填充。

共享类型

Schedule

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

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days（整数，1–30，或 0 表示禁用限制）：回溯窗口。必须与 count 一起发送——如果其中一个为 0，另一个也必须为 0；如果一个为 0 而另一个非零，则返回 400。
• count（整数，1 或更高，或 0 表示禁用限制）：在 days 内允许的最大消息数。配对规则与上面的 days 相同。
• exclude（布尔值）：硬性排除已达到上限的用户。
• avoid（布尔值）：软性避开已达到上限的用户（他们仍会计入分析）。

重要

发送 days 和 count 时，如果零值不匹配（例如 {"days": 0, "count": 5}），将返回 400。此验证是对 Notify 的一项重大变更——之前依赖于单个 0 会被静默忽略的客户端现在将收到错误。

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

节流发送。value 是每个 bucket 的消息数；典型的 bucket 是 "1s"。

Platform 枚举

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP, VIBER, FB_MESSENGER。

MessageType 枚举

• MESSAGE_TYPE_UNSPECIFIED：等同于 MESSAGE_TYPE_MARKETING。
• MESSAGE_TYPE_MARKETING：受对照组筛选和频率限制的约束。
• MESSAGE_TYPE_TRANSACTIONAL：跳过对照组筛选和频率限制。用于订单确认、一次性密码 (OTP) 和类似的关​​键流程。

相关

Notify 批量

取消

有效负载参考

电子邮件有效负载参考

从 v1 迁移