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.

Hinweis

Für E-Mails siehe die E-Mail-Payload-Referenz.

Payload

• preset (string): Code eines Push-Presets (Format XXXXX-XXXXX), das auf diese Nachricht angewendet werden soll.
• sms_preset (string): Code (Format XXXXX-XXXXX) eines gespeicherten SMS-Presets. Sein Text pro Gebietsschema wird in den sms.body jedes Gebietsschemas aufgelöst. Ein inline sms.body für ein bestimmtes Gebietsschema überschreibt das Preset für dieses Gebietsschema. Das Preset 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

Mappt Gebietsschemacode → plattformspezifischer Inhalt. Schlüssel sind zweibuchstabige ISO 639-1-Codes (zum Beispiel "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" }
    }
  }
}

Auswahl des Gebietsschemas für ein Gerät

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

1. Genaue Übereinstimmung mit der Sprache des Geräts.
2. Schlüssel "default".
3. Schlüssel "en".
4. Jedes andere in der Map vorhandene Gebietsschema.

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

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

Plattformblock	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 gemeinsam genutzt (die Unterstützung variiert. Nicht verwendete Felder werden von der jeweiligen Plattform ignoriert).

• title (string): Titel der Benachrichtigung.
• body (string): Textkörper 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 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): Eintrag im Message Inbox.

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

iOS (ios)

• subtitle (string): iOS-Benachrichtigungsuntertitel.
• is_critical (bool): kritischer Alarm (erfordert Berechtigung).
• attachment (string): URL eines Medienanhangs.
• thread_id (string): Thread-Kennung für gruppierte Benachrichtigungen.
• trim_content (bool): Inhalt passend zuschneiden.
• category_id (string): UNNotificationCategory-Kennung für interaktive Aktionen.
• interruption_level (string): passive, active, time-sensitive oder critical.
• collapse_id (string): APNs-Collapse-Kennung. 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 Benachrichtigungssymbol.
• 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 im Posteingang.
• group_id (string): Benachrichtigungsgruppenschlüssel.
• 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 sowie 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 sowie 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 Form:

{
  "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 davon.

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): einfacher 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.

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

Viber (viber)

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

• body (string): einfache 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): Gebietsschema 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:<Telefon> (E.164), zum Beispiel viber:+1234567890.

Einfacher 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 (der nur innerhalb des 24-stündigen Kundenservice-Fensters zugestellt wird, das durch eine eingehende Nachricht des Benutzers geöffnet wird) und genehmigten Vorlagen (erforderlich für die ausgehende Initiierung 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 ausgehende Initiierung oder jede Nachricht außerhalb des 24-Stunden-Fensters.
• language (string): Gebietsschema der Vorlage, das genau dem in Meta genehmigten Gebietsschema entsprechen muss (z. B. "en_US", "en_GB"). Nur in Verbindung mit content_id von Bedeutung. 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 das Meta-Vorlagen-Gebietsschema für diesen Inhalt aus.
• content_variables (string): JSON-Objekt, das Platzhalter im Textkörper mappt, z. B. "{\"1\":\"John\"}".
• button_url_variables (string): JSON-Objekt, das Platzhalter für Schaltflächen-URLs nach Schaltflächenindex mappt, z. B. "{\"0\":\"https://...\"}".
• header_variables (string): JSON-Objekt, das Platzhalter im Header nach Typ mappt, 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 Plattformblock innerhalb des Content jedes Gebietsschemas, neben ios, android und den anderen Messaging-Kanälen.

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

Es gibt zwei Möglichkeiten, den Text bereitzustellen:

• Inline – sms.body pro Gebietsschema in localized_content setzen.
• Aus einem Preset – den sms_preset auf Payload-Ebene auf den Code (Format XXXXX-XXXXX) eines gespeicherten SMS-Presets setzen. Sein gebietsschemaspezifischer Inhalt wird in sms.body für jedes vom Preset definierte Gebietsschema aufgelöst. Ein inline sms.body für ein Gebietsschema überschreibt das Preset für dieses Gebietsschema, sodass Sie ein Preset 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." } }
      }
    }
  }
}

MMS

Das Hinzufügen von subject und file_urls zu einem sms-Block macht die Nachricht zu einer MMS. Nur AbleMobile hat einen MMS-Endpunkt – andere SMS-Anbieter ignorieren beide Felder und liefern nur den reinen Text-body.

• subject (string): MMS-Betreff. Erfordert mindestens einen Eintrag in file_urls – ein Betreff ohne Anhänge wird abgelehnt. Bis zu 40 ASCII-Zeichen oder 13 Zeichen, wenn der Betreff Nicht-ASCII-Zeichen enthält.
• file_urls (array of string): bis zu 3 Anhang-URLs. Jede muss eine absolute https URL sein, die auf .jpg oder .gif endet – .jpeg und .png werden von der Validierung abgelehnt, selbst für eine echte JPEG- oder PNG-Datei, da der Anbieter sie nicht dekodieren kann. Jede Datei muss außerdem 200 KB oder kleiner sein; AbleMobile lehnt den gesamten Sendevorgang ab, wenn ein Anhang schwerer ist.
• message_at (int): Index in file_urls (0-basiert), nach dem der SMS-Textkörper angezeigt wird.

subject und file_urls unterstützen die Liquid-Personalisierung, genau wie body.

{
  "sms": {
    "body": "Your order has shipped.",
    "subject": "Order update",
    "file_urls": [
      "https://cdn.example.com/shipping-label.jpg",
      "https://cdn.example.com/tracking-map.gif"
    ],
    "message_at": 1
  }
}

OpenAction

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

Genau eines von:

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

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

Die Deep-Link-URL und die params-Werte unterstützen die Syntax der Liquid-Personalisierung – Ausdrücke werden aufgelöst, bevor der Deep Link geöffnet wird.

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 (timestamp): 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

Vorsicht

Senden Sie priority immer als einen der oben genannten Zeichenfolgenwerte. Die API akzeptiert auch die numerischen Äquivalente des Enums (1-5, entsprechend der obigen Reihenfolge), aber diese Zuordnung ist ein internes Protobuf-Detail und kein unterstützter Vertrag – verlassen Sie sich nicht darauf.

Ein nicht erkannter priority-Wert (eine falsch geschriebene Zeichenfolge oder eine Zahl außerhalb des Bereichs) wird nicht abgelehnt: Die API verwirft ihn stillschweigend, und die Benachrichtigung wird ohne priority-Feld gesendet, anstatt einen Fehler zurückzugeben.

Beispiel: Senden eines Push 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"
    }
  }'