Presets-API

Ein Push-Preset ist eine wiederverwendbare Vorlage für Push-Benachrichtigungen – dasselbe Objekt, das Sie im Push-Editor des Control Panels erstellen. Diese API verwaltet nur Push-Presets; SMS-, WhatsApp-, Kakao-, LINE- und Viber-Presets haben jeweils ihren eigenen dedizierten Preset-Dienst, der hier nicht behandelt wird.

Verwenden Sie den code eines Presets, um es über Notify (Payload preset) oder einen „Push senden“-Knotenpunkt einer Customer Journey zu senden.

Basis-URL

https://rpc-api.svc-nue.pushwoosh.com

Alle Endpunkte werden über HTTPS bereitgestellt. Anfragen und Antworten verwenden application/json, sofern nicht anders angegeben.

Authentifizierung

Jede Anfrage muss einen Authorization-Header mit Ihrem Server-API-Token enthalten:

Authorization: Api IHR_API_TOKEN

Konventionen

• Feldnamen: Anfrage-Bodys und Abfrage-/Pfadparameter akzeptieren lowerCamelCase (zum Beispiel sendType, localizedProperties, searchByName) – der Server verarbeitet beide Schreibweisen. Antworten werden immer mit den Proto-Feldnamen in snake_case formatiert (localized_properties, platform_properties, per_page usw.). Die Antwortbeispiele und die Referenz zum Preset-Objekt unten verwenden diese Schreibweise.
• code: Jede Preset-Antwort enthält ihren eigenen Code, der bei Create generiert wird. Übergeben Sie diesen Code an Get, Update, UpdatePartial, Delete, Clone und an die oben genannten Messaging-/Journey-APIs.
• Plattform-Schlüssel: Die Maps platforms und open_actions verwenden den numerischen Gerätetyp-Code als Schlüssel (1 für iOS, 3 für Android usw.). platform_properties verwendet stattdessen den Enum-Namen der Plattform als Schlüssel (IOS, ANDROID, HUAWEI_ANDROID, OSX – die einzigen vier Plattformen, die es abdeckt).
• Nicht gefüllte Felder: Die Antworten von Get, Create und Clone enthalten jedes Feld des Preset-Objekts, auch wenn es leer ist oder den Wert null hat. List gibt einen reduzierten Feldsatz zurück – siehe Auflisten unten. Update und UpdatePartial geben überhaupt keine Preset-Felder zurück – siehe die Warnung in ihren Abschnitten.

Fehlerantworten

HTTP-Status	Bedeutung
400 Bad Request	Ungültiges Argument – ein erforderliches Feld fehlt oder ist fehlerhaft, oder eine Vorbedingung ist fehlgeschlagen (z. B. Klonen ohne name).
401 Unauthorized	Fehlender oder ungültiger Authorization-Header.
403 Forbidden	Die Anwendung oder das Preset gehört nicht zum Konto des Aufrufers.
404 Not Found	Das Preset oder die Anwendung wurde nicht gefunden.
500 Internal Server Error	Unerwarteter serverseitiger Fehler.

Ein Delete-Aufruf für ein Preset, das noch von einem „Push senden“-Knotenpunkt in einer laufenden oder pausierten Journey verwendet wird, gibt ebenfalls 400 Bad Request zurück (ein FailedPrecondition auf der Leitung) – nicht 409. Entfernen Sie das Preset zuerst aus der Journey.

Create, Update und UpdatePartial geben ebenfalls 400 Bad Request für ein nicht auflösbares Personalisierungs-Token zurück – siehe unten.

Personalisierungs-Token

Create, Update und UpdatePartial validieren jedes Personalisierungs-Token ({name|modifier|default}) in localizedTitle, localizedSubtitle und localizedContent (für jede Sprache in der Anfrage) und in den Rich-Content-Feldern pro Plattform, die der Absender ersetzt (Titel, Inhalt, Banner, Symbol, URL, Deep-Link-Parameter usw. für jede Plattform). Felder außerhalb dieses Satzes, wie richmedia, campaignCode, deeplink oder filterCode, behalten ein Token genau wie geschrieben – Pushwoosh parst dort keine Personalisierungssyntax.

Ein Token benötigt einen von Pushwoosh erkannten Modifikator, da ein nicht modifiziertes oder falsch geschriebenes Token nicht formatiert werden kann und sonst die Benutzer als literale geschweifte Klammern erreichen würde. Ein Token mit einem fehlenden oder unbekannten Modifikator ({Tag|}, {Tag|typo}) führt zum Fehlschlagen des Aufrufs mit InvalidArgument:

{
  "code": 3,
  "message": "personalization token {Tag|} has no known modifier, so it would be delivered as text; expected one of [capitalizefirst capitalizeallfirst uppercase lowercase regular base64 cent dollar comma euro jpy lira M-d-y m-d-y M d y M d Y l M d H:i m-d-y H:i]"
}

Vorsicht

Bei UpdatePartial wird diese Prüfung gegen den gesamten gespeicherten Satz von ersetzten Inhaltsfeldern des Presets durchgeführt, nicht nur gegen die Felder in der aktuellen Anfrage – ein Preset, das bereits ein fehlerhaftes Token in einem unberührten Feld hat, lässt jeden nachfolgenden UpdatePartial-Aufruf fehlschlagen, bis dieses Token korrigiert ist. localizedTitle, localizedSubtitle und localizedContent sind die Ausnahme: Sie werden nur geprüft, wenn derselbe Aufruf sie enthält.

Akzeptierte Modifikatoren

Der Personalisierungs-Picker im Control Panel bietet bereits alle unten aufgeführten Modifikatoren für INTEGER/PRICE-Tags (einschließlich der Datumsformate) und für String-Tags an, außer base64 – dieser ist nur über die API erreichbar. gitlab.corp.pushwoosh.com/channels/sdk/pkg/dynamiccontent ist die Quelle der Wahrheit, gegen die sowohl das Control Panel als auch diese API validieren.

Modifikator	Tag-Typ	Anmerkungen
capitalizefirst	string	Groß-/Kleinschreibung wird nicht beachtet
capitalizeallfirst	string	Groß-/Kleinschreibung wird nicht beachtet
uppercase	string	Groß-/Kleinschreibung wird nicht beachtet
lowercase	string	Groß-/Kleinschreibung wird nicht beachtet
regular	string oder integer	Groß-/Kleinschreibung wird nicht beachtet, keine Formatierung angewendet
base64	string	Groß-/Kleinschreibung wird nicht beachtet, nur API – wird nicht vom CP-Picker angeboten
cent / dollar / comma / euro / jpy / lira	integer	Groß-/Kleinschreibung wird nicht beachtet
M-d-y, m-d-y, M d y, M d Y, l, M d, H:i, m-d-y H:i	integer	Datumsformat-Modifikatoren, exakt wie geschrieben abgeglichen, einschließlich Groß-/Kleinschreibung

Endpunkte

Methode	Pfad	Beschreibung
POST	/api/presets	Ein neues Push-Preset erstellen
GET	/api/presets	Push-Presets einer Anwendung auflisten
GET	/api/presets/{code}	Ein einzelnes Push-Preset abrufen
PUT	/api/presets/{code}	Ein Push-Preset aktualisieren (vollständiges Überschreiben)
PUT	/api/presets/{code}:partial	Ein Push-Preset teilweise aktualisieren
POST	/api/presets/{code}:clone	Ein Push-Preset klonen
DELETE	/api/presets/{code}	Ein Push-Preset löschen

Erstellen

Erstellt ein neues Push-Preset in einer Anwendung und gibt es mit seinem generierten Code zurück.

POST /api/presets

Anfrage-Body

Parameter	Typ	Erforderlich	Beschreibung
application	string	Ja	Der Anwendungscode, in dem das Preset erstellt werden soll.
name	string	Ja	Name des Presets.
sendType	string	Nein	Kanal des Presets (z. B. push).
isV2	boolean	Nein	Setzt das Ursprungs-Flag des Presets. Weglassen, um den Standardwert true (v2) zu verwenden; setzen Sie false nur, wenn Sie ein altes v1-Preset reproduzieren.

Alle anderen Felder – lokalisierter Inhalt, Plattformen, Deep-Link, Inbox, Kategorien usw. – werden mit Update geteilt und sind einmalig in der Referenz zum Preset-Objekt unten dokumentiert.

Anfragebeispiel

{
  "application": "XXXXX-XXXXX",
  "name": "20% Rabatt",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Holen Sie sich jetzt Ihren 20% Rabatt",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Hallo" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

Antwort

Gibt { "preset": { ... } } zurück, das erstellte Preset-Objekt.

Auflisten

Listet die Push-Presets einer Anwendung auf – ein reduzierter Feldsatz, nicht das vollständige Objekt – mit Paginierung, Sortierung und Filterung nach Name oder Kategorie.

GET /api/presets

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
application	string	Ja	Der Anwendungscode, für den Presets aufgelistet werden sollen.
orderBy	string	Nein	NAME (Standard), CREATED oder UPDATED.
orderDirection	string	Nein	ASC (Standard) oder DESC.
page	integer	Nein	Nullbasierter Seitenindex.
perPage	integer	Nein	Seitengröße. Standardmäßig 100, wenn weggelassen oder 0.
searchByName	string	Nein	Groß-/kleinschreibungsunabhängige Teilstring-Suche nach Preset-Name oder Code (ILIKE %value%).
searchByCategory	array of strings	Nein	Wiederholen Sie den Parameter, um nach mehreren Kategorien zu filtern, z. B. ?searchByCategory=promo&searchByCategory=lifecycle.
showHidden	boolean	Nein	Schließt als hidden markierte Presets ein.

Hinweis

isDefault ist ein veralteter Filter, der nur für das alte „Push senden“-Formular im Control Panel beibehalten wird – verlassen Sie sich nicht darauf.

Antwort

Jeder Eintrag enthält nur: name, code, platforms, localized_content (einfacher Text pro Locale – nicht localized_properties), localized_title, localized_subtitle, banner, icon, categories, journey_uuid, custom_data, is_v2, created, updated. Jedes andere Feld des Preset-Objekts – localized_properties, platform_properties, deeplink, richmedia, url usw. – wird weggelassen, auch wenn es im Preset gesetzt ist.

Feld	Typ	Beschreibung
presets	array of objects	Die aktuelle Seite der Presets in der oben beschriebenen reduzierten Form.
page	integer	Der zurückgegebene Seitenindex.
per_page	integer	Die für diese Antwort verwendete Seitengröße.
total	integer	Gesamtzahl der Presets, die den Filtern entsprechen, über alle Seiten hinweg.

Antwortbeispiel

{
  "presets": [
    { "name": "20% Rabatt", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Abrufen

Gibt ein einzelnes Push-Preset anhand seines Codes zurück, wobei jedes Feld des Preset-Objekts gefüllt ist.

GET /api/presets/{code}

Pfadparameter

Parameter	Typ	Beschreibung
code	string	Der Code des Presets.

Antwort

Gibt { "preset": { ... } } zurück, das vollständige Preset-Objekt.

Aktualisieren

Überschreibt ein bestehendes Push-Preset anhand seines Codes mit den angegebenen Feldern.

PUT /api/presets/{code}

Pfadparameter

Parameter	Typ	Beschreibung
code	string	Der Code des zu überschreibenden Presets.

Anfrage-Body

Dieselben Felder wie bei Erstellen (ohne application), plus die restlichen Felder des Preset-Objekts. sendType wird akzeptiert, aber ignoriert – der Kanal eines Presets kann nach der Erstellung nicht geändert werden.

Das Weglassen eines Feldes bedeutet nicht immer ‚unverändert lassen‘

Update baut die Inhaltseigenschaften des Presets bei jedem Aufruf von Grund auf neu auf: localizedProperties, platformProperties, openAction/openActions, deeplink, deeplinkParams, richmedia, url, campaignCode, filterCode, geoZones, sendRate, cappingCount/cappingDays, die drei notification*Url-Felder, remotePage, wnsContent, originalUrl, die vier *Silent-Flags, inboxImage/inboxIcon/inboxDays/inboxDate, banner, icon, customData und isV2 – lassen Sie eines dieser Felder weg, wird es gelöscht (oder, bei isV2, auf true zurückgesetzt).

name, platforms, categories, localizedTitle, localizedSubtitle und localizedContent sind die Ausnahme: Jedes wird nur berührt, wenn Sie es senden, und bleibt unverändert, wenn es weggelassen wird.

Verwenden Sie UpdatePartial, wenn Sie möchten, dass die erste Gruppe ebenfalls unverändert bleibt, wenn sie weggelassen wird.

Antwort hat kein Preset-Feld

Update gibt {} zurück – ein leeres Objekt. Die Antwortnachricht definiert technisch gesehen ein preset-Feld, aber der Server füllt es nie. Rufen Sie danach Get auf, wenn Sie das aktualisierte Objekt zurückbenötigen.

Antwort

Ein leeres Objekt bei Erfolg: {}.

Teilweise aktualisieren (UpdatePartial)

Aktualisiert nur die angegebenen Felder eines bestehenden Push-Presets anhand seines Codes und lässt nicht gesetzte Felder unverändert.

PUT /api/presets/{code}:partial

Pfadparameter

Parameter	Typ	Beschreibung
code	string	Der Code des zu patchenden Presets.

Anfrage-Body

Dieselben Felder wie bei Aktualisieren, ohne application. Im Gegensatz zu Update bleibt hier jedes Feld – einschließlich localizedProperties, platformProperties, categories und der restlichen Gruppe von Inhaltseigenschaften, die in der Warnung von Update aufgeführt sind – unverändert, wenn es weggelassen wird, und wird nur berührt, wenn Sie es senden (ein Map-/Array-Feld, das Sie senden, ersetzt immer noch den bestehenden Wert für dieses Feld vollständig, es beeinflusst jedoch nichts, was Sie nicht eingeschlossen haben). sendType wird ebenfalls akzeptiert, aber ignoriert.

Hinweis

isV2 ist auch hier die einzige Ausnahme: Es wird bei jedem UpdatePartial-Aufruf neu geschrieben und standardmäßig auf true gesetzt, wenn es weggelassen wird. Senden Sie explizit isV2: false, wenn das Preset ein Preset im v1-Stil bleiben muss.

Anfragebeispiel

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

Antwort

Ebenfalls ein leeres Objekt – siehe die Warnung oben.

Klonen

Dupliziert ein bestehendes Push-Preset unter einem neuen Namen in die gleiche Anwendung.

POST /api/presets/{code}:clone

Hinweis

Im Gegensatz zum Clone der E-Mail-Vorlagen-API hat dieser Endpunkt keinen application-Parameter – er klont immer innerhalb der eigenen Anwendung des Quell-Presets. Der Klon wird immer mit hidden: false erstellt, unabhängig von der Quelle.

Anfrage-Body

Parameter	Typ	Erforderlich	Beschreibung
code	string	Ja	Code des zu duplizierenden Quell-Presets.
name	string	Ja	Name für das neue Preset.

Anfragebeispiel

{ "code": "AAAAA-BBBBB", "name": "20% Rabatt (Kopie)" }

Antwort

Gibt { "preset": { ... } } zurück, das neue Preset-Objekt.

Löschen

Löscht ein Push-Preset anhand seines Codes endgültig.

DELETE /api/presets/{code}

Vorsicht

Schlägt fehl, wenn das Preset noch von einem send_push-Knotenpunkt in einer laufenden oder pausierten Journey verwendet wird – entfernen Sie es zuerst aus der Journey. Dies kann nicht rückgängig gemacht werden.

Pfadparameter

Parameter	Typ	Beschreibung
code	string	Der Code des zu löschenden Presets.

Antwort

Ein leeres Objekt bei Erfolg: {}.

Objektreferenz

Die unten stehenden Feldnamen entsprechen dem, was Get, Create, Update und Clone tatsächlich zurückgeben – snake_case-Proto-Feldnamen (siehe Konventionen). Die in den obigen Anfragebeispielen verwendete lowerCamelCase-Form funktioniert bei der Eingabe auf die gleiche Weise.

Preset-Objekt

Identität

Feld	Typ	Beschreibung
code	string	Wird bei Create generiert. Identifiziert dieses Preset überall sonst in der API.
name	string	Name des Presets.
send_type	string	Kanal des Presets (z. B. push).
is_v2	boolean	true für Presets, die mit dem v2-Inhaltsmodell erstellt oder dorthin migriert wurden.
system	boolean	Markiert das Preset als System-/internes Preset.
hidden	boolean	Verbirgt das Preset in den List-Ergebnissen (senden Sie showHidden: true, um es einzuschließen).
created	string (RFC 3339)	Zeitstempel der Erstellung.
updated	string (RFC 3339)	Zeitstempel der letzten Aktualisierung.

Targeting & Inhalt

Feld	Typ	Beschreibung
platforms	map<string, boolean>	Welche Plattformen das Preset anspricht, als Schlüssel wird der Gerätetyp-Code verwendet (z. B. "1" für iOS).
localized_properties	map<string, object>	Locale → Rich-Content pro Plattform. Gleiche Form wie LocalizedContent in der Notify-Payload – ein Eintrag pro Plattformblock (ios, android usw.). Dies ist die primäre Methode, um plattformspezifischen Push-Inhalt festzulegen.
localized_title / localized_subtitle / localized_content	map<string, string>	Locale → einfacher Text. Eine einfachere Alternative zu localized_properties für Titel, Untertitel und Textkörper, wenn Sie keine plattformspezifischen Überschreibungen benötigen.
platform_properties	map<string, object>	Legacy-Überschreibungen pro Plattform, als Schlüssel wird der Plattform-Enum-Name verwendet (IOS, ANDROID, HUAWEI_ANDROID, OSX). Siehe PlatformProperties-Objekt unten.
open_action	OpenAction	Aktion, die ausgelöst wird, wenn der Benutzer die Benachrichtigung öffnet, angewendet auf jede Plattform. Schließt sich gegenseitig mit open_actions aus – die Antwort setzt genau eines von beiden.
open_actions	map<string, OpenAction>	Plattformspezifische Überschreibung von open_action, als Schlüssel wird der Gerätetyp-Code verwendet.
deeplink	string	Deep-Link-Code.
deeplink_params	map<string, string>	Parameter, die an den Deep-Link übergeben werden.
richmedia	string	Rich-Media-Code, der durch die Benachrichtigung geöffnet wird.
url	string	URL, die durch die Benachrichtigung geöffnet wird, wenn kein Deep-Link oder Rich Media verwendet wird.

Inbox

Feld	Typ	Beschreibung
inbox_image	string	Bild-URL, die im Message-Inbox-Eintrag angezeigt wird.
inbox_icon	string	Symbol-URL, die im Message-Inbox-Eintrag angezeigt wird.
inbox_days	integer	Tage, die der Eintrag in der Message Inbox verbleibt.
inbox_date	string (RFC 3339)	Explizites Ablaufdatum für den Message-Inbox-Eintrag, als Alternative zu inbox_days.

Organisation & Metadaten

Feld	Typ	Beschreibung
categories	array of strings	Kategorienamen, mit denen das Preset getaggt ist.
campaign_code	string	Kampagnencode, dem dieses Preset zugeordnet ist.
filter_code	string	Segment-/Filtercode, den dieses Preset standardmäßig anspricht.
geo_zones	string	Geozone-Targeting, wenn das Preset geo-getriggert ist.
journey_uuid	string	UUID der Customer Journey, der dieses Preset gehört, falls es aus einem „Push senden“-Knotenpunkt einer Journey erstellt wurde.
custom_data	object	Freiform-JSON, das als u-Parameter an das Client-SDK weitergeleitet wird.
banner	string	URL des großen Bildes / Anhangs.
icon	string	URL des benutzerdefinierten Benachrichtigungssymbols.

Zustellungsgrenzen

Feld	Typ	Beschreibung
send_rate	integer	Drosselung für Sendungen, die dieses Preset verwenden, in Nachrichten/Sekunde – das Äquivalent auf Preset-Ebene zu Notifys SendRate.
capping_count / capping_days	integer	Frequenzlimit pro Benutzer für dieses Preset – das Äquivalent auf Preset-Ebene zu Notifys FrequencyCapping count / days.

Webhooks

Feld	Typ	Beschreibung
notification_sent_url	string	Callback-URL, die angefordert wird, wenn eine Benachrichtigung mit diesem Preset gesendet wird.
notification_delivered_url	string	Callback-URL, die angefordert wird, wenn eine Benachrichtigung mit diesem Preset zugestellt wird.
notification_click_url	string	Callback-URL, die angefordert wird, wenn eine Benachrichtigung mit diesem Preset angeklickt wird.

Legacy-Felder

Diese werden aus dem v1-Preset-Modell übernommen. Sie werden eher aus Kompatibilitätsgründen mit dem Control Panel gefüllt als für neue Integrationen.

Feld	Typ	Beschreibung
remote_page	string	Legacy-Referenz auf eine Remote-Seite.
wns_content	string	Legacy-Windows-Toast-Template-JSON, wie es von den v1-Methoden createPreset/getPreset akzeptiert wird.
original_url	string	Der Wert von url vor der Verkürzung, wenn url durch einen verkürzten Link ersetzt wurde.
ios_silent / android_silent / huawei_android_silent	boolean	Plattformspezifische Flags für stille (nur Daten) Push-Benachrichtigungen.

PlatformProperties-Objekt

Felder, die in jedem platform_properties-Eintrag verfügbar sind (IOS, ANDROID, HUAWEI_ANDROID, OSX):

Feld	Typ	Beschreibung
badge	string	Überschreibung der Badge-Anzahl.
sound	string	Name der Sounddatei.
sound_off	boolean	Stummschalten des Benachrichtigungstons.
priority	string	Priorität in der Benachrichtigungsleiste (nur Android/Huawei).
delivery_priority	string	NORMAL oder HIGH Zustellpriorität (nur Android/Huawei).
ios_interruption_level	string	passive, active, time-sensitive oder critical (nur iOS).

Verwandte Themen

Notify

Payload-Referenz

Referenz für Customer-Journey-Knotenpunkte