Notificar em lote

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

Envia várias mensagens em uma única chamada. Cada item é um Notify independente: é validado exatamente como uma solicitação Notify autônoma e obtém seu próprio resultado.

Leia os resultados, não o código de status

A chamada em si retorna HTTP 200 desde que o envelope do lote seja válido — mesmo que todos os itens individuais falhem. Um item com falha nunca faz com que a solicitação inteira falhe. Sempre verifique results[] e os contadores succeeded / failed; não trate uma resposta 200 como confirmação de que as mensagens foram enviadas.

Esta não é uma maneira mais rápida de enviar

NotifyBatch não envia mensagens mais rápido do que chamar Notify diretamente. Se sua integração já pode emitir solicitações simultaneamente, executar Notify em threads/workers paralelos oferece a mesma taxa de transferência — o HTTP/2 lida com isso por design. Use NotifyBatch por conveniência quando sua integração não for construída para simultaneidade, não por velocidade.

Estrutura da solicitação

Shape

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

Campo	Tipo	Descrição
items	array de NotifyBatchItem	Obrigatório, de 1 a 500 entradas (limite configurado no servidor). Os itens são processados simultaneamente; os resultados retornam na ordem da solicitação, independentemente.

NotifyBatchItem

Campo	Tipo	Descrição
item_id	string	ID de correlação opcional fornecido pelo chamador, retornado no resultado correspondente. Não é usado pela Pushwoosh de outra forma.
request	NotifyRequest	Mesmo corpo de uma chamada Notify única — segment ou transactional, transaction_id incluído. Obrigatório.

schedule ainda é necessário por item

A request de cada item precisa de seu próprio schedule, exatamente como uma chamada Notify autônoma. Omiti-lo não reverte para “enviar agora” — o item falha com um erro EmptySchedule.

Tentar novamente um lote é seguro

Defina transaction_id na request de cada item. Uma chamada repetida com o mesmo transaction_id retorna o mesmo message_code para aquele item dentro da janela de desduplicação de 5 minutos descrita na página Notify — portanto, tentar novamente o lote inteiro após um erro de rede não duplica as mensagens que já foram enviadas.

Exemplo

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"
          }
        }
      }
    ]
  }'

Resposta

{
  "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
}

Campo	Tipo	Descrição
results	array de NotifyBatchResult	Uma entrada por item solicitado, na ordem da solicitação.
succeeded	integer	Contagem de itens que retornaram um resultado.
failed	integer	Contagem de itens que retornaram um erro.

NotifyBatchResult

Campo	Tipo	Descrição
item_id	string	Eco do item_id do item da solicitação.
index	integer	Posição baseada em zero do item na solicitação. Use isso para correlacionar resultados quando item_id foi deixado em branco.
result	object	Definido quando o item é bem-sucedido — mesma forma de uma única resposta Notify: message_code e unknown_identifiers.
error	NotifyBatchError	Definido quando o item falhou.

NotifyBatchError

Campo	Tipo	Descrição
code	integer	Código de status gRPC (google.rpc.Code), por exemplo, 3 para INVALID_ARGUMENT.
message	string	Mensagem de erro voltada para o desenvolvedor, em inglês.
reason	string	Nome de status curto — o mesmo valor que uma chamada Notify única retornaria, por exemplo, EmptySchedule.
domain	string	Domínio do erro, api.pushwoosh.com.

Erros

Os erros usam o envelope de erro padrão do gRPC-Gateway: { "code": ..., "message": ..., "details": [...] }. Estes são erros no nível do envelope que fazem com que a solicitação inteira falhe — um item individual com falha produz um error por item em results[] (veja NotifyBatchError acima), não um destes.

Status HTTP	Condição
400	items está vazio.
400	items tem mais do que o limite configurado no servidor (500 por padrão).
400	Um dos itens está sem request.

Exemplo

Enviar 501 itens quando o limite é 500 retorna HTTP 400:

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

Relacionado

Notify

Cancel

Referência de payload

Visão geral da API de Mensagens v2

Migração da v1