# Messaging API v2 概述

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

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

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

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

## 基本 URL

```
https://api.pushwoosh.com
```

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

## 身份验证

每个请求都必须包含一个 `Authorization` 标头，其中包含一个服务器端的 Pushwoosh [API 访问令牌](/zh/developer/api-reference/api-access-token/#server-api-token)：

```
Authorization: Token YOUR_API_TOKEN
```

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

## 方法

- [`Notify`](/zh/developer/api-reference/messaging-api-v2/notify/)：`POST /messaging/v2/notify`。创建并发送单条消息（分群或事务性）。
- [`Cancel`](/zh/developer/api-reference/messaging-api-v2/cancel/)：`POST /messaging/v2/cancel`。取消先前创建但尚未送达的消息。
- [`Update`](/zh/developer/api-reference/messaging-api-v2/update/)：`POST /messaging/v2/update`。用新的定义替换仍在计划中的消息。

## 请求和响应格式

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

## 快速入门

```bash title="向分群发送推送"
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"
    }
  }'
```

## 通过 SMTP 发送电子邮件

如果一个服务已经支持 SMTP，您可以通过 [SMTP 网关](/zh/developer/api-reference/smtp-gateway/) 提交事务性电子邮件，而不是直接调用 `Notify`。网关会将每条消息作为事务性 `Notify` 转发到此 API，因此适用相同的身份验证和电子邮件有效负载规则。

## 后续步骤

<CardGrid>
  <LinkCard title="通知" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="取消" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="更新" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="有效负载参考" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="电子邮件有效负载参考" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="SMTP 网关" href="/developer/api-reference/smtp-gateway/" />
  <LinkCard title="从 v1 迁移" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>