Notify 일괄 처리

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

한 번의 호출로 여러 메시지를 보냅니다. 모든 항목은 독립적인 Notify입니다. 독립 실행형 Notify 요청과 똑같이 유효성 검사를 받으며, 자체 결과를 얻습니다.

상태 코드가 아닌 결과를 읽으세요

호출 자체는 일괄 처리 봉투가 유효한 한 HTTP 200을 반환합니다. 모든 단일 항목이 실패하더라도 마찬가지입니다. 실패한 항목이 전체 요청을 실패시키지는 않습니다. 항상 results[]와 succeeded / failed 카운터를 확인하고, 200 응답을 메시지가 전송되었다는 확인으로 간주하지 마십시오.

이것은 더 빠른 전송 방법이 아닙니다

NotifyBatch는 Notify를 직접 호출하는 것보다 메시지를 더 빨리 보내지 않습니다. 통합이 이미 동시에 요청을 발행할 수 있다면, 병렬 스레드/워커에서 Notify를 실행하면 동일한 처리량을 제공합니다. 이는 HTTP/2가 설계상 처리하는 방식입니다. 통합이 동시성을 위해 구축되지 않은 경우, 속도가 아닌 편의를 위해 NotifyBatch를 사용하십시오.

요청 구조

Shape

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

필드	유형	설명
items	NotifyBatchItem 배열	필수, 1~500개 항목(서버 구성 제한). 항목은 동시에 처리되며, 결과는 요청 순서에 관계없이 반환됩니다.

NotifyBatchItem

필드	유형	설명
item_id	string	호출자가 제공하는 선택적 상관관계 ID로, 일치하는 결과에 다시 에코됩니다. 그 외에는 Pushwoosh에서 사용되지 않습니다.
request	NotifyRequest	단일 Notify 호출과 동일한 본문 — segment 또는 transactional, transaction_id 포함. 필수.

각 항목마다 schedule이 여전히 필요합니다

각 항목의 request는 독립 실행형 Notify 호출과 마찬가지로 자체 schedule이 필요합니다. 이를 생략해도 “지금 보내기”로 대체되지 않으며, 항목은 EmptySchedule 오류로 실패합니다.

일괄 재시도는 안전합니다

각 항목의 request에 transaction_id를 설정하십시오. Notify 페이지에 설명된 5분 중복 제거 기간 내에 동일한 transaction_id로 반복 호출하면 해당 항목에 대해 동일한 message_code가 반환됩니다. 따라서 네트워크 오류 후 전체 일괄 처리를 재시도해도 이미 전송된 메시지가 중복되지 않습니다.

예시

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	integer	결과를 반환한 항목 수.
failed	integer	오류를 반환한 항목 수.

NotifyBatchResult

필드	유형	설명
item_id	string	요청 항목 item_id의 에코.
index	integer	요청에서 항목의 0부터 시작하는 위치. item_id가 비어 있을 때 결과를 상호 연관시키는 데 사용합니다.
result	object	항목이 성공했을 때 설정됩니다. 단일 Notify 응답과 동일한 형태: message_code 및 unknown_identifiers.
error	NotifyBatchError	항목이 실패했을 때 설정됩니다.

NotifyBatchError

필드	유형	설명
code	integer	gRPC 상태 코드(google.rpc.Code), 예: INVALID_ARGUMENT의 경우 3.
message	string	개발자 대상 오류 메시지, 영어로 제공됩니다.
reason	string	짧은 상태 이름 — 단일 Notify 호출이 반환하는 것과 동일한 값, 예: EmptySchedule.
domain	string	오류 도메인, 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": []
}

관련 항목

Notify

Cancel

페이로드 참조

Messaging API v2 개요

v1에서 마이그레이션