发送通知

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

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

请求结构

请求正文是一个 NotifyRequest，它只有以下两种类型之一：

segment：通过分群代码、seglang 表达式或结构化筛选表达式来定位受众分群。
transactional：发送到明确的 hwid、user ID、push token 或测试设备列表。

{
  "segment": { ... }       // OR
  "transactional": { ... }
}

NotifySegment

定位匹配受众分群或筛选表达式的用户。

字段	类型	描述
`schedule`	`Schedule`	发送时间和方式。必需。
`application`	string	Application code。
`platforms`	array of `Platform`	消息定位的平台。
`code`	string	Segment code。与 `expression` 和 `filter_expression` 互斥。
`expression`	string	Seglang 表达式。
`filter_expression`	`FilterExpression`	结构化筛选表达式（高级）。
`payload`	`Payload`	Push / SMS / Telegram / Kakao payload。与 `email_payload` 互斥。
`email_payload`	`EmailPayload`	Email payload。
`campaign`	string	将此消息归属的 Campaign code。
`frequency_capping`	`FrequencyCapping`	每个用户的频率限制。
`send_rate`	`SendRate`	发送的节流控制。
`message_type`	`MessageType`	`MESSAGE_TYPE_MARKETING` (默认) 或 `MESSAGE_TYPE_TRANSACTIONAL`。控制对照组筛选。
`dynamic_content_placeholders`	map<string, string>	替换内容中的占位符。
`meta_data`	object	转发到下游分析的自由格式元数据。

示例：发送到分群

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`	Push / SMS / Telegram / Kakao payload。
`email_payload`	`EmailPayload`	Email payload。
`return_unknown_identifiers`	bool	当为 `true` 时，响应的 `unknown_identifiers` 会列出未找到的标识符。
`campaign`, `frequency_capping`, `send_rate`, `message_type`, `dynamic_content_placeholders`, `meta_data`		见上文 `NotifySegment`。

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

示例：按 user 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": ["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
    }
  }'

响应

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

针对营销发送的每用户频率限制。

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

days (int, 1–30)：回溯窗口。
count (int)：在 days 内允许的最大消息数。
exclude (bool)：硬性排除已达到上限的用户。
avoid (bool)：软性规避已达到上限的用户（他们仍会计入分析）。

SendRate

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

节流控制发送。value 是每个 bucket 的消息数；典型的 bucket 是 “1s”。

Platform enum

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

MessageType enum

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