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, Viber, WhatsApp) verwendet wird.

Payload

preset (string): Code einer Push-Voreinstellung (Format XXXXX-XXXXX), die auf diese Nachricht angewendet wird.
sms_preset (string): Code (Format XXXXX-XXXXX) einer gespeicherten SMS-Voreinstellung. Der Text pro Locale wird in den sms.body jeder Locale aufgelöst. Ein inline sms.body für eine bestimmte Locale überschreibt die Voreinstellung für diese Locale. Die Voreinstellung muss zur selben Anwendung wie die Nachricht gehören.
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): Freiform-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.

{
  "payload": {
    "preset": "XXXXX-XXXXX",
    "content": { "localized_content": { "default": { "ios": { "title": "Hello", "body": "Tap to view" } } } },
    "custom_data": { "order_id": "42" },
    "open_action": { "link": { "url": "https://example.com/promo" } }
  }
}

LocalizedContent

Ordnet Locale-Code → plattformspezifischem Inhalt zu. Schlüssel sind zweibuchstabige ISO 639-1-Codes (z. B. "en", "es") plus der spezielle Schlüssel "default" für eine allgemeine Übersetzung. Die Ausnahmen zu 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:

Genaue Ü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 Schlüssel "default" oder "en" an, damit jedes Gerät einen deterministischen Fallback hat. Wenn Sie keine Varianten pro Locale erwarten, senden Sie nur "default".

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

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
`viber`	Viber-Nachricht
`whatsapp`	WhatsApp-Nachricht
`sms`	SMS-Nachricht

Allgemeine Push-Felder

Diese Felder werden von den Blöcken ios, android, huawei_android, baidu_android, mac_os, amazon, safari, chrome und firefox geteilt (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 (duration, z. B. "3600s"): Wie lange der Push-Server die Benachrichtigung für ein Offline-Gerät aufbewahren soll.
sound (string): Name der Sound-Datei.
sound_enabled (bool): Ton aktivieren oder unterdrücken.
badges (string): Badge-Anzahl (iOS) oder Äquivalent.
root_params (object): Rohe plattformspezifische Payload-Überschreibungen.
inbox (Inbox): Eintrag im Nachrichten-Posteingang.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "time_to_live": "3600s",
    "sound": "default",
    "sound_enabled": true,
    "badges": "+1"
  }
}

iOS (`ios`)

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

{
  "ios": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "attachment": "https://cdn.example.com/image.png",
    "interruption_level": "active",
    "thread_id": "promo"
  }
}

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

icon (string): Kleines Symbol der Benachrichtigung.
banner (string): URL für großes Bild.
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-Schlüssel. Benachrichtigungen mit demselben collapse_key ersetzen sich gegenseitig, während das Gerät offline ist.

{
  "android": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "ic_notification",
    "banner": "https://cdn.example.com/banner.png",
    "led_color": "#FF0000",
    "priority": "PRIORITY_HIGH",
    "delivery_priority": "HIGH"
  }
}

macOS (`mac_os`)

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

{
  "mac_os": {
    "title": "Hello",
    "body": "Tap to view",
    "subtitle": "New update",
    "action": "https://example.com/promo"
  }
}

Amazon (`amazon`)

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

{
  "amazon": {
    "title": "Hello",
    "body": "Tap to view",
    "custom_icon": "https://cdn.example.com/icon.png",
    "priority": "PRIORITY_HIGH"
  }
}

Safari (`safari`)

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

{
  "safari": {
    "title": "Hello",
    "body": "Tap to view",
    "action": "https://example.com/promo",
    "url_arguments": ["promo", "2026"]
  }
}

Chrome (`chrome`)

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

{
  "chrome": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png",
    "image": "https://cdn.example.com/banner.png",
    "duration": "20s",
    "button_text1": "Open",
    "button_url1": "https://example.com/promo"
  }
}

Firefox (`firefox`)

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

{
  "firefox": {
    "title": "Hello",
    "body": "Tap to view",
    "icon": "https://cdn.example.com/icon.png"
  }
}

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.

{
  "telegram": {
    "body": "Hello from Pushwoosh",
    "content_variables": "{\"name\":\"John\"}"
  }
}

Kakao (`kakao`)

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

{
  "kakao": {
    "content": "Hello from Pushwoosh",
    "template": "welcome_v1",
    "content_variables": "{\"name\":\"John\"}"
  }
}

LINE (`line`)

content (string): Reiner Textkörper.
template (string): Code einer im Pushwoosh Control Panel konfigurierten LINE-Vorlage (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.

{
  "line": {
    "content": "Hello from Pushwoosh",
    "template": "promo_carousel"
  }
}

Viber (`viber`)

Eine Viber-Nachricht ist entweder ein Freitext oder eine vorab genehmigte transaktionale Vorlage (Omni Messaging / MStat), auf die per ID und Sprache verwiesen wird.

body (string): Reine Textnachricht. Erforderlich, wenn template_id nicht gesetzt ist.
template_id (string): ID einer vorab genehmigten transaktionalen Vorlage. Wenn gesetzt, hat sie Vorrang vor body.
template_lang (string): Locale der Vorlage. Erforderlich, wenn template_id gesetzt ist.
template_params (map<string, string>): Schlüssel/Wert-Bindungen, die in die Vorlage eingesetzt werden, z. B. { "name": "John", "code": "123456" }.
all_devices (bool): false (Standard) liefert nur an das primäre Gerät des Benutzers; true liefert an alle Geräte des Benutzers.

Mindestens eines von body oder template_id muss gesetzt sein. Wenn template_id gesetzt ist, ist template_lang erforderlich.

Adressieren Sie Viber-Empfänger als HWIDs im Format viber:<phone> (E.164), zum Beispiel viber:+1234567890.

Reiner Text:

{
  "viber": {
    "body": "Hello from Pushwoosh"
  }
}

Transaktionale Vorlage:

{
  "viber": {
    "template_id": "e3dec4a0-c063-4b0f-96d5-cf9d629a7abe",
    "template_lang": "en",
    "template_params": {
      "name": "John",
      "code": "123456",
      "expires_in": "5 minutes"
    },
    "all_devices": false
  }
}

WhatsApp (`whatsapp`)

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

content (string): Freitextnachricht. 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): Locale der Vorlage, die genau 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, nach Schaltflächenindex geschlüsselt, z. B. "{\"0\":\"https://...\"}".
header_variables (string): JSON-Objekt, das Platzhalter im Header abbildet, nach Typ geschlüsselt, z. B. "{\"image\":\"https://...\"}".

Mindestens eines von content oder content_id muss gesetzt sein.

{
  "whatsapp": {
    "content_id": "hello_world",
    "language": "en_US",
    "content_variables": "{\"1\":\"John\"}"
  }
}

SMS (`sms`)

SMS hat seinen eigenen Plattform-Block innerhalb des Content jeder Locale, neben ios, android und den anderen Messaging-Kanälen.

body (string): SMS-Text für die Locale. Erforderlich, wenn der sms-Block vorhanden ist.

Es gibt zwei Möglichkeiten, den Text bereitzustellen:

Inline — sms.body pro Locale in localized_content setzen.
Aus einer Voreinstellung — den sms_preset auf Payload-Ebene auf den Code (Format XXXXX-XXXXX) einer gespeicherten SMS-Voreinstellung setzen. Der Inhalt pro Locale wird in sms.body für jede Locale aufgelöst, die die Voreinstellung definiert. Ein inline sms.body für eine Locale überschreibt die Voreinstellung für diese Locale, sodass Sie eine Voreinstellung wiederverwenden und dennoch einzelne Sprachen anpassen können.

{
  "payload": {
    "sms_preset": "XXXXX-XXXXX",
    "content": {
      "localized_content": {
        "default": { "sms": { "body": "Your order has shipped." } },
        "es":      { "sms": { "body": "Tu pedido ha sido enviado." } }
      }
    }
  }
}

OpenAction

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

Genau eines 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.

{
  "open_action": {
    "deep_link": { "code": "flow-code", "params": { "promo": "summer" } }
  }
}

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 Nachrichten-Posteingang 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 (timestamp): Zeitpunkt, zu dem 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)

Viber (viber)

WhatsApp (whatsapp)

SMS (sms)