Пакетная отправка уведомлений (Notify batch)

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

Отправляет несколько сообщений за один вызов. Каждый элемент является независимым Notify: он проверяется точно так же, как и отдельный запрос Notify, и получает собственный результат.

Читайте результаты, а не код состояния

Сам вызов возвращает HTTP 200, если пакетная обертка действительна, — даже если каждый отдельный элемент не прошел проверку. Сбой одного элемента никогда не приводит к сбою всего запроса. Всегда проверяйте results[] и счетчики succeeded / failed; не рассматривайте ответ 200 как подтверждение того, что сообщения были отправлены.

Это не более быстрый способ отправки

NotifyBatch не отправляет сообщения быстрее, чем прямой вызов Notify. Если ваша интеграция уже может выполнять запросы одновременно, запуск Notify в параллельных потоках/воркерах обеспечивает ту же пропускную способность — HTTP/2 спроектирован для этого. Используйте NotifyBatch для удобства, когда ваша интеграция не рассчитана на параллелизм, а не для скорости.

Структура запроса

Структура

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

Поле	Тип	Описание
items	array of NotifyBatchItem	Обязательно, от 1 до 500 записей (лимит настраивается на сервере). Элементы обрабатываются одновременно; результаты возвращаются в порядке запроса независимо от этого.

NotifyBatchItem

Поле	Тип	Описание
item_id	string	Необязательный идентификатор корреляции, предоставляемый вызывающей стороной, возвращается в соответствующем результате. В остальном Pushwoosh его не использует.
request	NotifyRequest	Тело запроса такое же, как у одиночного вызова Notify — segment или transactional, включая transaction_id. Обязательно.

schedule по-прежнему требуется для каждого элемента

Каждый request элемента должен иметь свой собственный schedule, точно так же, как и отдельный вызов Notify. Его отсутствие не приводит к отправке “немедленно” — элемент завершится с ошибкой EmptySchedule.

Повторная отправка пакета безопасна

Установите transaction_id для request каждого элемента. Повторный вызов с тем же transaction_id вернет тот же message_code для этого элемента в течение 5-минутного окна дедупликации, описанного на странице Notify, — поэтому повторная отправка всего пакета после сетевой ошибки не приведет к дублированию уже отправленных сообщений.

Пример

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	array of NotifyBatchResult	Одна запись для каждого запрошенного элемента, в порядке запроса.
succeeded	integer	Количество элементов, вернувших результат.
failed	integer	Количество элементов, вернувших ошибку.

NotifyBatchResult

Поле	Тип	Описание
item_id	string	Повторение item_id из элемента запроса.
index	integer	Позиция элемента в запросе, начиная с нуля. Используйте это для сопоставления результатов, если item_id был оставлен пустым.
result	object	Устанавливается, когда элемент обработан успешно — та же структура, что и у ответа на одиночный вызов Notify: message_code и unknown_identifiers.
error	NotifyBatchError	Устанавливается, когда элемент не был обработан.

NotifyBatchError

Поле	Тип	Описание
code	integer	Код состояния gRPC (google.rpc.Code), например, 3 для INVALID_ARGUMENT.
message	string	Сообщение об ошибке для разработчика, на английском языке.
reason	string	Краткое имя состояния — то же значение, которое вернул бы одиночный вызов Notify, например, EmptySchedule.
domain	string	Домен ошибки, api.pushwoosh.com.

Ошибки

Ошибки используют стандартную обертку ошибок gRPC-Gateway: { "code": ..., "message": ..., "details": [...] }. Это ошибки на уровне обертки, которые приводят к сбою всего запроса — сбой отдельного элемента вместо этого создает ошибку error для каждого элемента в results[] (см. NotifyBatchError выше), а не одну из этих.

HTTP-статус	Условие
400	items пуст.
400	items содержит больше записей, чем лимит, настроенный на сервере (по умолчанию 500).
400	В одном из элементов отсутствует request.

Пример

Отправка 501 элемента при лимите в 500 вернет HTTP 400:

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

Связанные материалы

Notify

Cancel

Справочник по Payload

Обзор Messaging API v2

Миграция с v1