Batch-Einzel-Push-API

Batch-Push-API

Funktionsbeschreibung

Mit der Batch-Push-API können Sie Nachrichten an mehrere Zielnutzer:innen in einem einzigen Aufruf versenden. Unterstützt wird das Pushen per registration_id oder alias:

Push per registration_id: POST /v4/batch/push/regid
Push per alias: POST /v4/batch/push/alias
Kapazitätsgrenzen:
- Maximal 500 Push-Ziele pro Anfrage
- Unterstützt parallele Verarbeitung für hohe Effizienz
- Bei Überschreitung des Rate-Limits werden Teilergebnisse zurückgegeben
- Diese API teilt sich das QPS-Limit mit der Push API. Ein Batch-Push auf 1 regid oder 1 alias verbraucht 1 QPS der Push API.

Authentifizierung

Fügen Sie das HTTP-Header-Feld für Authentifizierung hinzu:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

Diesen Codeblock im schwebenden Fenster anzeigen

Generierung: base64(username:password)
- username = Applikations-AppKey
- password = Master Secret
Zugriffspfad: Konsole → App-Einstellungen → App-Informationen

Endpunkte

Batch-Push per registration_id

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

Diesen Codeblock im schwebenden Fenster anzeigen

Batch-Push per alias

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

Diesen Codeblock im schwebenden Fenster anzeigen

Anfragebeispiele

1. Batch-Push per registration_id

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "android", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android", "builder_id": 1, "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \
  -H "Content-Type: application/json" \
  -u "AppKey:MasterSecret" \
  -d '{
    "requests": [
      {
        "target": "registration_id_1",
        "platform": "android",
        "notification": {
          "android": {
            "alert": "Hi, Push!",
            "title": "Send to Android",
            "builder_id": 1,
            "extras": { "newsid": 321 }
          }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        },
        "custom_args": { "business": "info" }
      },
      {
        "target": "registration_id_2",
        "platform": "ios",
        "notification": {
          "ios": {
            "alert": "Hi, MTPush!",
            "sound": "default",
            "badge": "+1",
            "extras": { "newsid": 321 }
          }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

Diesen Codeblock im schwebenden Fenster anzeigen

2. Batch-Push per alias

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "all", "notification": { "android": { "alert": "Hi, Push!", "title": "Send to Android" }, "ios": { "alert": "Hi, MTPush!", "sound": "default" } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "ios", "notification": { "ios": { "alert": "Hi, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \
  -H "Content-Type: application/json" \
  -u "AppKey:MasterSecret" \
  -d '{
    "requests": [
      {
        "target": "user_alias_1",
        "platform": "all",
        "notification": {
          "android": { "alert": "Hi, Push!", "title": "Send to Android" },
          "ios": { "alert": "Hi, MTPush!", "sound": "default" }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      },
      {
        "target": "user_alias_2",
        "platform": "ios",
        "notification": {
          "ios": {
            "alert": "Hi, MTPush!",
            "sound": "default",
            "badge": "+1",
            "extras": { "newsid": 321 }
          }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrageparameter

Struktur des Request-Bodys:

{ "requests": [ { "target": "string", // Erforderlich, Push-Ziel (registration_id oder alias) "platform": "string", // Erforderlich, Push-Plattform (android/ios/all) "notification": "object", // Optional, Benachrichtigungsinhalt (siehe Single Push API) "message": "object", // Optional, individuelle Nachricht (siehe Single Push API), darf nicht gleichzeitig mit notification verwendet werden "options": "object", // Optional, Push-Optionen (siehe Push API) "custom_args": "object" // Optional, an den Client übergebene Parameter } ] }

              
              {
  "requests": [
    {
      "target": "string",     // Erforderlich, Push-Ziel (registration_id oder alias)
      "platform": "string",   // Erforderlich, Push-Plattform (android/ios/all)
      "notification": "object",  // Optional, Benachrichtigungsinhalt (siehe Single Push API)
      "message": "object",     // Optional, individuelle Nachricht (siehe Single Push API), darf nicht gleichzeitig mit notification verwendet werden
      "options": "object",     // Optional, Push-Optionen (siehe Push API)
      "custom_args": "object"  // Optional, an den Client übergebene Parameter
    }
  ]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Parameterbeschreibung:

Feld	Erforderlich	Typ	Beschreibung
`requests`	Ja	array	Batch-Request-Array (max. 500 Einträge, `target` muss innerhalb des Batches eindeutig sein)
`target`	Ja	string	Zielwert: - `/regid`-Endpunkt: `registration_id` - `/alias`-Endpunkt: `alias`
`platform`	Ja	string	Push-Plattform: `android`, `ios` oder `all`
`notification`	Nein	object	Benachrichtigungsinhalt (siehe Single Push API)
`message`	Nein	object	Individuelle Nachricht (siehe Single Push API), darf nicht gleichzeitig mit notification verwendet werden
`options`	Nein	object	Push-Optionen (z. B. `time_to_live`, `apns_production`)
`custom_args`	Nein	object	Individuelle Parameter für den Client

Antwortbeispiele

Erfolgreiche Antwort (alle erfolgreich)

{ "results": { "registration_id_1": { "target": "registration_id_1", "success": true, "msg_id": 2460001 }, "registration_id_2": { "target": "registration_id_2", "success": true, "msg_id": 2460002 } } }

              
              {
  "results": {
    "registration_id_1": {
      "target": "registration_id_1",
      "success": true,
      "msg_id": 2460001
    },
    "registration_id_2": {
      "target": "registration_id_2",
      "success": true,
      "msg_id": 2460002
    }
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Erfolgreiche Antwort (teilweise Rate-Limiting)

{ "rate_limit_info": { "message": "Einige Anfragen wurden während der Batch-Verarbeitung durch das Rate-Limit eingeschränkt", "rate_limit_occurred": true }, "results": { "170976fa8a0771c2647": { "target": "170976fa8a0771c2647", "success": false, "error": { "code": 23008, "message": "API-Rate-Limit überschritten" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "API-Rate-Limit überschritten" } } } }

              
              {
    "rate_limit_info": {
        "message": "Einige Anfragen wurden während der Batch-Verarbeitung durch das Rate-Limit eingeschränkt",
        "rate_limit_occurred": true
    },
    "results": {
        "170976fa8a0771c2647": {
            "target": "170976fa8a0771c2647",
            "success": false,
            "error": {
                "code": 23008,
                "message": "API-Rate-Limit überschritten"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "API-Rate-Limit überschritten"
            }
        }
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlgeschlagene Antwort (globaler Fehler)

{ "error": { "code": 21004, "message": "Basic-Authentifizierung fehlgeschlagen" } }

              
              {
  "error": {
    "code": 21004,
    "message": "Basic-Authentifizierung fehlgeschlagen"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlgeschlagene Antwort (Parameterfehler)

{ "error": { "code": 21003, "message": "Parameterwert ist ungültig" } }

              
              {
  "error": {
    "code": 21003,
    "message": "Parameterwert ist ungültig"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlercode-Referenz

Fehlercode	Beschreibung	Lösungsvorschlag	HTTP-Status
Globale Fehlercodes
21004	Basic-Authentifizierung fehlgeschlagen	AppKey/MasterSecret prüfen	401
21008	AppKey-Länge ist nicht 24 Zeichen	AppKey-Format überprüfen	400
21038	Keine Push-Berechtigung für die App	App-Konfiguration prüfen	400
21043	Keine Push-Berechtigung (Zahlung ausstehend)	Zahlungsproblem beheben	400
23009	IP nicht auf Allowlist	Server-IP zur Allowlist hinzufügen	400
21009	Interner Systemfehler (nicht erneut versuchen)	Technischen Support kontaktieren	400
Rate-Limit-Fehler
23008	API-Rate-Limit erreicht	Fehlgeschlagene Einträge erneut versuchen, falls Teilerfolg	400
Parameterfehler
21003	Ungültiger Parameterwert	Format des Request-Bodys prüfen	400
21015	Ungültige Anfrageparameter	Erforderliche Felder validieren	400
21016	Parameterüberprüfung fehlgeschlagen	Feldtypen und Wertebereiche prüfen	400

Vollständige Fehlercodes: Create Push API – Response

Hinweise

Rate-Limit-Verarbeitung: Bei Überschreitung des Rate-Limits werden Teilerfolgsergebnisse zurückgegeben (msg_id für erfolgreiche + error für fehlgeschlagene).
Doppelter Check: Alle target- oder cid-Werte müssen innerhalb eines Batches eindeutig sein.
Mengengrenze: Maximal 500 Ziele pro Anfrage.
Fehlerbehandlung: Globale Fehler (z. B. Authentifizierungsfehler) führen zum sofortigen Abbruch ohne Teilergebnisse.