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（发送到每个设备）。
control_group	string	应用于此消息的、该次发送专属保留组的代码或名称。它不会缩小适用的对照组范围：无论是否设置此字段，应用中每个已启用的对照组都会将用户排除在营销发送之外。与 holdout_percentage 互斥。
holdout_percentage	uint32	将细分中此比例（1–20）的用户抽取到仅作用于此次发送的对照组中，该对照组叠加在应用已启用的对照组之上，用于衡量单个活动的效果，而不消耗共享的对照组。0（默认）表示不启用。与 control_group 互斥。

重要

Pushwoosh 将该保留组命名为 __holdout_<campaign code>（对于未设置 campaign 的发送，则为 __holdout_<message code>），并在之后每次使用相同代码的发送中按原始比例复用同一个组。抽取结果在该组首次创建时即被固定。此组不会出现在 设置 > 控制组 中，调整其大小、重新抽取、停用或删除它都会返回 FailedPrecondition，因为在衡量过程中更改它会使对比结果失效。

被抽取到保留组中的设备会以与应用的对照组相同的方式被排除在发送之外。这些设备不会收到消息，跟踪日志会将此次丢弃记录为 Device is in control group。message_type 为 MESSAGE_TYPE_TRANSACTIONAL 时会完全跳过此排除，与应用的对照组相同。

同时设置 holdout_percentage 和 control_group，或 holdout_percentage 大于 20 时，会返回 400：

Invalid holdout_percentage

{
  "code": 3,
  "message": "invalid argument",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "holdout_percentage",
          "description": "holdout_percentage and control_group are mutually exclusive"
        }
      ]
    },
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "InvalidHoldoutPercentage",
      "domain": "api.pushwoosh.com",
      "metadata": {}
    }
  ]
}

示例：发送到 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)。如果时间已过，Pushwoosh 会替换为收到请求的时间。当 follow_user_timezone 未设置或为 false 时，这意味着消息会立即发送给所有人。关于 follow_user_timezone: true，请参阅下方的注意事项。最多可设置未来 30 天。
after	duration	at 的替代方案。在“现在”之后经过此偏移量后发送（例如 "3600s"）。最长 30 天。
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 或设置了 best_time_to_send 时有意义。
best_time_to_send	timestamp	可选。仅适用于细分发送。每台设备会在此时间之后 24 小时内各自的最佳时段收到消息。没有最佳时段的设备会按其本地时区，在 at / after 的日期和时间收到消息。请参阅最佳发送时间。

启用 follow_user_timezone 时，过去的发送时间并不会让所有人立即收到

当 follow_user_timezone: true 时，替换后的“现在”仍会被拆分为按设备本地时间划分的时间段，而不是一次性发送到所有设备。落后于 UTC 的时区在本地尚未到达该时刻，因此会在最多 12 小时后收到消息。领先于 UTC 的时区在本地已经过了该时刻，因此会遵循 past_timezones_behaviour：立即发送、跳过（DO_NOT_SEND），或在同一本地时间顺延一天（NEXT_DAY）。同样的拆分也适用于 best_time_to_send 的回退发送。

最佳发送时间

best_time_to_send 是 Control Panel 中最佳时间选项在 API 中的对应参数。at / after 为没有足够数据确定最佳时段的设备设置回退时间。Pushwoosh 取 at / after 的 UTC 日期和时间，并在每台设备本地时区的该日期和时间发送回退消息，与 follow_user_timezone: true 的效果相同。这一行为是隐式应用的：请不要设置 follow_user_timezone，因为设置为 true 会被拒绝并返回 BestTimeToSendWithUserTimezone。在下面的示例中，没有最佳时段的设备会在 5 月 1 日本地时间 18:00 收到消息。如果发送开始时该本地时间已过，则适用 past_timezones_behaviour。

{
  "at": "2026-05-01T18:00:00Z",
  "best_time_to_send": "2026-05-01T00:00:00Z"
}

除非满足以下所有条件，否则 Pushwoosh 会以 400 拒绝请求：

• 请求使用 segment 类型。transactional 发送不支持 best_time_to_send。
• follow_user_timezone 未设置或为 false。
• at / after 指定的发送时间在未来。过去的 at、after: "0s" 或省略 after 都视为“立即发送”，会被拒绝。
• best_time_to_send 不早于下一个整点，且不超过未来 30 天。它会向下取整到整点。
• at / after 指定的发送时间不晚于 best_time_to_send 加 24 小时。

错误的 reason（位于 ErrorInfo 详情中）会指明未通过的检查：

reason	原因
BestTimeToSendWithUserTimezone	follow_user_timezone 为 true。
BestTimeToSendTooEarly	best_time_to_send 早于下一个整点。
BestTimeToSendTooFarInFuture	best_time_to_send 超过未来 30 天。
SendDateAfterBestTimeToSend	at / after 晚于 best_time_to_send 加 24 小时。
BestTimeToSendNotAllowed	在 transactional 发送中设置了 best_time_to_send。
BestTimeToSendWithSendNow	at / after 解析为“立即”（过去的 at 或为零的 after）。

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 迁移