批量通知

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

在一次调用中发送多条消息。每个项目都是一个独立的 Notify：它的验证方式与独立的 Notify 请求完全相同，并会获得自己的结果。

请求结构

{
  "items": [
    {
      "item_id": "caller-defined-id",
      "request": { ... }
    }
  ]
}

字段	类型	描述
`items`	`NotifyBatchItem` 数组	必需，1 到 500 个条目（服务器配置的限制）。项目并发处理；无论如何，结果都会按请求顺序返回。

NotifyBatchItem

字段	类型	描述
`item_id`	字符串	可选的调用者提供的关联 ID，会在匹配的结果中回显。Pushwoosh 不会以其他方式使用它。
`request`	`NotifyRequest`	与单个 `Notify` 调用的主体相同——包括 `segment` 或 `transactional`、`transaction_id`。必需。

示例

curl -X POST https://api.pushwoosh.com/messaging/v2/notify/batch \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "order-1001",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["user-123"] },
            "payload": {
              "content": {
                "localized_content": {
                  "en": { "ios": { "body": "Your order has shipped." } }
                }
              }
            },
            "schedule": { "at": "2026-05-01T12:00:00Z" },
            "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
            "transaction_id": "order-1001-shipped"
          }
        }
      },
      {
        "item_id": "order-1002",
        "request": {
          "transactional": {
            "application": "XXXXX-XXXXX",
            "platforms": ["IOS", "ANDROID"],
            "users": { "list": ["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",
            "transaction_id": "order-1002-shipped"
          }
        }
      }
    ]
  }'

响应

{
  "results": [
    {
      "item_id": "order-1001",
      "index": 0,
      "result": {
        "message_code": "XXXXX-XXXXX-XXXXX",
        "unknown_identifiers": []
      }
    },
    {
      "item_id": "order-1002",
      "index": 1,
      "error": {
        "code": 3,
        "message": "invalid argument",
        "reason": "EmptySchedule",
        "domain": "api.pushwoosh.com"
      }
    }
  ],
  "succeeded": 1,
  "failed": 1
}

字段	类型	描述
`results`	`NotifyBatchResult` 数组	每个请求的项目对应一个条目，按请求顺序排列。
`succeeded`	整数	返回结果的项目数量。
`failed`	整数	返回错误的项目数量。

NotifyBatchResult

字段	类型	描述
`item_id`	字符串	请求项目的 `item_id` 的回显。
`index`	整数	项目在请求中从零开始的位置。当 `item_id` 为空时，使用此字段来关联结果。
`result`	对象	当项目成功时设置——形状与单个 `Notify` 响应相同：`message_code` 和 `unknown_identifiers`。
`error`	`NotifyBatchError`	当项目失败时设置。

NotifyBatchError

字段	类型	描述
`code`	整数	gRPC 状态码 (`google.rpc.Code`)，例如 `3` 代表 `INVALID_ARGUMENT`。
`message`	字符串	面向开发者的错误消息，为英文。
`reason`	字符串	简短的状态名称——与单个 `Notify` 调用将返回的值相同，例如 `EmptySchedule`。
`domain`	字符串	错误域，`api.pushwoosh.com`。

错误

错误使用标准的 gRPC-Gateway 错误信封：{ "code": ..., "message": ..., "details": [...] }。这些是信封级别的错误，会导致整个请求失败——单个项目失败会在 results[] 中产生一个逐项的 error（请参阅上面的 NotifyBatchError），而不是这些错误之一。

| HTTP 状态 | 条件 | |---|---|---| | 400 | items 为空。 | | 400 | items 的数量超过了服务器配置的限制（默认为 500）。 | | 400 | 其中一个项目缺少 request。 |

示例

当限制为 500 时发送 501 个项目将返回 HTTP 400：

{
  "code": 3,
  "message": "items must not exceed 500 entries, got 501",
  "details": []
}