Batch-Einzel-Push-API

Batch Push API – Einzelbenachrichtigungen im Batch-Verfahren

Funktionsbeschreibung

Mit der Batch Push API können Sie batchweise Einzelbenachrichtigungen versenden und so mehrere Zielnutzer:innen mit nur einem API-Aufruf effizient erreichen. Unterstützt wird das Versenden von Push-Benachrichtigungen entweder per registration_id oder per alias:

Batch-Push per registration_id: POST /v4/batch/push/regid
Batch-Push per alias: POST /v4/batch/push/alias

Grenzen und Limitierungen:

Maximal 500 Push-Ziele pro Anfrage
Unterstützt parallele Verarbeitung für hohe Effizienz
Bei Rate-Limiting werden Teilergebnisse mit Erfolgs- und Fehlermeldungen zurückgegeben
Diese API teilt sich das QPS-Kontingent mit der Push API. Das Versenden an 1 registration_id oder 1 alias über die Batch Push API verbraucht 1 QPS-Kontingent der Push API.

Authentifizierung

Fügen Sie das Authentifizierungsfeld im HTTP-Header hinzu:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

Diesen Codeblock im schwebenden Fenster anzeigen

Generierung: base64(username:password)
- username = Anwendungs-AppKey
- password = Master Secret
Zugriffspfad: Konsole → Anwendungseinstellungen → Anwendungsinfo

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://webpushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "registration_id_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
                "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        },
        "custom_args": {
          "business": "info"
        }
      },
      {
        "target": "registration_id_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
                "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "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://webpushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "user_alias_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
              "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      },
      {
        "target": "user_alias_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      }
    ]
  }'

Diesen Codeblock im schwebenden Fenster anzeigen

Anfrageparameter

Struktur des Anfragebodys:

{ "requests": [ { "target": "string", // Erforderlich, Push-Ziel (registration_id oder alias) "platform": "string", // Erforderlich, Push-Plattform-Einstellung (siehe Push API) "notification": "object", // Optional, Benachrichtigungsinhalt (siehe Push API) "message": "object", // Optional, individuelle Nachricht (siehe Push API), kann nicht mit notification kombiniert werden "options": "object", // Optional, Push-Optionen (z. B. time_to_live, apns_production) "custom_args": "object" // Optional, individuelle Übergabeparameter } ] }

              
              {
  "requests": [
    {
      "target": "string",     // Erforderlich, Push-Ziel (registration_id oder alias)
      "platform": "string",   // Erforderlich, Push-Plattform-Einstellung (siehe Push API)
      "notification": "object",  // Optional, Benachrichtigungsinhalt (siehe Push API)
      "message": "object",     // Optional, individuelle Nachricht (siehe Push API), kann nicht mit notification kombiniert werden
      "options": "object",     // Optional, Push-Optionen (z. B. time_to_live, apns_production)
      "custom_args": "object"  // Optional, individuelle Übergabeparameter
    }
  ]
}

Diesen Codeblock im schwebenden Fenster anzeigen

Parameterbeschreibung:

Feld	Erforderlich	Typ	Beschreibung
`requests`	Ja	array	Batch-Anfrage-Array (max. 500 Einträge, `target` muss je Batch 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 (gleiche Struktur wie Push API)
`message`	Nein	object	Individuelle Nachricht (gleiche Struktur wie Push API)
`options`	Nein	object	Push-Optionen (z. B. `time_to_live`, `apns_production`)
`custom_args`	Nein	object	Individuelle Übergabeparameter

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": "Rate limit exceeded for the API" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Rate limit exceeded for the API" } } } }

              
              {
    "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": "Rate limit exceeded for the API"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Rate limit exceeded for the API"
            }
        }
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlgeschlagene Antwort (globaler Fehler)

{ "error": { "code": 21004, "message": "basic auth failed" } }

              
              {
  "error": {
    "code": 21004,
    "message": "basic auth failed"
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

Fehlgeschlagene Antwort (Parameterfehler)

{ "error": { "code": 21003, "message": "Parameter value is invalid" } }

              
              {
  "error": {
    "code": 21003,
    "message": "Parameter value is invalid"
  }
}

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 ist nicht 24 Zeichen lang	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 lösen	400
23009	IP nicht auf der 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	400
Parameterfehler
21003	Ungültiger Parameterwert	Anfrageformat prüfen	400
21015	Ungültige Anfrageparameter	Pflichtfelder validieren	400
21016	Parameterüberprüfung fehlgeschlagen	Feldtypen und Wertebereiche prüfen	400

Vollständige Fehlercodes: Create Push API – Response

Hinweise

Rate-Limit-Handling: Bei Rate-Limiting werden Teilergebnisse mit msg_id für erfolgreiche und error für fehlgeschlagene Einträge zurückgegeben.
Duplikatsprüfung: 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 zu einem sofortigen Abbruch ohne Teilergebnisse.

Jetzt Batch Push API nutzen und Push-Benachrichtigungen effizient versenden.