Push-Erstellungs-API

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.

Dies ist die neueste Version der Push API. Die Neuerungen der Version v4 im Überblick:

Verwendung von HTTP Basic Authentication zur Zugriffsauthorisierung. Dadurch kann die gesamte API-Anfrage komfortabel mit gängigen HTTP-Tools wie curl oder 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

              
              POST v4/push

Diesen Codeblock im schwebenden Fenster anzeigen

Beispielanfragen

Request Header

> POST /v4/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              > POST /v4/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

Diesen Codeblock im schwebenden Fenster anzeigen

Request Body

{ "from": "push", "to": "all", "body": { "platform": "web", "notification": { "alert": "Hi,MTPush !", //optional "web": { "alert": "web_push", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } } }, "request_id": "12345678", "custom_args": "business info" }

              
              {
    "from": "push",
    "to": "all",
    "body": {
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !", //optional
            "web": {
                "alert": "web_push",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        }
    },
    "request_id": "12345678",
    "custom_args": "business info"
}

Diesen Codeblock im schwebenden Fenster anzeigen

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	Benachrichtigungskörper, der an den Client gesendet wird. notification oder message – eines muss enthalten sein, beide dürfen nicht gleichzeitig vorkommen.
message	JSON-Objekt	Optional	Nachrichtenkörper, der an den Client gesendet wird. notification oder message – eines muss enthalten sein, beide dürfen nicht gleichzeitig vorkommen.
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" }

              
              {
    "from": "push"
}

Diesen Codeblock im schwebenden Fenster anzeigen

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

              
              {
  "to": "all"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Push an mehrere Registration IDs:

{ "to": { "registration_id": [ "4312kjklfds2", "8914afd2", "45fdsa31" ] } }

              
              {
  "to": {
    "registration_id": [
      "4312kjklfds2",
      "8914afd2",
      "45fdsa31"
    ]
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

body

Der Anfragetext. Unterstützte Felder:

Schlüsselwort	Typ	Optional	Beschreibung
platform	String oder JSON-Array	Erforderlich	Ziel-Plattform
notification	JSON-Objekt	Optional	Benachrichtigungskörper, der an den Client gesendet wird. notification oder message – eines muss enthalten sein, beide dürfen nicht gleichzeitig vorkommen.
message	JSON-Objekt	Optional	Nachrichtenkörper, der an den Client gesendet wird. notification oder message – eines muss enthalten sein, beide dürfen nicht gleichzeitig vorkommen.
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" }

              
              { "platform": "web" }

Diesen Codeblock im schwebenden Fenster anzeigen

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	Erforderlich	Web-Push-URL	Zieladresse beim Klick auf die Benachrichtigung
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" } } } }

              
              {
    "notification": {
        "web": {
            "alert": "Hallo, Push!",
            "title": "Push-Test",
            "url": "http://www.google.com",
            "icon": "",
            "image": "",
            "extras": {
                "news_id": 134,
                "my_key": "ein Wert"
            }
        }
    }
}

Diesen Codeblock im schwebenden Fenster anzeigen

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

              
              {
  "message": {
    "msg_content": "Hallo, Push",
    "content_type": "text",
    "title": "msg",
    "extras": {
      "key": "Wert"
    }
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

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)	Wenn Nutzer:innen beim Push offline sind, werden die Nachrichten für die angegebene Dauer gespeichert und beim nächsten Online-Zustand zugestellt. Standard: 86.400 (1 Tag), maximal 15 Tage. Falls der Browser weniger unterstützt, gilt dessen Limit. 0 bedeutet: Keine Speicherung, nur Online-Nutzer:innen erhalten den Push.
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)	Verlangsamt den Push und verteilt ihn gleichmäßig über n Minuten; maximal 1.440 Minuten. Maximal 20 verzögerte Pushes gleichzeitig. Wenn nicht gesetzt, erfolgt kein verzögerter Push.
web_buttons	JSON-Objekt	Optional	Benachrichtigung mit Buttons versehen	Maximal 2 Buttons. Name und Link können festgelegt werden. Details siehe web_buttons.
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": "" } } } }

              
                 HTTP-Methode: POST
   Anfrage-URL: /v4/push
   POST-Datenformat: json
   POST-Datenbeispiel:
   {
    "options": {
      "multi_language": {
        "de": {
          "content": "",
          "title": ""
        }
      }
    }
   }

Diesen Codeblock im schwebenden Fenster anzeigen

Beispielantwort

Bei Erfolg: { } Bei Fehler: { "code": 400, "data": "", "message": "Fehlerinformation" }

              
              Bei Erfolg:
{
   
}

Bei Fehler:
{   
    "code": 400,  
    "data": "",
    "message": "Fehlerinformation"
}

Diesen Codeblock im schwebenden Fenster anzeigen

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-Link	Unterstützt ab Chrome 48+. Wird web_buttons verwendet, ist das url-Feld im web-Parameter inaktiv.

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

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

Diesen Codeblock im schwebenden Fenster anzeigen

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	Werte: 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" } } }

              
              {
  "third_party_channel": {
    "w3push": {
      "distribution": "mtpush"
    }
  }
}

Diesen Codeblock im schwebenden Fenster anzeigen

request_id

Die ID der Anfrage. Dient zur Identifikation und wird in der Antwort zurückgegeben.

Beispiel

{ "request_id": "12345678" }

              
              {
    "request_id": "12345678"
}

Diesen Codeblock im schwebenden Fenster anzeigen

custom_args

Benutzerdefiniertes optionales Feld. Wird nicht in der Antwort, sondern beim Callback zurückgegeben.

{ "custom_args": "Geschäftsinformationen" }

              
              {
  "custom_args": "Geschäftsinformationen"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwortparameter

Antwort bei Erfolg

Feld	Typ	Optional	Beschreibung
request_id	String	Optional	Die übermittelte Anfrage-ID, wird in der Antwort zurückgegeben.
msg_id	String	Erforderlich	Eindeutige Nachrichten-ID.

< HTTP/1.1 200 OK < Content-Type: application/json {"request_id": "18", "msg_id": "1828256757"}

              
              < HTTP/1.1 200 OK
< Content-Type: application/json
{"request_id": "18", "msg_id": "1828256757"}

Diesen Codeblock im schwebenden Fenster anzeigen

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

              
              {
    "code": 3002,
    "message": "Push.template Feld muss korrekt gesetzt werden, wenn Typ 'template' ist"
}

Diesen Codeblock im schwebenden Fenster anzeigen

Antwort

HTTP-Statuscodes

Referenz: HTTP-Status-Code

Rückgabecodes

Code	Beschreibung	Details	HTTP-Statuscode
20101	Ungültiger Push-Parameter.	registration_id ist ungültig oder gehört nicht zum aktuellen AppKey.	400
21001	Nur HTTP POST wird unterstützt.	GET wird nicht unterstützt.	405
21002	Fehlende Pflichtparameter.	Muss korrigiert werden.	400
21003	Ungültiger Parameterwert.	Muss korrigiert werden.	400
21004	Authentifizierung fehlgeschlagen.	Muss korrigiert werden. Siehe Authentifizierung.	401
21005	Nachrichtenkörper zu groß.	Muss korrigiert werden. Notification max. 2.048 Bytes.	400
21008	Ungültiger app_key Parameter.	Bitte prüfen Sie app_key auf Korrektheit und Leerzeichen.	400
21009	Interner Systemfehler.	Muss korrigiert werden.	400
21011	Keine passenden Push-Ziele.	Bitte prüfen.	400
21015	Anfrageparameter ungültig.	Unerwartete Parameter.	400
21016	Anfrageparameter ungültig.	Falscher Typ oder Länge überschritten.	400
21030	Interner Dienst-Timeout.	Später erneut versuchen.	503
23006	Parameterfehler.	big_push_duration maximal 1.440.	400
23008	Schnittstellen-Limit erreicht.	Push QPS-Limit (500 QPS) erreicht.	400
27000	Speicherfehler.	Bitte erneut versuchen.	500
27001	Parameterfehler.	Verifizierungsinformation ist leer.	401
27008	Parameterfehler.	distribution in third_party_channel ist nicht leer, aber notification.alert ist leer.	401
27009	Parameterfehler.	Format von distribution in third_party_channel ungültig oder leer.	401

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)	Benachrichtigungszentrum und Sperrbildschirm: max. 110 Zeichen bzw. 55 chinesische Zeichen. Top-Popup: max. 62 Zeichen bzw. 31 chinesische Zeichen, Rest wird mit Auslassungszeichen angezeigt.	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

Push API v4 – Web-Push-Benachrichtigungen per JSON versenden

Anfrage-Limits

Authentifizierung der Anfragen

API-Endpunkt

Beispielanfragen

Anfrageparameter

from

Beispielanfrage

to

Push-Ziel

Beispielanfragen

body

platform

notification

web

message

options

multi_language

Anfrageparameter

Beispielanfrage

Beispielantwort

web_buttons

third_party_channel

request_id

Beispiel

custom_args

Antwortparameter

Antwort bei Erfolg

Fehlerantwort

Antwort

HTTP-Statuscodes

Rückgabecodes

Push-Beschränkungen

Sprachcodes