Notificar en lote

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

Envía varios mensajes en una sola llamada. Cada elemento es una Notify independiente: se valida exactamente igual que una solicitud Notify autónoma y obtiene su propio resultado.

Lee los resultados, no el código de estado

La llamada en sí devuelve HTTP 200 siempre que el sobre del lote sea válido, incluso si cada uno de los elementos ha fallado. Un elemento que falla nunca hace que falle toda la solicitud. Comprueba siempre results[] y los contadores succeeded / failed; no trates una respuesta 200 como una confirmación de que los mensajes se han enviado.

Esta no es una forma más rápida de enviar

NotifyBatch no envía mensajes más rápido que llamar a Notify directamente. Si tu integración ya puede emitir solicitudes de forma concurrente, ejecutar Notify en hilos/workers paralelos proporciona el mismo rendimiento; HTTP/2 lo gestiona por diseño. Usa NotifyBatch por comodidad cuando tu integración no esté diseñada para la concurrencia, no por velocidad.

Estructura de la solicitud

Shape

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

Campo	Tipo	Descripción
items	array de NotifyBatchItem	Requerido, de 1 a 500 entradas (límite configurado por el servidor). Los elementos se procesan de forma concurrente; los resultados se devuelven en el orden de la solicitud independientemente de ello.

NotifyBatchItem

Campo	Tipo	Descripción
item_id	string	ID de correlación opcional proporcionado por el llamante, devuelto en el resultado correspondiente. Pushwoosh no lo utiliza para ningún otro fin.
request	NotifyRequest	Mismo cuerpo que una llamada Notify única — segment o transactional, transaction_id incluido. Requerido.

schedule sigue siendo requerido por elemento

El request de cada elemento necesita su propio schedule, exactamente como una llamada Notify independiente. Omitirlo no recurre a “enviar ahora”; el elemento falla con un error EmptySchedule.

Reintentar un lote es seguro

Establece transaction_id en el request de cada elemento. Una llamada repetida con el mismo transaction_id devuelve el mismo message_code para ese elemento dentro de la ventana de deduplicación de 5 minutos descrita en la página Notify — por lo que reintentar todo el lote después de un error de red no duplica los mensajes que ya se enviaron.

Ejemplo

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

Respuesta

{
  "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	Descripción
results	array de NotifyBatchResult	Una entrada por cada elemento solicitado, en el orden de la solicitud.
succeeded	entero	Número de elementos que devolvieron un resultado.
failed	entero	Número de elementos que devolvieron un error.

NotifyBatchResult

Campo	Tipo	Descripción
item_id	string	Eco del item_id del elemento de la solicitud.
index	entero	Posición del elemento en la solicitud, basada en cero. Úsalo para correlacionar resultados cuando item_id se dejó vacío.
result	objeto	Se establece cuando el elemento tuvo éxito — misma forma que una respuesta Notify única: message_code y unknown_identifiers.
error	NotifyBatchError	Se establece cuando el elemento falló.

NotifyBatchError

Campo	Tipo	Descripción
code	entero	Código de estado gRPC (google.rpc.Code), p. ej. 3 para INVALID_ARGUMENT.
message	string	Mensaje de error para el desarrollador, en inglés.
reason	string	Nombre corto del estado — el mismo valor que devolvería una llamada Notify única, p. ej. EmptySchedule.
domain	string	Dominio del error, api.pushwoosh.com.

Errores

Los errores utilizan el sobre de error estándar de gRPC-Gateway: { "code": ..., "message": ..., "details": [...] }. Estos son errores a nivel de sobre que hacen que falle toda la solicitud; un elemento individual que falla produce un error por elemento en results[] en su lugar (ver NotifyBatchError arriba), no uno de estos.

Estado HTTP	Condición
400	items está vacío.
400	items tiene más del límite configurado por el servidor (500 por defecto).
400	A uno de los elementos le falta request.

Ejemplo

Enviar 501 elementos cuando el límite es 500 devuelve HTTP 400:

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

Relacionado

Notify

Cancel

Referencia de Payload

Visión general de la API de mensajería v2

Migración desde v1