Référence du payload

Référence pour le message Payload utilisé par Notify lors de l’envoi via un canal autre que l’e-mail (push, SMS, Telegram, Kakao, LINE, Viber, WhatsApp).

Note

Pour l’e-mail, consultez la référence du payload d’e-mail.

Payload

• preset (string) : code de préréglage push (format XXXXX-XXXXX) à appliquer à ce message.
• sms_preset (string) : code (format XXXXX-XXXXX) d’un préréglage SMS enregistré. Son texte par locale est résolu dans le champ sms.body 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) : contenu du message. Mutuellement exclusif avec silent.
• silent (bool) : envoie 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) : action déclenchée lorsque l’utilisateur ouvre la notification.
• open_actions (map<Platform, OpenAction>) : remplacement par plateforme de open_action. La clé est une valeur numérique de l’énumération Platform.
• voip_push (bool) : notification VoIP pour iOS.

{
  "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 locale au contenu par plateforme. Les clés sont des codes à deux lettres ISO 639-1 (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é.

{
  "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 dé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’une des clés "default" ou "en" pour que chaque appareil ait une solution de repli déterministe. Si vous ne prévoyez pas de variantes par locale, n’envoyez que "default".

Chaque entrée de locale est un objet Content avec des blocs optionnels par plateforme. Ne remplissez que 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 (vignette / toast / badge)
telegram	Message Telegram
kakao	Message Kakao
line	Message LINE
viber	Message Viber
whatsapp	Message WhatsApp
sms	Message SMS

Champs push communs

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 push doit conserver la notification pour un appareil hors ligne.
• sound (string) : nom du fichier son.
• sound_enabled (bool) : active ou supprime le son.
• badges (string) : nombre de badges (iOS) ou équivalent.
• root_params (object) : remplacements bruts du payload spécifiques à la plateforme.
• inbox (Inbox) : entrée de la Boîte de réception.

{
  "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 spéciale).
• 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) : tronque le contenu pour l’ajuster.
• 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.

{
  "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 la 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) : priorité dans la barre de notifications.
• group_id (string) : clé de groupe de notifications.
• collapse_key (string) : clé de regroupement FCM. Les notifications avec la même collapse_key se remplacent mutuellement lorsque l’appareil est hors ligne.

{
  "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 push communs plus subtitle et action (URL ouverte lorsque l’utilisateur clique sur la notification).

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

Amazon (amazon)

Utilise les champs push communs plus custom_icon et 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 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 Push Web.

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

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

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

Windows (windows)

Windows utilise une forme différente :

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

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

{
  "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 Panneau de Contrôle Pushwoosh (utilisé pour envoyer des messages image, carrousel ou flex). Pour du contenu riche, pré-configurez le modèle dans le Panneau de Contrôle et référencez-le ici.

Au moins l’un des champs content ou template doit être défini.

{
  "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é. S’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<string, string>) : 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 champs 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:<téléphone> (E.164), par exemple viber:+1234567890.

Texte brut :

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

Modèle transactionnel :

{
  "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 fait entre le texte libre (uniquement délivré 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 initier une conversation sortante et pour tout message en dehors de la fenêtre de 24 heures).

• content (string) : texte de message libre. Dé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 initier une conversation sortante ou pour 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 champs content ou content_id doit être défini.

{
  "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 du Content de chaque 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 manières 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 au niveau du payload avec le code (format XXXXX-XXXXX) d’un préréglage SMS enregistré. Son contenu par locale est résolu dans 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.

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

MMS

L’ajout de subject et file_urls à un bloc sms transforme le message en MMS. Seul AbleMobile dispose d’un point de terminaison MMS — les autres fournisseurs de SMS ignorent ces deux champs et ne délivrent que le body en texte brut.

• subject (string) : sujet du MMS. Nécessite au moins une entrée dans file_urls — un sujet sans pièces jointes est rejeté. Jusqu’à 40 caractères ASCII, ou 13 caractères si le sujet contient des caractères non-ASCII.
• file_urls (array of string) : jusqu’à 3 URL de pièces jointes. Chacune doit être une URL https absolue se terminant par .jpg ou .gif — .jpeg et .png sont rejetés par la validation, même pour un fichier JPEG ou PNG authentique, car le fournisseur ne peut pas les décoder. Chaque fichier doit également faire 200 Ko ou moins ; AbleMobile rejette l’envoi entier si une pièce jointe est plus lourde.
• message_at (int) : index dans file_urls (base 0) après lequel le texte du corps du SMS est affiché.

subject et file_urls prennent en charge la personnalisation Liquid, tout comme 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

Définit l’action effectuée lorsque l’utilisateur ouvre le message.

Exactement l’un des suivants :

• rich_media (RichMedia) : ouvre une page Rich Media.
• deep_link : ouvre un lien profond : { "code": "flow-code", "params": { "key": "value" } }.
• link (Link) : ouvre une URL.

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

L’URL du lien profond et les valeurs de params prennent en charge la syntaxe de personnalisation Liquid — les expressions sont résolues avant l’ouverture du lien profond.

RichMedia

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

Link

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

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

Inbox

Configure l’apparence du message dans la Boîte de réception.

{
  "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) : date à laquelle 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 élevée).

• PRIORITY_UNSPECIFIED
• PRIORITY_MIN
• PRIORITY_LOW
• PRIORITY_DEFAULT
• PRIORITY_HIGH
• PRIORITY_MAX

Attention

Envoyez toujours priority comme l’une des valeurs de chaîne ci-dessus. L’API accepte également les équivalents numériques de l’énumération (1-5, correspondant à l’ordre ci-dessus), mais ce mappage est un détail interne de protobuf, pas un contrat pris en charge — ne vous y fiez pas.

Une valeur de priority non reconnue (une chaîne mal orthographiée ou un nombre hors plage) n’est pas rejetée : l’API l’ignore silencieusement, et la notification est envoyée sans aucun champ priority au lieu de retourner une erreur.

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

Exemple : Notification push transactionnelle par ID utilisateur

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