Notify-Batch

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

Sendet mehrere Nachrichten in einem einzigen Aufruf. Jedes Element ist ein unabhängiges Notify: Es wird genau wie eine eigenständige Notify-Anfrage validiert und erhält ein eigenes Ergebnis.

Lesen Sie die Ergebnisse, nicht den Statuscode

Der Aufruf selbst gibt HTTP 200 zurück, solange der Batch-Umschlag gültig ist – auch wenn jedes einzelne Element fehlgeschlagen ist. Ein fehlerhaftes Element führt niemals zum Scheitern der gesamten Anfrage. Überprüfen Sie immer results[] und die Zähler succeeded / failed; behandeln Sie eine 200-Antwort nicht als Bestätigung, dass Nachrichten gesendet wurden.

Dies ist keine schnellere Methode zum Senden

NotifyBatch sendet Nachrichten nicht schneller als der direkte Aufruf von Notify. Wenn Ihre Integration bereits Anfragen gleichzeitig ausführen kann, bietet die Ausführung von Notify in parallelen Threads/Workern den gleichen Durchsatz – HTTP/2 ist dafür konzipiert. Verwenden Sie NotifyBatch aus Bequemlichkeit, wenn Ihre Integration nicht für Gleichzeitigkeit ausgelegt ist, nicht für Geschwindigkeit.

Anfragestruktur

Shape

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

Feld	Typ	Beschreibung
items	Array von NotifyBatchItem	Erforderlich, 1 bis 500 Einträge (serverkonfiguriertes Limit). Elemente werden gleichzeitig verarbeitet; die Ergebnisse werden unabhängig davon in der Reihenfolge der Anfrage zurückgegeben.

NotifyBatchItem

Feld	Typ	Beschreibung
item_id	string	Optionale, vom Aufrufer bereitgestellte Korrelations-ID, die im passenden Ergebnis zurückgegeben wird. Wird von Pushwoosh ansonsten nicht verwendet.
request	NotifyRequest	Gleicher Body wie bei einem einzelnen Notify-Aufruf – segment oder transactional, transaction_id eingeschlossen. Erforderlich.

schedule ist weiterhin pro Element erforderlich

Die request jedes Elements benötigt einen eigenen schedule, genau wie ein eigenständiger Notify-Aufruf. Das Weglassen führt nicht zu einem Fallback auf “jetzt senden” – das Element schlägt mit einem EmptySchedule-Fehler fehl.

Ein erneuter Versuch eines Batches ist sicher

Setzen Sie transaction_id für die request jedes Elements. Ein wiederholter Aufruf mit derselben transaction_id gibt denselben message_code für dieses Element innerhalb des 5-minütigen Deduplizierungsfensters zurück, das auf der Notify-Seite beschrieben ist – so werden bei einem erneuten Versuch des gesamten Batches nach einem Netzwerkfehler die bereits versendeten Nachrichten nicht dupliziert.

Beispiel

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

Antwort

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

Feld	Typ	Beschreibung
results	Array von NotifyBatchResult	Ein Eintrag pro angefordertem Element, in der Reihenfolge der Anfrage.
succeeded	integer	Anzahl der Elemente, die ein Ergebnis zurückgegeben haben.
failed	integer	Anzahl der Elemente, die einen Fehler zurückgegeben haben.

NotifyBatchResult

Feld	Typ	Beschreibung
item_id	string	Echo der item_id des Anfrageelements.
index	integer	Nullbasierte Position des Elements in der Anfrage. Verwenden Sie dies, um Ergebnisse zu korrelieren, wenn item_id leer gelassen wurde.
result	object	Wird gesetzt, wenn das Element erfolgreich war – gleiche Form wie eine einzelne Notify-Antwort: message_code und unknown_identifiers.
error	NotifyBatchError	Wird gesetzt, wenn das Element fehlgeschlagen ist.

NotifyBatchError

Feld	Typ	Beschreibung
code	integer	gRPC-Statuscode (google.rpc.Code), z. B. 3 für INVALID_ARGUMENT.
message	string	Entwicklerorientierte Fehlermeldung, auf Englisch.
reason	string	Kurzer Statusname – derselbe Wert, den ein einzelner Notify-Aufruf zurückgeben würde, z. B. EmptySchedule.
domain	string	Fehlerdomäne, api.pushwoosh.com.

Fehler

Fehler verwenden den Standard-gRPC-Gateway-Fehlerumschlag: { "code": ..., "message": ..., "details": [...] }. Dies sind Fehler auf Umschlag-Ebene, die die gesamte Anfrage fehlschlagen lassen – ein einzelnes fehlerhaftes Element erzeugt stattdessen einen error pro Element in results[] (siehe NotifyBatchError oben), nicht einen von diesen.

HTTP-Status	Bedingung
400	items ist leer.
400	items hat mehr als das serverkonfigurierte Limit (standardmäßig 500).
400	Bei einem der Elemente fehlt request.

Beispiel

Das Senden von 501 Elementen, wenn das Limit 500 beträgt, gibt HTTP 400 zurück:

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

Verwandte Themen

Notify

Cancel

Payload-Referenz

Übersicht zur Messaging API v2

Migration von v1