Push API v4 – Web-Push-Benachrichtigungen per JSON versenden
Versenden Sie gezielte Push-Benachrichtigungen oder Nachrichten an einzelne Geräte oder eine Liste von Geräten – schnell, sicher und flexibel mit der Push API v4. Push-Inhalte werden ausschließlich als Push-Objekt im JSON-Format bereitgestellt. Weitere Funktionen im Zusammenhang mit Label oder Alias finden Sie in der AppPushAPI.
- Verwendung von HTTP Basic Authentication zur Zugriffsauthorisierung. Dadurch kann die gesamte API-Anfrage komfortabel mit gängigen HTTP-Tools wie
curloder Browser-Plugins durchgeführt werden. - Push-Inhalte werden im JSON-Format bereitgestellt.
Anfrage-Limits
Um die Stabilität und Fairness unseres Dienstes sicherzustellen, begrenzen wir die Aufrufhäufigkeit der API. Die QPS (Queries Per Second)-Grenzwerte pro AppKey lauten wie folgt:
- Standardlimit: Bis zu 500 Anfragen pro Sekunde.
- Erweitertes Limit: Wenn Ihr kostenpflichtiger AppKey ein höheres QPS-Limit benötigt, wenden Sie sich bitte an unser Vertriebsteam: Sales@engagelab.com.
Authentifizierung der Anfragen
Detaillierte Informationen finden Sie unter Authentifizierungsmethode.
API-Endpunkt
POST v4/push
Beispielanfragen
Request Header
> POST /v4/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
Request Body
{
"from": "push",
"to": "all",
"body": {
"platform": "web",
"notification": {
"alert": "Hi,MTPush !",
"web": {
"alert": "web_push",
"title": "web_push",
"url": "http://www.google.com",
"extras": {
"web-key1": "web-value1"
}
}
}
},
"request_id": "12345678",
"custom_args": {
"business": "info"
}
}
Anfrageparameter
Die Struktur der Push-Parameter ist in der folgenden Tabelle detailliert beschrieben.
| Schlüsselwort | Typ | Optional | Beschreibung |
|---|---|---|---|
| from | String | Optional | Aktueller Absender der Anwendung |
| to | String oder JSON-Objekt | Erforderlich | Zielgerät(e) |
| body | JSON-Objekt | Erforderlich | Inhalt der Anfrage |
| platform | String oder JSON-Array | Erforderlich | Ziel-Plattform |
| notification | JSON-Objekt | Optional | |
| message | JSON-Objekt | Optional | |
| options | JSON-Objekt | Optional | Zusätzliche Push-Parameter |
| request_id | String | Optional | Benutzerdefiniertes Feld zur Identifizierung der Anfrage, wird in der Antwort zurückgegeben. |
| custom_args | JSON-Objekt | Optional | Benutzerdefinierte optionale Felder, die beim Callback zurückgegeben werden. |
from
Der Absender der aktuellen Anwendung. Wert ist vom Typ String und optional.
Beispielanfrage
{
"from": "push"
}
to
Push-Geräteobjekt, das die Liste der Geräte angibt, an die gepusht werden kann. MTPush bietet zwei Methoden: Registration ID und Broadcast.
Push-Ziel
| Schlüsselwort | Typ | Erklärung | Beschreibung | Hinweis |
|---|---|---|---|---|
| all | String | Broadcast | Push an alle Geräte | Zielgeräte, die in den letzten 30 Tagen aktiv waren. |
| registration_id | JSON-Array | Registration ID | Array. Mehrere Registration IDs sind ODER-verknüpft (Vereinigung). | Geräte-ID. Maximal 1.000 Nachrichten pro Push. |
| tag | JSON-Array | Tag | Arrays. Mehrere Tags sind ODER-verknüpft (Vereinigung). | Tags für großflächige Geräte- oder Nutzerattribut-Gruppierungen. Maximal 20 Tags pro Push. Gültige Zeichen: Buchstaben (Groß-/Kleinschreibung), Zahlen, Unterstriche, chinesische Zeichen. Jeder Tag max. 40 Bytes (UTF-8). |
| tag_and | JSON-Array | Tag UND | Array. Mehrere Tags sind UND-verknüpft (Schnittmenge). | Bis zu 20 Tags pro Push. |
| tag_not | JSON-Array | Tag NICHT | Array. Zuerst Vereinigung aller Tags, dann Komplement. | Bis zu 20 Tags pro Push. |
| alias | JSON-Array | Alias | Array. Mehrere Aliase sind ODER-verknüpft (Vereinigung). | Identifiziert Nutzer:innen eindeutig. Ein Gerät kann nur einem Alias zugeordnet werden und umgekehrt. Maximal 1.000 Aliase pro Push. Gültige Zeichen: Buchstaben (Groß-/Kleinschreibung), Zahlen, Unterstriche, chinesische Zeichen. Jeder Alias max. 40 Bytes (UTF-8). |
Die implizite Beziehung zwischen mehreren Werten in einem Array ist ODER (Vereinigung); bei tag_and ist die Beziehung UND (Schnittmenge).
Wird tag_not allein verwendet, erfolgt die tag_not-Verarbeitung unter den Broadcast-Nutzer:innen.
Diese Typen können koexistieren. Die implizite Beziehung zwischen mehreren Feldern beim gemeinsamen Auftreten ist UND (Schnittmenge). Beispiel:
"to" : {"tag" : [ "tag1", "tag2"],
"tag_and" : ["tag3", "tag4"],
"tag_not" : ["tag5", "tag6"]
}
Berechnung:
- "tag"-Feld: tag1 oder tag2 = A
- "tag_and"-Feld: tag3 und tag4 = B
- "tag_not"-Feld: nicht (tag5 oder tag6) = C
Das Endergebnis von "to" ist A und B und C.
Beispielanfragen
- Push an alle (Broadcast):
{
"to": "all"
}
- Push an mehrere Registration IDs:
{
"to": {
"registration_id": [
"4312kjklfds2",
"8914afd2",
"45fdsa31"
]
}
}
body
Der Anfragetext. Unterstützte Felder:
| Schlüsselwort | Typ | Optional | Beschreibung |
|---|---|---|---|
| platform | String oder JSON-Array | Erforderlich | Ziel-Plattform |
| notification | JSON-Objekt | Optional | |
| message | JSON-Objekt | Optional | |
| options | JSON-Objekt | Optional | Zusätzliche Push-Parameter |
platform
MTPush unterstützt derzeit nur Push für die Web-Plattform. Der Wert von platform ist daher immer „web“.
{ "platform": "web" }
notification
Das notification-Objekt ist einer der möglichen Push-Inhalte (das andere ist message) und wird als Benachrichtigung an die Web-Plattform gesendet.
| Schlüsselwort | Typ | Optional | Erklärung | Beschreibung |
|---|---|---|---|---|
| web | JSON-Objekt | Erforderlich | Plattform-Eigenschaften | Web-Plattform-Benachrichtigungen, siehe web |
web
Web-Plattform-Benachrichtigungen
| Schlüsselwort | Typ | Optional | Erklärung | Beschreibung |
|---|---|---|---|---|
| alert | String oder JSON-Objekt | Erforderlich | Inhalt | Der eigentliche Nachrichtentext, überschreibt die alert-Information der übergeordneten Ebene. |
| url | String | Optional | Web-Push-URL | Zieladresse beim Klick auf die Benachrichtigung. Falls angegeben, muss es eine gültige URL sein. |
| title | String | Optional | Titel | Nachrichtentitel |
| extras | JSON-Objekt | Optional | Erweiterte Felder | Benutzerdefinierte Key/Value-Informationen im JSON-Format für geschäftliche Zwecke. |
| icon | String | Optional | Benachrichtigungs-Icon | Empfohlen: 192x192px, max. 1 MB, Formate: JPG, PNG, GIF. Unterstützt Chrome, Firefox (Safari und Edge unterstützen keine eigenen Icons). |
| image | String | Optional | Großes Bild für Benachrichtigung | Empfohlen: 360x180px, max. 1 MB, Formate: JPG, PNG, GIF. Unterstützt Chrome, Edge (Firefox und Safari nicht unterstützt). |
{
"notification": {
"web": {
"alert": "Hallo, Push!",
"title": "Push-Test",
"url": "http://www.google.com",
"icon": "",
"image": "",
"extras": {
"news_id": 134,
"my_key": "ein Wert"
}
}
}
}
message
In-App-Nachrichten oder benutzerdefinierte Nachrichten. Dieser Inhalt wird nicht im Browser angezeigt. Nach Empfang wird die Nachricht vom SDK an das Web übertragen und dort verarbeitet.
| Schlüsselwort | Typ | Optional | Beschreibung |
|---|---|---|---|
| msg_content | String oder JSON-Objekt | Erforderlich | Nachrichteninhalt |
| title | String | Optional | Nachrichtentitel |
| content_type | String | Optional | Nachrichtentyp |
| extras | JSON-Objekt | Optional | Optionale Parameter im JSON-Format |
Beispiel:
{
"message": {
"msg_content": "Hallo, Push",
"content_type": "text",
"title": "msg",
"extras": {
"key": "Wert"
}
}
}
options
Push-Optionen. Folgende Optionen sind verfügbar:
| Schlüsselwort | Typ | Optional | Erklärung | Beschreibung |
|---|---|---|---|---|
| time_to_live | Int oder String | Optional | Dauer der Offline-Nachrichten (Sekunden) | |
| override_msg_id | Long | Optional | Zu überschreibende Nachrichten-ID | Wenn der aktuelle Push eine frühere Nachricht überschreiben soll, hier die msg_id der alten Nachricht angeben. Die Funktion ist 1 Tag gültig. Existiert die msg_id nicht, wird Fehler 1003 zurückgegeben und der Push nicht durchgeführt. |
| big_push_duration | Int | Optional | Dauer für verzögerten Push (Minuten) | |
| web_buttons | JSON-Objekt | Optional | Benachrichtigung mit Buttons versehen | |
| multi_language | JSON-Objekt | Optional | Mehrsprachige Push-Einstellungen | Mehrsprachige Anpassung für Push-Inhalte. Details siehe multi_language. |
| third_party_channel | JSON-Objekt | Optional | Konfiguration für Web-Systemkanal | Gültig nur für Nutzer:innen mit Systemkanal-Konfiguration. Details siehe third_party_channel. |
| plan_id | String | Optional | Push-Plan-ID | Muss zuvor erstellt werden, entweder in der Konsole oder per API. |
| cid | String | Optional | Push-Request-ID zur Duplikatsvermeidung | Nur Buchstaben, Zahlen, Unterstriche, Bindestriche, max. 64 Zeichen. Muss unter einem AppKey eindeutig sein. |
multi_language
Dieses Feld ermöglicht mehrsprachige Push-Benachrichtigungen. Sie können für verschiedene Sprachen individuelle Inhalte und Titel angeben, die je nach Spracheinstellung der Nutzer:innen versendet werden.
Anfrageparameter
| Schlüsselwort | Typ | Optional | Erklärung | Beschreibung |
|---|---|---|---|---|
| en, de, ... | string | Optional | Sprachcode | Entspricht der Nutzersprache, siehe Tabelle unten |
| content | string | Optional | Nachrichtentext | Ersetzt notification.web.alert bzw. message.msg_content je nach Sprache |
| title | string | Optional | Nachrichtentitel | Ersetzt notification.web.title bzw. message.title je nach Sprache |
Beispielanfrage
HTTP-Methode: POST
Anfrage-URL: /v4/push
POST-Datenformat: json
POST-Datenbeispiel:
{
"options": {
"multi_language": {
"de": {
"content": "",
"title": ""
}
}
}
}
Beispielantwort
Bei Erfolg:
{
}
Bei Fehler:
{
"code": 400,
"data": "",
"message": "Fehlerinformation"
}
web_buttons
Mit dem Parameter web_buttons können Buttons in Benachrichtigungen hinzugefügt werden. Die Parameter sind:
| Schlüsselwort | Typ | Optional | Erklärung | Beschreibung |
|---|---|---|---|---|
| id | String | Erforderlich | Button-ID | Unterstützt ab Chrome 48+ |
| text | String | Erforderlich | Button-Text | Unterstützt ab Chrome 48+ |
| icon | String | Optional | Button-Icon | Unterstützt ab Chrome 50+ |
| url | String | Erforderlich | Button-Ziellink | Unterstützt ab Chrome 48+. Wenn web_buttons verwendet wird, ist das url-Feld im web-Parameter nicht wirksam |
Beispiel:
[
{
"id": "like-button",
"text": "Gefällt mir",
"icon": "http://i.imgur.com/N8SN8ZS.png",
"url": "https://yoursite.com"
},
{
"id": "read-more-button",
"text": "Mehr lesen",
"icon": "http://i.imgur.com/MIxJp1L.png",
"url": "https://yoursite.com"
}
]
third_party_channel
Dieses Feld dient zur Angabe von Informationen für den Web-Systemkanal. Der Schlüsselname ist w3push, der Wert ein JSON-Objekt mit einem optionalen distribution-Feld (String).
| Schlüsselwort | Typ | Optional | Erklärung | Beschreibung |
|---|---|---|---|---|
| distribution | String | Erforderlich | Priorität der Zustellung | Der Wert darf kein leerer String sein. Der Standardwert ist first_ospush. first_ospush: Zuerst Systemkanal, Engagelab nicht verwendet. mtpush: Nur über Engagelab. secondary_push: Erst Engagelab, dann Systemkanal (empfohlen). ospush: Nur über Systemkanal. |
Beispiel:
{
"third_party_channel": {
"w3push": {
"distribution": "mtpush"
}
}
}
request_id
Die ID der Anfrage. Dient zur Identifikation und wird in der Antwort zurückgegeben.
Beispiel
{
"request_id": "12345678"
}
custom_args
Benutzerdefiniertes optionales Feld. Wird nicht in der Antwort, sondern beim Callback zurückgegeben.
{
"custom_args": {
"business": "info"
}
}
Antwortparameter
Antwort bei Erfolg
| Feld | Typ | Optional | Beschreibung |
|---|---|---|---|
| request_id | String | Erforderlich | Die Antwort-Eigenschaft ist immer vorhanden. Die in der Anfrage übermittelte benutzerdefinierte ID wird unverändert zurückgegeben; ohne Angabe ist sie in der Regel ein leerer String. |
| msg_id | String | Erforderlich | Eindeutige Nachrichten-ID. |
< HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id": "18", "msg_id": "1828256757"}
Fehlerantwort
Der HTTP-Statuscode ist 4xx oder 5xx. Der Antwort-Body enthält folgende Felder:
| Feld | Typ | Optional | Beschreibung |
|---|---|---|---|
| code | int | Erforderlich | Fehlercode. Weitere Infos siehe return-code. |
| message | String | Erforderlich | Fehlerdetails |
{
"code": 3002,
"message": "Push.template Feld muss korrekt gesetzt werden, wenn Typ 'template' ist"
}
Antwort
HTTP-Statuscodes
Referenz: HTTP-Status-Code
Rückgabecodes
| Code | Beschreibung | Details | HTTP-Statuscode |
|---|---|---|---|
| 20101 | Ungültige Push-Parameter | Registrierungs-ID ungültig oder nicht zur aktuellen appkey gehörig | 400 |
| 21001 | Nur HTTP POST unterstützt | GET nicht unterstützt | 405 |
| 21002 | Pflichtparameter fehlt | Korrigieren | 400 |
| 21003 | Ungültiger Parameterwert | Korrigieren | 400 |
| 21004 | Verifizierung fehlgeschlagen | Korrigieren, siehe Aufrufvalidierung | 401 |
| 21005 | Nachricht zu groß | Korrigieren; Notification/Message max. 4000 Byte | 400 |
| 21007 | Ungültiger Eingabeparameter | Der Parameter receiver_value ist ungültig | 400 |
| 21008 | Ungültiger app_key-Parameter | Muss korrigiert werden. Prüfen Sie, ob der übermittelte appkey eine Zeichenfolge mit 24 Zeichen ist und ob zusätzliche Leerzeichen enthalten sind | 400 |
| 21009 | Interner Systemfehler | Support kontaktieren | 400 |
| 21011 | Kein passendes Push-Ziel | Feld to prüfen |
400 |
| 21015 | Parametervalidierung fehlgeschlagen | Unerwartete Parameter | 400 |
| 21016 | Parametervalidierung fehlgeschlagen | Falscher Typ oder Länge überschritten | 400 |
| 21030 | Interner Timeout | Später erneut versuchen | 503 |
| 21036 | Parameterfehler | Benachrichtigung und Custom-Message nicht gleichzeitig | 400 |
| 21037 | Ungültiger group_key | group_key ist kein 24-stelliger String, oder die zugehörige App-Gruppe existiert nicht | 400 |
| 21038 | Push-Berechtigungsfehler | VIP abgelaufen oder nicht aktiv | 400 |
| 21039 | Web-Button-Parameterfehler | id, url oder text des Web Button ist leer | 400 |
| 21040 | Anzahl der Web Buttons überschreitet das Limit | Die Anzahl der Web Buttons darf 2 nicht überschreiten | 400 |
| 21041 | Ungültige Web-Button-URL | Das url-Format des Web Button ist ungültig | 400 |
| 21042 | Doppelte Web-Button-ID | Web-Button-ids in derselben Anfrage dürfen nicht doppelt vorkommen | 400 |
| 21043 | Push-Berechtigungsfehler | Die App hat eine unbezahlte Rechnung | 400 |
| 21061 | Validierung von Inhalt oder Callback-Konfiguration fehlgeschlagen | Der Push-Inhalt enthält sensible Wörter, oder die angeforderte callback_url ist nicht in den Callback-Adressen der aktuellen App konfiguriert | 400 |
| 21062 | Anzahl der Datei-Push-Ziele überschreitet das Limit | Die Anzahl der Push-Ziele in der Datei überschreitet das App-Kontingent oder das Systemlimit | 400 |
| 23006 | Parameterfehler | big_push_duration über Maximum 1440 |
400 |
| 23008 | Schnittstellen-Rate-Limit | Push-QPS-Limit (500) erreicht | 400 |
| 23009 | Push-Berechtigungsfehler | Client-IP nicht in IP-Whitelist | 400 |
| 27000 | Interner Speicherfehler | Erneut versuchen | 500 |
| 27001 | Ungültige Authentifizierungsinformationen | Der AppKey in Basic Auth ist 24 Zeichen lang, aber die Anwendung existiert nicht, oder die Authentifizierungsinformationen der Anwendung sind ungültig | 401 |
| 27006 | override_msg_id existiert nicht | Kein Push-Datensatz für override_msg_id gefunden | 400 |
| 27007 | Formatfehler von override_msg_id | override_msg_id ist negativ oder hat ein ungültiges Format | 400 |
| 27008 | Parameterfehler | third_party_channel mit distribution, aber leerer alert |
400 |
| 27009 | Parameterfehler | Ungültiges oder leeres distribution in third_party_channel |
400 |
| 27104 | Segment-ID existiert nicht | Die segment ID existiert nicht. Erstellen oder ändern Sie zuerst das Segment | 400 |
| 27200 | Ungültige msg_id | Das Format von msg_id ist ungültig | 400 |
| 27201 | msg_id existiert nicht oder gehört nicht zur App | msg_id existiert nicht oder gehört nicht zum aktuellen appkey | 400 |
| 27202 | Nachricht bereits zurückgezogen | Die Nachricht zu msg_id wurde bereits zurückgezogen | 400 |
| 27203 | Systemfehler | Systemfehler, bitte erneut versuchen | 400 |
| 27204 | Rücknahmezeit der Nachricht überschritten | Die Nachricht hat die zulässige Rücknahmezeit überschritten | 400 |
| 27300 | Ungültige Push-Plan-ID | Das Format von plan_id ist ungültig | 400 |
| 27301 | Ungültige Push-Plan-Beschreibung | Die Länge von plan_description überschreitet das Limit | 400 |
| 27302 | Anzahl der Push-Pläne überschreitet das Limit | Die Anzahl verfügbarer Push-Pläne hat das Limit erreicht | 400 |
| 27303 | Push-Plan-ID ist leer | plan_id darf nicht leer sein | 400 |
| 27304 | Push-Plan-ID zu lang | Die Länge von plan_id überschreitet das Limit | 400 |
| 27305 | Push-Plan existiert nicht | Die angegebene plan_id existiert unter dem aktuellen appkey nicht | 400 |
| 27306 | Anzahl der Push-Plan-IDs überschreitet das Limit | Die Anzahl der plan_ids überschreitet das Limit | 400 |
| 28100 | Ungültiger Parameter der geplanten Aufgabe | Der Parameter schedule task ist ungültig | 400 |
| 28101 | Authentifizierung der geplanten Aufgabe fehlgeschlagen | Basic Authentication fehlgeschlagen | 401 |
| 28102 | Ungültiger Parameter des geplanten Push | Der Parameter push ist leer oder ungültig | 400 |
| 28103 | Ungültige Zeit des geplanten Push | Das Format von single time oder trigger time ist fehlerhaft | 400 |
| 28104 | Geplante Aufgabe existiert nicht | Die angeforderte schedule task existiert nicht | 404 |
| 28105 | Geplante Aufgabe hat kein Push-Ziel | Zum geplanten Zeitpunkt gibt es kein passendes Push-Ziel | 400 |
| 28200 | Systemfehler der geplanten Aufgabe | Im Dienst ist ein unerwarteter interner Fehler aufgetreten | 500 |
Push-Beschränkungen
| Kanal | Betreff-Länge | Inhaltslänge | Zusätzliche Hinweise |
|---|---|---|---|
| Engagelab | Kein Limit, aber Gesamtgröße des Nachrichtenkörpers begrenzt | Kein Limit, aber Gesamtgröße des Nachrichtenkörpers begrenzt | Notification MTPush max. 4.000 Bytes. |
| Systemkanal | <20 Zeichen (40 englische Zeichen) | Keine |
Sprachcodes
| Sprache | Sprachcode |
|---|---|
| Englisch | en |
| Arabisch | ar |
| Chinesisch (vereinfacht) | zh-Hans |
| Chinesisch (traditionell) | zh-Hant |
| Tschechisch | cs |
| Dänisch | da |
| Niederländisch | nl |
| Französisch | fr |
| Deutsch | de |
| Hindi | hi |
| Italienisch | it |
| Japanisch | ja |
| Koreanisch | ko |
| Malaiisch | ms |
| Russisch | ru |
| Spanisch | es |
| Thailändisch | th |
| Vietnamesisch | vi |
| Indonesisch | id |
| Norwegisch | no |
| Schwedisch | sv |
| Polnisch | pl |
| Türkisch | tr |
| Hebräisch | he |
| Portugiesisch | pt |
| Rumänisch | ro |
| Ungarisch | hu |
| Finnisch | fi |
| Griechisch | el |
| Ukrainisch | uk |
| Laotisch | lo |
| Portugiesisch (Portugal) | pt_PT |
| Portugiesisch (Brasilien) | pt_BR |
| Spanisch (Argentinien) | es_AR |
| Spanisch (Spanien) | es_ES |
| Spanisch (Lateinamerika) | es_419 |










