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, Facebook Messenger) verwendet wird.

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 an alle Plattformen. Schließt sich gegenseitig mit content aus. Um nur einige Plattformen still zu schalten, setzen Sie stattdessen silent innerhalb von content für iOS oder Android.
custom_data (object): Freiform-JSON, das als u-Parameter an das Client-SDK weitergeleitet wird. Sehr große Ganzzahlen können an Genauigkeit verlieren, siehe Große Ganzzahlen in benutzerdefinierten Daten.
custom_data_raw (string): Ein String, der ein JSON-Objekt enthält und als u-Parameter an das Client-SDK weitergeleitet wird. Zahlen darin behalten ihren exakten Wert. Schließt sich gegenseitig mit einem nicht leeren custom_data aus. Ein ungültiger Wert gibt 400 zurück.
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" } }
  }
}

Große Ganzzahlen in benutzerdefinierten Daten

Ganzzahlen über 9007199254740992 verlieren in custom_data an Genauigkeit. Verwenden Sie custom_data_raw, damit sie exakt bleiben.

custom_data ist ein google.protobuf.Struct (ein generisches JSON-ähnliches Objekt). Es speichert jede Zahl als Double, eine 64-Bit-Gleitkommazahl, die nur für Ganzzahlen bis 9007199254740992 exakt ist. Größere Ganzzahlen werden gerundet: 5190090000030465245 kommt auf dem Gerät als 5190090000030465000 an. Strings sind nicht betroffen.

Damit solche Ganzzahlen exakt bleiben, senden Sie in custom_data_raw einen String, der das JSON-Objekt enthält:

{ "payload": { "silent": true, "custom_data_raw": "{\"pushUID\": 5190090000030465245}" } }

Regeln für custom_data_raw:

Der String muss ein JSON-Objekt enthalten. Ein Array, ein String, null oder ungültiges JSON gibt 400 (INVALID_ARGUMENT) mit einer Feldverletzung für payload.custom_data_raw zurück.
Wenn custom_data Schlüssel enthält und custom_data_raw gesetzt ist, gibt die Anfrage 400 zurück. Ein leeres custom_data-Objekt wird ignoriert.
Wie custom_data ersetzt es die im Push-preset gespeicherten benutzerdefinierten Daten.
Das Objekt wird vor der Zustellung wieder in JSON-Text umgewandelt. Die Reihenfolge der Schlüssel bleibt nicht erhalten, und Leerzeichen werden entfernt. Zahlen behalten ihren exakten Wert, aber der ursprüngliche Text bleibt nicht Byte für Byte erhalten.
In /messaging/v2/notify/batch lässt ein ungültiges custom_data_raw nur das eigene Element fehlschlagen. Andere Elemente werden gesendet.

Je nachdem, wie Sie die Anfrage senden:

REST: Für /messaging/v2/notify und /messaging/v2/notify/batch sind keine Änderungen nötig. Wenn custom_data eine Ganzzahl enthält, die ein Double nicht exakt darstellen kann, behält die API sie automatisch verlustfrei bei. Sie können custom_data_raw trotzdem explizit setzen.
gRPC: Der Client erstellt das Struct selbst, daher geht die Genauigkeit verloren, bevor die Anfrage gesendet wird. Füllen Sie custom_data_raw statt custom_data aus.

Je nachdem, wohin die Benachrichtigung zugestellt wird:

Android: Das SDK übergibt u als String über PushMessage.getCustomData() an die App, sodass jede Ziffer erhalten bleibt.
Web-Push: Das Web SDK parst u mit JSON.parse, und jede JavaScript-Zahl ist ein Double. Große Ganzzahlen werden im Browser unabhängig von der API gerundet, übergeben Sie sie daher als Strings.
Windows: Die Toast-Benachrichtigung erhält dieselben u-Daten wie andere Plattformen, und über custom_data_raw gesendete Ganzzahlen kommen exakt an.

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:

Genaue Übereinstimmung mit der Sprache des Geräts.
Schlüssel "default".
Schlüssel "en".
Jedes andere im Map vorhandene Gebietsschema.

Stellen Sie mindestens einen der Schlüssel "default" oder "en" bereit, damit jedes Gerät einen deterministischen Fallback hat. Wenn Sie keine Varianten pro Gebietsschema erwarten, senden Sie nur "default".

Jeder Gebietsschema-Eintrag 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
`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
`fb_messenger`	Facebook Messenger-Nachricht
`sms`	SMS-Nachricht

Schaltflächen

Jeder Spracheintrag kann außerdem buttons enthalten: bis zu 3 Aktionsschaltflächen, die unter dem Push auf iOS, Android und Huawei angezeigt werden. Andere Plattformen ignorieren sie. Schaltflächen erfordern iOS SDK 7.2.10 oder höher mit einer Notification Service Extension sowie Android SDK 6.17.0 oder höher.

Jeder PushButton hat diese Felder:

id (string): die Schaltflächen-ID, die Ihre App beim Tippen erhält. Bis zu 64 Zeichen, ohne Leerzeichen, innerhalb des Push eindeutig. Erforderlich für ACTION_OPEN und ACTION_CUSTOM. Wenn Sie sie bei anderen Aktionen weglassen, setzt Pushwoosh btn_1, btn_2 usw.
label (string): der Schaltflächentext, 1 bis 64 Zeichen.
action (enum): ACTION_OPEN öffnet die App, ACTION_URL öffnet url, ACTION_DEEPLINK öffnet einen Deeplink, ACTION_CUSTOM übergibt id an Ihre App, die sie selbst verarbeitet.
url (string): eine absolute http- oder https-Adresse für ACTION_URL oder ein Deeplink mit Schema für ACTION_DEEPLINK.
platform_urls (map): ein Deeplink pro Plattform für ACTION_DEEPLINK, mit dem Plattformcode als Schlüssel: 1 iOS, 3 Android, 17 Huawei.
style (enum): STYLE_DEFAULT oder STYLE_DESTRUCTIVE. Der destruktive Stil zeigt die Schaltfläche auf iOS in Rot an.

{
  "localized_content": {
    "default": {
      "ios": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "android": { "title": "Your order is on its way", "body": "Arrives tomorrow" },
      "buttons": [
        { "id": "track", "label": "Track order", "action": "ACTION_DEEPLINK", "url": "myapp://orders/42" },
        { "id": "cancel", "label": "Cancel order", "action": "ACTION_CUSTOM", "style": "STYLE_DESTRUCTIVE" }
      ]
    }
  }
}

Allgemeine Push-Felder

Diese Felder werden von den Blöcken ios, android, huawei_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): 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): Anzahl der Badges (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-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.
silent (bool): Sendet den iOS-Push als stillen (nur Daten) Push, während andere Plattformen in derselben Nachricht eine normale Benachrichtigung erhalten. Wird innerhalb von content gesetzt und funktioniert daher zusammen damit. Um alle Plattformen still zu schalten, verwenden Sie stattdessen das silent der obersten Ebene, das content ersetzt. Setzen Sie es in einem beliebigen Gebietsschema, um es auf alle Gebietsschemas anzuwenden.

{
  "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`)

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 im Benachrichtigungsfach.
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.
silent (bool): Sendet den Push an diese Plattform als stillen (nur Daten) Push, während andere Plattformen in derselben Nachricht eine normale Benachrichtigung erhalten. Wird innerhalb von content gesetzt und funktioniert daher zusammen damit. Um alle Plattformen still zu schalten, verwenden Sie stattdessen das silent der obersten Ebene, das content ersetzt. Setzen Sie es in einem beliebigen Gebietsschema, um es auf alle Gebietsschemas anzuwenden. Der baidu_android-Block akzeptiert silent ebenfalls, mit demselben Verhalten.

{
  "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 von Strings): 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 (Dauer): 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 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): Code der genehmigten Vorlage.
content_variables (string): JSON-stringifizierte Vorlagenvariablen-Bindungen.

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

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.

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

Viber (`viber`)

Eine Viber-Nachricht ist entweder ein Freitextkörper, optional mit einem Bild und einer Schaltfläche oder mit einem Karussell, oder eine vorab genehmigte transaktionale Vorlage (Omni Messaging / MStat), auf die über ID und Sprache verwiesen wird.

body (string): Reine Textnachricht. Erforderlich, wenn template_id nicht gesetzt ist, es sei denn, image ist gesetzt. Erforderlich bei einer Schaltfläche oder einem Karussell.
image (string): Öffentliche Bild-URL. Wird ignoriert, wenn template_id gesetzt ist.
button_caption (string): Schaltflächentext, bis zu 30 Zeichen. Zusammen mit button_action setzen. Erfordert body. Wird ignoriert, wenn template_id gesetzt ist.
button_action (string): Link der Schaltfläche: eine http://- oder https://-URL, ein viber://-Deep-Link oder ein Omni-Token wie {lp-100} (ein Platzhalter für einen Tracking-Link, den Omni Messaging beim Versand auflöst). Zusammen mit button_caption setzen.
carousel (object): 2–5 wischbare Karten, die unter body angezeigt werden. Kann nicht mit image, button_caption, button_action oder template_id kombiniert werden. Siehe Karussell.
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, image 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.

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

Karussell

carousel.items enthält 2 bis 5 Karten. Um stattdessen ein Karussell in einer Journey einzurichten, siehe Ein Karussell senden. Jede Karte hat diese Felder:

title (string): Kartentitel, 2–38 Zeichen. Erforderlich.
image (string): Öffentliche http://- oder https://-Bild-URL. Erforderlich.
primary_button (object): Hauptschaltfläche. Erforderlich.
secondary_button (object): Zweite Schaltfläche. Optional.

Jede Schaltfläche hat zwei Felder, und beide sind erforderlich, wenn die Schaltfläche vorhanden ist:

caption (string): Schaltflächentext, bis zu 10 Zeichen für primary_button und bis zu 12 für secondary_button.
action (string): Link der Schaltfläche: eine URL mit Schema (http://, https://, viber://) oder ein Omni-Token wie {lp-100}, also dieselben Werte wie bei button_action.

Eine Anfrage, die gegen eine dieser Regeln verstößt, wird mit INVALID_ARGUMENT abgelehnt. Das Detail google.rpc.BadRequest nennt das Feld, zum Beispiel viber.carousel.items[0].title.

Beispiel:

{
  "viber": {
    "body": "New arrivals are in. Swipe to see them.",
    "carousel": {
      "items": [
        {
          "title": "Running shoes",
          "image": "https://example.com/img/shoes.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/shoes" },
          "secondary_button": { "caption": "Details", "action": "{lp-100}" }
        },
        {
          "title": "Sports backpack",
          "image": "https://example.com/img/backpack.jpg",
          "primary_button": { "caption": "Buy now", "action": "https://example.com/backpack" }
        }
      ]
    }
  }
}

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-Stunden-Kundenservice-Fensters zugestellt wird, das durch eine eingehende Nachricht des Benutzers geöffnet wird) und genehmigten Vorlagen (die für den ausgehenden Start und für jede Nachricht außerhalb des 24-Stunden-Fensters erforderlich sind).

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 den ausgehenden Start oder jede Nachricht außerhalb des 24-Stunden-Fensters.
language (string): Gebietsschema der Vorlage, das genau mit dem in Meta genehmigten Gebietsschema übereinstimmen muss (z.B. "en_US", "en_GB"). Nur zusammen 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 das Meta-Vorlagen-Gebietsschema 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 nach Schaltflächenindex abbildet, z.B. "{\"0\":\"https://...\"}".
header_variables (string): JSON-Objekt, das Platzhalter im Header nach Typ abbildet, 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\"}"
  }
}

Facebook Messenger (`fb_messenger`)

Facebook Messenger-Nachrichten laufen über Meta und unterliegen den Messaging-Regeln von Meta: Freitextinhalte werden nur innerhalb des 24-Stunden-Kundenservice-Fensters zugestellt, das durch eine eingehende Nachricht des Benutzers geöffnet wird. Außerhalb dieses Fensters setzen Sie message_tag auf einen der von Meta genehmigten Anwendungsfälle, sonst lehnt Meta den Versand ab.

body (string): Reine Textnachricht. Erforderlich, es sei denn, message ist gesetzt.
message (string): ein vollständiges message-Objekt der Meta Send API als JSON-String, mit Text, Anhängen, Vorlagen oder Schnellantworten. Wenn gesetzt, sendet Pushwoosh es anstelle von body.
message_tag (string): Erforderlich außerhalb des 24-Stunden-Fensters. Einer von CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT.

{
  "fb_messenger": {
    "body": "Hello from Pushwoosh",
    "message_tag": "ACCOUNT_UPDATE"
  }
}

Für diesen Kanal gibt es keine separate Gerätekennung: hwid, push_token und user_id werden alle auf denselben Wert aufgelöst, die seitenbezogene ID (PSID) des Empfängers bei Meta. Sprechen Sie eine bestimmte Konversation mit einer dieser Kennungen in NotifyTransactional an.

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": ["FB_MESSENGER"],
      "hwids": { "list": ["<recipient-psid>"] },
      "payload": {
        "content": {
          "localized_content": {
            "default": {
              "fb_messenger": { "body": "Hello from Pushwoosh" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" }
    }
  }'

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 – Setzen Sie sms.body pro Gebietsschema in localized_content.
Aus einem Preset – Setzen Sie das sms_preset auf Payload-Ebene auf den Code (Format XXXXX-XXXXX) eines gespeicherten SMS-Presets. Sein Inhalt pro Gebietsschema wird in sms.body für jedes Gebietsschema aufgelöst, das das Preset definiert. 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 von Strings): bis zu 3 Anhang-URLs. Jede muss eine absolute https-URL sein, die auf .jpg oder .gif endet – .jpeg und .png werden bei der Validierung abgelehnt, auch bei einer echten 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 Versand 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
  }
}

RCS

Wenn Sie rcs zu einem sms-Block hinzufügen, wird statt body eine Twilio-Content-Vorlage über RCS (Rich Communication Services) gesendet. Twilio stellt die Vorlage als RCS-Nachricht zu und greift ersatzweise auf eine SMS zurück, die aus dem twilio/text-Typ der Vorlage erstellt wird, nicht aus body. Eine Vorlage ohne twilio/text-Typ erreicht nur RCS-fähige Telefone.

rcs.content_sid (string): SID der Twilio-Content-Vorlage, HX gefolgt von 32 Hexadezimalzeichen. Sie erhalten sie über ListRcsTemplates oder in der Twilio Console.
rcs.content_variables (string): JSON-Objekt mit Vorlagenvariablen, als String serialisiert, zum Beispiel "{\"1\": \"{FirstName|CapitalizeFirst|there}\"}". Werte unterstützen Tags und Liquid-Personalisierung. Eine Variable, die Sie weglassen, erhält den Standardwert der Vorlage.

body ist in einem sms-Block mit rcs weiterhin erforderlich.

Die Anfrage wird abgelehnt, es sei denn, die Anwendung sendet SMS über Twilio mit eigener Account SID, eigenem Auth token und eigener Messaging Service SID, die in der SMS-Plattformkonfiguration festgelegt sind. Eine Anwendung mit von Pushwoosh bereitgestellten Twilio-Zugangsdaten kann kein RCS senden.

Ein SMS-Preset kann eine Vorlage pro Gebietsschema enthalten. Mit sms_preset im Payload wird die Vorlage des Presets für jedes Gebietsschema verwendet, für das die Anfrage keine eigene rcs.content_sid mitbringt.

{
  "sms": {
    "body": "Your order has shipped.",
    "rcs": {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "content_variables": "{\"1\": \"{FirstName|CapitalizeFirst|there}\", \"2\": \"A-1042\"}"
    }
  }
}

RCS-Vorlagen auflisten

ListRcsTemplates gibt die Twilio-Content-Vorlagen der Anwendung zurück, die über RCS gesendet werden können. Sie werden mit den eigenen Twilio-Zugangsdaten der Anwendung gelesen.

GET https://rpc-api.svc-nue.pushwoosh.com/api/sms_presets:rcs_templates?application=XXXXX-XXXXX
Authorization: Api YOUR_API_TOKEN

application (string, query): Anwendungscode, Format XXXXX-XXXXX.

Die Antwort enthält ein templates-Array. Es werden nur Vorlagen mit mindestens einem RCS-Content-Typ aufgeführt: twilio/card, twilio/carousel, twilio/quick-reply, twilio/call-to-action oder twilio/media.

Feld	Typ	Beschreibung
`content_sid`	string	Vorlagen-SID, der Wert für `rcs.content_sid`.
`friendly_name`	string	Name der Vorlage in Twilio.
`language`	string	Sprachcode der Vorlage.
`types`	Array von Strings	Twilio-Content-Typen, die die Vorlage definiert, zum Beispiel `twilio/card` und `twilio/text`.
`variables`	object	Vorlagenvariablen mit ihren Standardwerten.
`has_sms_fallback`	boolean	`true`, wenn die Vorlage einen `twilio/text`-Typ hat – die SMS, die ein Telefon ohne RCS erhält.

{
  "templates": [
    {
      "content_sid": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
      "friendly_name": "order_shipped_card",
      "language": "en",
      "types": ["twilio/card", "twilio/text"],
      "variables": { "1": "there", "2": "your order" },
      "has_sms_fallback": true
    }
  ]
}

ListRcsTemplates gibt diese Fehler zurück:

HTTP-Status	Ursache
`400 Bad Request`	Die Anwendung hat keine eigene Twilio-Account SID und kein eigenes Auth token (`FailedPrecondition`).
`401 Unauthorized`	Twilio hat die Zugangsdaten der Anwendung abgelehnt (`Unauthenticated`).
`503 Service Unavailable`	Die Twilio Content API hat einen anderen Fehler zurückgegeben (`Unavailable`).

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

Die Deeplink-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 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 (Zeitstempel): Zeitpunkt, zu dem der Eintrag aus dem Posteingang entfernt wird.
expires_in (Dauer, z.B. "604800s"): Wie lange der Eintrag im Posteingang bleibt, gerechnet ab dem Sendedatum (dem geplanten send_date oder dem Zeitpunkt der Anfrage bei sofortigem Versand). Muss positiv sein. Wird ignoriert, wenn expiration_date gesetzt ist.

Um statt eines festen Datums eine relative Lebensdauer festzulegen, senden Sie nur expires_in:

{
  "image_url": "https://cdn.example.com/inbox.png",
  "expires_in": "604800s"
}

Wenn für Ihr Konto eine maximale Lebensdauer im Posteingang gilt, wird ein expiration_date oder expires_in, das darüber hinausgeht, abgelehnt.

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

Payload-Referenz

Payload

Große Ganzzahlen in benutzerdefinierten Daten

LocalizedContent

Auswahl des Gebietsschemas für ein Gerät

Schaltflächen

Allgemeine Push-Felder

iOS (ios)

Android (android, huawei_android)

macOS (mac_os)

Amazon (amazon)

Safari (safari)

Chrome (chrome)

Firefox (firefox)

Windows (windows)

Telegram (telegram)

Kakao (kakao)

LINE (line)

Viber (viber)