# Référence du Payload

Référence pour le message `Payload` utilisé par [`Notify`](/fr/developer/api-reference/messaging-api-v2/notify/) lors de l'envoi via n'importe quel canal autre que l'e-mail (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp).

<Aside type="note">
Pour l'e-mail, consultez la [référence du payload d'e-mail](/fr/developer/api-reference/messaging-api-v2/email-payload-reference/).
</Aside>

## Payload

- `preset` (string) : code du [préréglage de push](/fr/product/content/push-presets/) (format `XXXXX-XXXXX`) à appliquer à ce message.
- `sms_preset` (string) : code (format `XXXXX-XXXXX`) d'un [préréglage de SMS](/fr/product/content/sms-presets/) enregistré. Son texte par locale est résolu dans le [`sms.body`](#sms-sms) de chaque locale. Un `sms.body` en ligne pour une locale donnée remplace le préréglage pour cette locale. Le préréglage doit appartenir à la même application que le message.
- `content` ([`LocalizedContent`](#localizedcontent)) : contenu du message. Mutuellement exclusif avec `silent`.
- `silent` (bool) : envoyer une notification push silencieuse (données uniquement). Mutuellement exclusif avec `content`.
- `custom_data` (object) : JSON de forme libre transmis au SDK client en tant que paramètre `u`.
- `open_action` ([`OpenAction`](#openaction)) : action déclenchée lorsque l'utilisateur ouvre la notification.
- `open_actions` (map&lt;Platform, `OpenAction`&gt;) : remplacement par plateforme de `open_action`. La clé est une valeur numérique de l'énumération `Platform`.
- `voip_push` (bool) : notification VoIP iOS.

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

Mappe le code de la locale au contenu par plateforme. Les clés sont des codes à deux lettres [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) (par exemple, `"en"`, `"es"`) plus la clé spéciale `"default"` pour une traduction fourre-tout. Les exceptions à la norme ISO 639-1 sont `"zh-Hant"` et `"zh-Hans"` pour le chinois traditionnel et simplifié.

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

### Sélection de la locale pour un appareil

Le contenu livré à un appareil est choisi dans cet ordre :

1.  Correspondance exacte avec la langue de l'appareil.
2.  Clé `"default"`.
3.  Clé `"en"`.
4.  Toute autre locale présente dans la carte.

Fournissez au moins l'un des deux, `"default"` ou `"en"`, afin que chaque appareil ait une solution de repli déterministe. Si vous ne prévoyez pas de variantes par locale, envoyez uniquement `"default"`.

Chaque entrée de locale est un objet `Content` avec des blocs optionnels par plateforme. Remplissez uniquement les plateformes que vous ciblez.

| Bloc de plateforme | Canal |
|---|---|
| `ios` | Push iOS |
| `android` | Push Android (FCM) |
| `huawei_android` | Push Android Huawei |
| `baidu_android` | Push Android Baidu |
| `mac_os` | Push macOS |
| `amazon` | Push Amazon (ADM) |
| `safari` | Push web Safari |
| `chrome` | Push web Chrome |
| `firefox` | Push web Firefox |
| `ie` | Push web Internet Explorer |
| `windows` | Push Windows (tuile / toast / badge) |
| `telegram` | Message Telegram |
| `kakao` | Message Kakao |
| `line` | Message LINE |
| `viber` | Message Viber |
| `whatsapp` | Message WhatsApp |
| `sms` | Message SMS |

## Champs de push courants

Ces champs sont partagés par les blocs `ios`, `android`, `huawei_android`, `baidu_android`, `mac_os`, `amazon`, `safari`, `chrome` et `firefox` (le support varie. Les champs non utilisés sont ignorés par la plateforme concernée).

- `title` (string) : titre de la notification.
- `body` (string) : corps de la notification.
- `time_to_live` (duration, ex. `"3600s"`) : durée pendant laquelle le serveur de push doit conserver la notification pour un appareil hors ligne.
- `sound` (string) : nom du fichier son.
- `sound_enabled` (bool) : activer ou supprimer le son.
- `badges` (string) : nombre de badges (iOS) ou analogue.
- `root_params` (object) : remplacements bruts de la charge utile spécifiques à la plateforme.
- `inbox` ([`Inbox`](#inbox)) : entrée [Message Inbox](/fr/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) : sous-titre de la notification iOS.
- `is_critical` (bool) : alerte critique (nécessite une autorisation).
- `attachment` (string) : URL d'une pièce jointe multimédia.
- `thread_id` (string) : identifiant de fil de discussion pour les notifications groupées.
- `trim_content` (bool) : rogner le contenu pour l'adapter.
- `category_id` (string) : identifiant `UNNotificationCategory` pour les actions interactives.
- `interruption_level` (string) : `passive`, `active`, `time-sensitive` ou `critical`.
- `collapse_id` (string) : identifiant de regroupement APNs. Les notifications avec le même `collapse_id` se remplacent mutuellement sur l'appareil.

```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) : petite icône de notification.
- `banner` (string) : URL de la grande image.
- `delivery_priority` (`NORMAL` | `HIGH`) : priorité de livraison FCM.
- `vibration` (bool) : vibration à la réception.
- `led_color` (string, hex) : couleur de la LED de notification.
- `icon_background_color` (string, hex) : couleur de fond de l'icône.
- `show_on_lockscreen` (bool) : afficher sur l'écran de verrouillage.
- `custom_icon` (string) : URL d'une icône personnalisée.
- `priority` ([`NotificationPriority`](#notificationpriority-enum)) : priorité dans la barre de notifications.
- `group_id` (string) : clé de groupe de notification.
- `collapse_key` (string) : clé de regroupement FCM. Les notifications avec la même `collapse_key` se remplacent mutuellement lorsque l'appareil est hors ligne.

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

Utilise les champs de push courants plus `subtitle` et `action` (URL ouverte lorsque l'utilisateur clique sur la notification).

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

## Amazon (`amazon`)

Utilise les champs de push courants plus `custom_icon` et `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 ouverte lorsque l'utilisateur clique sur la notification.
- `url_arguments` (array of string) : arguments d'URL Safari substitués dans le modèle d'URL de Web Push.

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

## Chrome (`chrome`)

- `icon`, `image` (string) : URL de la petite icône et de la grande image.
- `duration` (duration) : minuteur de fermeture automatique.
- `button_text1` / `button_url1`, `button_text2` / `button_url2` : jusqu'à deux boutons d'action.

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

Utilise uniquement `title`, `body`, `icon`, `root_params` et `inbox`.

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

## Windows (`windows`)

Windows utilise une forme différente :

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

- `type` est `TILE`, `TOAST` ou `BADGE`.
- `template` (structuré) ou `raw` (`{ "content": "<raw xml>" }`) — exactement l'un des deux.

## Telegram (`telegram`)

- `body` (string) : texte du message.
- `content_variables` (string) : variables sous forme de chaîne JSON pour le modèle côté bot.

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

## Kakao (`kakao`)

- `content` (string) : contenu du message.
- `template` (string) : code du modèle approuvé.
- `content_variables` (string) : liaisons de variables de modèle sous forme de chaîne JSON.

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

## LINE (`line`)

- `content` (string) : corps en texte brut.
- `template` (string) : code d'un modèle LINE configuré dans le Control Panel de Pushwoosh (utilisé pour envoyer des messages image, carrousel ou flex). Pour du contenu riche, pré-configurez le modèle dans le Control Panel et référencez-le ici.

Au moins l'un des deux, `content` ou `template`, doit être défini.

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

## Viber (`viber`)

Un message Viber est soit un corps de texte libre, soit un modèle transactionnel pré-approuvé (Omni Messaging / MStat) référencé par son id et sa langue.

- `body` (string) : message en texte brut. Requis lorsque `template_id` n'est pas défini.
- `template_id` (string) : id d'un modèle transactionnel pré-approuvé. Lorsqu'il est défini, il a la priorité sur `body`.
- `template_lang` (string) : locale du modèle. Requis lorsque `template_id` est défini.
- `template_params` (map&lt;string, string&gt;) : liaisons clé/valeur substituées dans le modèle, ex. `{ "name": "John", "code": "123456" }`.
- `all_devices` (bool) : `false` (par défaut) livre uniquement à l'appareil principal de l'utilisateur ; `true` livre à tous les appareils de l'utilisateur.

Au moins l'un des deux, `body` ou `template_id`, doit être défini. Lorsque `template_id` est défini, `template_lang` est requis.

Adressez les destinataires Viber en tant que hwids sous la forme `viber:<phone>` (E.164), par exemple `viber:+1234567890`.

Texte brut :

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

Modèle transactionnel :

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

Les messages WhatsApp passent par Meta et sont soumis aux règles de messagerie de Meta. La distinction principale se situe entre le texte de forme libre (livré uniquement dans la fenêtre de service client de 24 heures ouverte par un message entrant de l'utilisateur) et les modèles approuvés (requis pour l'initiation sortante et pour tout message en dehors de la fenêtre de 24 heures).

- `content` (string) : texte du message de forme libre. Livré par Meta uniquement dans la fenêtre de 24 heures.
- `content_id` (string) : nom d'un modèle Meta pré-approuvé (ex. `"hello_world"`). Requis pour l'initiation sortante ou tout message en dehors de la fenêtre de 24 heures.
- `language` (string) : locale du modèle qui doit correspondre exactement à la locale approuvée dans Meta (ex. `"en_US"`, `"en_GB"`). N'a de sens qu'avec `content_id`. Ceci est indépendant de la clé `LocalizedContent` externe. La clé externe sélectionne le contenu pour un appareil, et `language` sélectionne la locale du modèle Meta pour ce contenu.
- `content_variables` (string) : objet JSON mappant les placeholders du corps, ex. `"{\"1\":\"John\"}"`.
- `button_url_variables` (string) : objet JSON mappant les placeholders d'URL de bouton, indexés par l'index du bouton, ex. `"{\"0\":\"https://...\"}"`.
- `header_variables` (string) : objet JSON mappant les placeholders d'en-tête, indexés par type, ex. `"{\"image\":\"https://...\"}"`.

Au moins l'un des deux, `content` ou `content_id`, doit être défini.

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

## SMS (`sms`)

Le SMS a son propre bloc de plateforme à l'intérieur de chaque [`Content`](#localizedcontent) de locale, aux côtés de `ios`, `android` et des autres canaux de messagerie.

- `body` (string) : texte du SMS pour la locale. Requis lorsque le bloc `sms` est présent.

Il y a deux façons de fournir le texte :

- **En ligne** — définissez `sms.body` par locale dans `localized_content`.
- **À partir d'un préréglage** — définissez le [`sms_preset`](#payload) au niveau du payload sur le code (format `XXXXX-XXXXX`) d'un [préréglage de SMS](/fr/product/content/sms-presets/) enregistré. Son contenu par locale est résolu en `sms.body` pour chaque locale que le préréglage définit. Un `sms.body` en ligne pour une locale remplace le préréglage pour cette locale, vous pouvez donc réutiliser un préréglage tout en ajustant des langues individuelles.

```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
Définit l'action effectuée lorsque l'utilisateur ouvre le message.

Exactement l'un des suivants :

- `rich_media` ([`RichMedia`](#richmedia)) : ouvrir une page [Rich Media](/fr/product/content/in-apps/).
- `deep_link` : ouvrir un deep link : `{ "code": "flow-code", "params": { "key": "value" } }`.
- `link` ([`Link`](#link)) : ouvrir une URL.

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

### RichMedia


```json
{ "code": "XXXXX-XXXXX" }        // par code Rich Media
{ "url":  "https://..." }        // par URL distante
```

### Link


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

`shortener` est `NONE` (par défaut) ou `BITLY`.

## Inbox

Configure comment le message apparaît dans la Message Inbox.

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

- `image_url` (string) : image affichée dans l'entrée de la boîte de réception.
- `expiration_date` (timestamp) : moment où l'entrée est supprimée de la boîte de réception.

## Énumération NotificationPriority
Contrôle la priorité de la notification sur l'appareil cible, de `PRIORITY_MIN` (la plus basse) à `PRIORITY_MAX` (la plus haute).

- `PRIORITY_UNSPECIFIED`
- `PRIORITY_MIN`
- `PRIORITY_LOW`
- `PRIORITY_DEFAULT`
- `PRIORITY_HIGH`
- `PRIORITY_MAX`

## Exemple : Envoyer un push à un 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"
    }
  }'
```

## Exemple : Push transactionnel par ID utilisateur

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