# Payload-Referenz

Referenz für die `Payload`-Nachricht, die von [`Notify`](/de/developer/api-reference/messaging-api-v2/notify/) beim Senden über einen beliebigen Kanal außer E-Mail (Push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp) verwendet wird.

<Aside type="note">
Für E-Mails siehe die [E-Mail-Payload-Referenz](/de/developer/api-reference/messaging-api-v2/email-payload-reference/).
</Aside>

## Payload

- `preset` (string): Code des [Push-Presets](/de/product/content/push-presets/) (Format `XXXXX-XXXXX`), das auf diese Nachricht angewendet werden soll.
- `sms_preset` (string): Code (Format `XXXXX-XXXXX`) eines gespeicherten [SMS-Presets](/de/product/content/sms-presets/). Sein sprachspezifischer Text wird in den [`sms.body`](#sms-sms) jeder Sprache aufgelöst. Ein inline `sms.body` für eine bestimmte Sprache überschreibt das Preset für diese Sprache. Das Preset muss zur selben Anwendung wie die Nachricht gehören.
- `content` ([`LocalizedContent`](#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`](#openaction)): Aktion, die ausgelöst wird, wenn der Benutzer die Benachrichtigung öffnet.
- `open_actions` (map&lt;Platform, `OpenAction`&gt;): Plattformspezifische Überschreibung von `open_action`. Der Schlüssel ist ein numerischer `Platform`-Enum-Wert.
- `voip_push` (bool): iOS-VoIP-Benachrichtigung.

```json
{
  "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-Codes plattformspezifischen Inhalten zu. Die Schlüssel sind zweibuchstabige [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php)-Codes (zum Beispiel `"en"`, `"es"`) plus der spezielle Schlüssel `"default"` für eine allgemeingültige Übersetzung. Die Ausnahmen zu ISO 639-1 sind `"zh-Hant"` und `"zh-Hans"` für traditionelles und vereinfachtes Chinesisch.

```json
{
  "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" }
    }
  }
}
```

### Sprachauswahl 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.  Jede andere in der Map vorhandene Sprache.

Geben Sie mindestens einen der Schlüssel `"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 |
| `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): 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 Entsprechung.
- `root_params` (object): Rohe plattformspezifische Payload-Überschreibungen.
- `inbox` ([`Inbox`](#inbox)): Eintrag im [Message Inbox](/de/developer/guides/message-inbox/mobile-message-inbox/).

```json
{
  "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 demselben `collapse_id` ersetzen sich gegenseitig auf dem Gerät.

```json
{
  "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`](#notificationpriority-enum)): 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.

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

```json
{
  "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`](#notificationpriority-enum)).

```json
{
  "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.

```json
{
  "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.

```json
{
  "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`.

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

## Windows (`windows`)

Windows verwendet eine andere Struktur:

```json
{
  "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.

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

## Kakao (`kakao`)

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

```json
{
  "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.

```json
{
  "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): 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): Sprache der Vorlage. Erforderlich, wenn `template_id` gesetzt ist.
- `template_params` (map&lt;string, string&gt;): 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:

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

Transaktionale Vorlage:

```json
{
  "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 liegt zwischen Freitext (wird nur innerhalb des 24-stündigen 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): Sprache der Vorlage, die genau mit der in Meta genehmigten Sprache übereinstimmen 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 die Meta-Vorlagensprache 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 Button-URLs abbildet, die nach dem Button-Index 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.

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

## SMS (`sms`)

SMS hat seinen eigenen Plattform-Block innerhalb des [`Content`](#localizedcontent) jeder Sprache, neben `ios`, `android` und den anderen Messaging-Kanälen.

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

Es gibt zwei Möglichkeiten, den Text bereitzustellen:

- **Inline** — Setzen Sie `sms.body` pro Sprache in `localized_content`.
- **Aus einem Preset** — Setzen Sie das Payload-Level [`sms_preset`](#payload) auf den Code (Format `XXXXX-XXXXX`) eines gespeicherten [SMS-Presets](/de/product/content/sms-presets/). Sein sprachspezifischer Inhalt wird für jede Sprache, die das Preset definiert, in `sms.body` aufgelöst. Ein inline `sms.body` für eine Sprache überschreibt das Preset für diese Sprache, sodass Sie ein Preset wiederverwenden und dennoch einzelne Sprachen anpassen können.

```json
{
  "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`](#richmedia)): Öffnet eine [Rich Media](/de/product/content/in-apps/)-Seite.
- `deep_link`: Öffnet einen Deep Link: `{ "code": "flow-code", "params": { "key": "value" } }`.
- `link` ([`Link`](#link)): Öffnet eine URL.

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

Die Deeplink-URL und die `params`-Werte unterstützen die [Liquid-Personalisierungs](/de/developer/guides/personalization/liquid-templates/)-Syntax – Ausdrücke werden aufgelöst, bevor der Deep Link geöffnet wird.

### RichMedia


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

### Link


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

`shortener` ist `NONE` (Standard) oder `BITLY`.

## Inbox

Konfiguriert, wie die Nachricht im Message Inbox erscheint.

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

<Aside type="caution">
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 zurückgewiesen: Die API verwirft ihn stillschweigend, und die Benachrichtigung wird ohne ein `priority`-Feld gesendet, anstatt einen Fehler zurückzugeben.
</Aside>

## Beispiel: Senden eines Push an ein Segment

```bash
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

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