Messaging API v2 概述

Messaging API v2 是一个单一的 REST/JSON 端点，用于在 Pushwoosh 支持的每个渠道上创建出站消息：

推送：iOS、Android、Huawei、Baidu、macOS、Amazon、Windows、Safari、Chrome、Firefox、IE
电子邮件
短信
Telegram、Kakao、LINE、WhatsApp

渠道通过有效负载类型选择（payload 用于推送/短信/即时通讯，email_payload 用于电子邮件）。

目标通过请求类型选择（segment 用于受众分群，transactional 用于明确的设备或用户列表）。

基本 URL

https://api.pushwoosh.com

如果您使用专用区域或私有部署，请与您的 Pushwoosh 客户成功经理确认确切的基本 URL。

身份验证

每个请求都必须包含一个 Authorization 标头，其中带有服务器端的 Pushwoosh API 访问令牌：

Authorization: Token YOUR_API_TOKEN

请使用您已为服务器到服务器 API 调用颁发的相同令牌。请勿在客户端应用程序中暴露此令牌。

方法

Notify：POST /messaging/v2/notify。创建并发送单条消息（分群或事务性）。

请求和响应格式

内容类型：application/json。
字段名称使用 snake_case。oneof 组以嵌套对象的形式出现，且只设置一个键。
枚举值序列化为其字符串名称（例如，"IOS"、"MESSAGE_TYPE_MARKETING"）。
成功的响应返回 HTTP 200 和 JSON 正文；错误使用标准的 gRPC-Gateway 错误封装 — { "code": ..., "message": ..., "details": [...] }。

快速入门

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 from v2!" },
              "android": { "body": "Hello from v2!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

后续步骤

Notify

有效负载参考

电子邮件有效负载参考

从 v1 迁移