Payload-Referenz

Referenz für die Payload-Nachricht, die von Notify beim Senden über einen beliebigen Nicht-E-Mail-Kanal (Push, SMS, Telegram, Kakao, LINE, WhatsApp) verwendet wird.

Payload

preset (string): Preset-Code, der auf diese Nachricht angewendet wird.
content (LocalizedContent): Nachrichteninhalt. Schließt sich gegenseitig mit silent aus.
silent (bool): Sendet einen stillen (nur Daten) Push. Schließt sich gegenseitig mit content aus.
custom_data (object): Frei gestaltbares JSON, das als u-Parameter an das Client-SDK weitergeleitet wird.
open_action (OpenAction): Aktion, die ausgelöst wird, wenn der Benutzer die Benachrichtigung öffnet.
open_actions (map<Platform, OpenAction>): Plattformspezifische Überschreibung von open_action. Der Schlüssel ist ein numerischer Platform-Enum-Wert.
voip_push (bool): iOS-VoIP-Benachrichtigung.

LocalizedContent

Ordnet Locale-Code → plattformspezifischen Inhalt zu. Schlüssel sind ISO 639-1-Zweibuchstabencodes (zum Beispiel "en", "es") plus der spezielle Schlüssel "default" für eine Catch-all-Übersetzung. Die Ausnahmen von ISO 639-1 sind "zh-Hant" und "zh-Hans" für traditionelles und vereinfachtes Chinesisch.

{
  "localized_content": {
    "default": {
      "ios":     { "title": "Hello", "body": "Tap to view" },
      "android": { "title": "Hello", "body": "Tap to view" }
    },
    "es": {
      "ios":     { "title": "Hola",  "body": "Toca para ver" },
      "android": { "title": "Hola",  "body": "Toca para ver" }
    }
  }
}

Locale-Auswahl für ein Gerät

Der an ein Gerät gelieferte Inhalt wird in dieser Reihenfolge ausgewählt:

Exakte Übereinstimmung mit der Sprache des Geräts.
Schlüssel "default".
Schlüssel "en".
Jede andere in der Map vorhandene Locale.

Geben Sie mindestens einen der Werte "default" oder "en" an, damit jedes Gerät einen deterministischen Fallback hat. Wenn Sie keine sprachspezifischen Varianten erwarten, senden Sie nur "default".

Jeder Locale-Eintrag ist ein Content-Objekt mit optionalen plattformspezifischen Blöcken. Füllen Sie nur die Plattformen aus, auf die Sie abzielen.

Plattform-Block	Kanal
`ios`	iOS-Push
`android`	Android (FCM)-Push
`huawei_android`	Huawei-Android-Push
`baidu_android`	Baidu-Android-Push
`mac_os`	macOS-Push
`amazon`	Amazon (ADM)-Push
`safari`	Safari-Web-Push
`chrome`	Chrome-Web-Push
`firefox`	Firefox-Web-Push
`ie`	Internet Explorer-Web-Push
`windows`	Windows-Push (Kachel / Toast / Badge)
`telegram`	Telegram-Nachricht
`kakao`	Kakao-Nachricht
`line`	LINE-Nachricht
`whatsapp`	WhatsApp-Nachricht

Allgemeine Push-Felder

Diese Felder werden von den Blöcken ios, android, huawei_android, baidu_android, mac_os, amazon, safari, chrome und firefox gemeinsam genutzt (Unterstützung variiert. Nicht verwendete Felder werden von der jeweiligen Plattform ignoriert).

title (string): Titel der Benachrichtigung.
body (string): Text der Benachrichtigung.
time_to_live (Dauer, z. B. "3600s"): Wie lange der Push-Server die Benachrichtigung für ein Offline-Gerät aufbewahren soll.
sound (string): Name der Sounddatei.
sound_enabled (bool): Ton aktivieren oder unterdrücken.
badges (string): Badge-Anzahl (iOS) oder Äquivalent.
root_params (object): Rohe plattformspezifische Payload-Überschreibungen.
inbox (Inbox): Message Inbox-Eintrag.

iOS (`ios`)

subtitle (string): Untertitel der iOS-Benachrichtigung.
is_critical (bool): Kritischer Alarm (erfordert Berechtigung).
attachment (string): URL eines Medienanhangs.
thread_id (string): Thread-Identifier für gruppierte Benachrichtigungen.
trim_content (bool): Inhalt kürzen, damit er passt.
category_id (string): UNNotificationCategory-Identifier für interaktive Aktionen.
interruption_level (string): passive, active, time-sensitive oder critical.
collapse_id (string): APNs-Collapse-Identifier. Benachrichtigungen mit derselben collapse_id ersetzen sich gegenseitig auf dem Gerät.

Android (`android`, `huawei_android`, `baidu_android`)

icon (string): Kleines Symbol der Benachrichtigung.
banner (string): Big-Picture-URL.
delivery_priority (NORMAL | HIGH): FCM-Zustellpriorität.
vibration (bool): Vibration bei Empfang.
led_color (string, hex): LED-Farbe der Benachrichtigung.
icon_background_color (string, hex): Hintergrundfarbe des Symbols.
show_on_lockscreen (bool): Auf dem Sperrbildschirm anzeigen.
custom_icon (string): URL eines benutzerdefinierten Symbols.
priority (NotificationPriority): Priorität in der Benachrichtigungsleiste.
group_id (string): Gruppenschlüssel der Benachrichtigung.
collapse_key (string): FCM-Collapse-Key. Benachrichtigungen mit demselben collapse_key ersetzen sich gegenseitig, während das Gerät offline ist.

macOS (`mac_os`)

Verwendet die allgemeinen Push-Felder plus subtitle und action (URL, die geöffnet wird, wenn der Benutzer auf die Benachrichtigung klickt).

Amazon (`amazon`)

Verwendet die allgemeinen Push-Felder plus custom_icon und priority (NotificationPriority).

Safari (`safari`)

action (string): URL, die geöffnet wird, wenn der Benutzer auf die Benachrichtigung klickt.
url_arguments (Array von Strings): Safari-URL-Argumente, die in die Web-Push-URL-Vorlage eingesetzt werden.

Chrome (`chrome`)

icon, image (string): URLs für kleines Symbol und großes Bild.
duration (Dauer): Timer zum automatischen Schließen.
button_text1 / button_url1, button_text2 / button_url2: Bis zu zwei Aktionsschaltflächen.

Firefox (`firefox`)

Verwendet nur title, body, icon, root_params und inbox.

Windows (`windows`)

Windows verwendet eine andere Struktur:

{
  "windows": {
    "type": "TOAST",
    "template": { "title": "Hello", "body": "Tap to view" },
    "tag": "promo",
    "cache": true,
    "time_to_live": "3600s"
  }
}

type ist TILE, TOAST oder BADGE.
template (strukturiert) oder raw ({ "content": "<raw xml>" }) — genau eines von beiden.

Telegram (`telegram`)

body (string): Nachrichtentext.
content_variables (string): JSON-stringifizierte Variablen für die Bot-seitige Vorlage.

Kakao (`kakao`)

content (string): Nachrichteninhalt.
template (string): Genehmigter Vorlagencode.
content_variables (string): JSON-stringifizierte Vorlagenvariablenbindungen.

LINE (`line`)

content (string): Reiner Textkörper.
template (string): Code einer LINE-Vorlage, die im Pushwoosh Control Panel konfiguriert ist (wird zum Senden von Bild-, Karussell- oder Flex-Nachrichten verwendet). Für Rich Content konfigurieren Sie die Vorlage im Control Panel vor und verweisen Sie hier darauf.

Mindestens eines von content oder template muss gesetzt sein.

WhatsApp (`whatsapp`)

WhatsApp-Nachrichten laufen über Meta und unterliegen den Messaging-Regeln von Meta. Die wesentliche Unterscheidung besteht zwischen frei formuliertem Text (der nur innerhalb des 24-Stunden-Kundenservice-Fensters zugestellt wird, das durch eine eingehende Nachricht des Benutzers geöffnet wird) und genehmigten Vorlagen (die für die Initiierung von ausgehenden Nachrichten und für jede Nachricht außerhalb des 24-Stunden-Fensters erforderlich sind).

content (string): Frei formulierter Nachrichtentext. Wird von Meta nur innerhalb des 24-Stunden-Fensters zugestellt.
content_id (string): Name einer vorab genehmigten Meta-Vorlage (z. B. "hello_world"). Erforderlich für die Initiierung von ausgehenden Nachrichten oder jede Nachricht außerhalb des 24-Stunden-Fensters.
language (string): Vorlagen-Locale, die exakt mit der in Meta genehmigten Locale übereinstimmen muss (z. B. "en_US", "en_GB"). Nur in Verbindung mit content_id sinnvoll. Dies ist unabhängig vom äußeren LocalizedContent-Schlüssel. Der äußere Schlüssel wählt den Inhalt für ein Gerät aus, und language wählt die Meta-Vorlagen-Locale für diesen Inhalt aus.
content_variables (string): JSON-Objekt, das Platzhalter im Textkörper abbildet, z. B. "{\"1\":\"John\"}".
button_url_variables (string): JSON-Objekt, das Platzhalter für Schaltflächen-URLs abbildet, die nach dem Index der Schaltfläche geschlüsselt sind, z. B. "{\"0\":\"https://...\"}".
header_variables (string): JSON-Objekt, das Platzhalter im Header abbildet, die nach Typ geschlüsselt sind, z. B. "{\"image\":\"https://...\"}".

Mindestens eines von content oder content_id muss gesetzt sein.

SMS

SMS verwendet den generischen Nachrichtenfluss. Der sms-Plattformblock ist reserviert. Geben Sie den Text über das allgemeine body-Feld in einem beliebigen ausgefüllten Plattformblock an. Absender-ID und andere Anbieteroptionen stammen aus der SMS-Konfiguration der App. Siehe SMS-Konfiguration.

OpenAction

Definiert die Aktion, die ausgeführt wird, wenn der Benutzer die Nachricht öffnet.

Genau einer von:

rich_media (RichMedia): Öffnet eine Rich Media-Seite.
deep_link: Öffnet einen Deep Link: { "code": "flow-code", "params": { "key": "value" } }.
link (Link): Öffnet eine URL.

RichMedia

{ "code": "XXXXX-XXXXX" }        // nach Rich Media-Code
{ "url":  "https://..." }        // nach Remote-URL

Link

{
  "url": "https://example.com/promo",
  "shortener": "BITLY"
}

shortener ist NONE (Standard) oder BITLY.

Inbox

Konfiguriert, wie die Nachricht im Message Inbox erscheint.

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expiration_date": "2026-05-15T00:00:00Z"
}

image_url (string): Bild, das im Posteingangseintrag angezeigt wird.
expiration_date (Zeitstempel): Wann der Eintrag aus dem Posteingang entfernt wird.

NotificationPriority-Enum

Steuert die Benachrichtigungspriorität auf dem Zielgerät, von PRIORITY_MIN (niedrigste) bis PRIORITY_MAX (höchste).

PRIORITY_UNSPECIFIED
PRIORITY_MIN
PRIORITY_LOW
PRIORITY_DEFAULT
PRIORITY_HIGH
PRIORITY_MAX

Beispiel: Senden eines Pushes an ein Segment

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "title": "Hello",   "body": "Hello, world!" },
              "android": { "title": "Hello",   "body": "Hello, world!" }
            },
            "es": {
              "ios":     { "title": "¡Hola!",  "body": "¡Hola, mundo!" },
              "android": { "title": "¡Hola!",  "body": "¡Hola, mundo!" }
            }
          }
        },
        "open_action": { "link": { "url": "https://example.com/promo" } }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

Beispiel: Transaktionaler Push nach Benutzer-IDs

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["customer-42"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "ios":     { "title": "Your order", "body": "Order #42 has shipped." },
              "android": { "title": "Your order", "body": "Order #42 has shipped." }
            }
          }
        },
        "custom_data": { "order_id": "42" }
      },
      "schedule":     { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL"
    }
  }'

Payload-Referenz

Payload

LocalizedContent

Locale-Auswahl für ein Gerät

Allgemeine Push-Felder

iOS (ios)

Android (android, huawei_android, baidu_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

WhatsApp (whatsapp)

SMS