API des Préréglages

Un préréglage push est un modèle de notification push réutilisable — le même objet que vous construisez dans l’éditeur de push du Panneau de Contrôle. Cette API gère uniquement les préréglages push ; les préréglages SMS, WhatsApp, Kakao, LINE et Viber ont chacun leur propre service de préréglage dédié, non couvert ici.

Utilisez le code d’un préréglage pour l’envoyer via Notify (charge utile preset) ou un point Envoyer un push d’un Customer Journey.

URL de base

https://rpc-api.svc-nue.pushwoosh.com

Tous les points de terminaison sont servis via HTTPS. Les requêtes et les réponses utilisent application/json sauf indication contraire.

Authentification

Chaque requête doit inclure un en-tête Authorization avec votre jeton d’API Serveur :

Authorization: Api VOTRE_JETON_API

Conventions

• Nommage des champs : les corps de requête et les paramètres de chemin/requête acceptent le lowerCamelCase (par exemple, sendType, localizedProperties, searchByName) — le serveur décode l’une ou l’autre casse. Les réponses sont toujours encodées en utilisant les noms de champs proto, en snake_case (localized_properties, platform_properties, per_page, etc.). Les exemples de réponse et la référence de l’Objet Préréglage ci-dessous utilisent cette casse.
• code : chaque réponse de préréglage contient son propre code, généré lors de la Création. Transmettez ce code à Get, Update, UpdatePartial, Delete, Clone, et aux API de messagerie/journey mentionnées ci-dessus.
• Clés de plateforme : les maps platforms et open_actions sont indexées par le code de type d’appareil numérique (1 pour iOS, 3 pour Android, etc.). platform_properties est indexé par le nom de l’énumération de la plateforme à la place (IOS, ANDROID, HUAWEI_ANDROID, OSX — les seules quatre plateformes qu’il couvre).
• Champs non remplis : les réponses de Get, Create et Clone incluent chaque champ de l’Objet Préréglage, même lorsqu’ils sont vides ou nuls. List renvoie un ensemble de champs réduit — voir Lister ci-dessous. Update et UpdatePartial ne renvoient aucun champ de préréglage — voir l’avertissement dans leurs sections.

Réponses d’erreur

Statut HTTP	Signification
400 Bad Request	Argument invalide — un champ obligatoire est manquant ou malformé, ou une précondition a échoué (par exemple, cloner sans nom).
401 Unauthorized	En-tête Authorization manquant ou invalide.
403 Forbidden	L’application ou le préréglage n’appartient pas au compte de l’appelant.
404 Not Found	Le préréglage ou l’application n’a pas été trouvé.
500 Internal Server Error	Échec inattendu côté serveur.

Delete sur un préréglage encore utilisé par un point Envoyer un push d’un journey en cours d’exécution ou en pause renvoie également 400 Bad Request (un FailedPrecondition sur le réseau) — et non 409. Retirez d’abord le préréglage du journey.

Create, Update, et UpdatePartial renvoient également 400 Bad Request pour un jeton de personnalisation non résolvable — voir ci-dessous.

Jetons de personnalisation

Create, Update, et UpdatePartial valident chaque jeton de personnalisation ({name|modifier|default}) dans localizedTitle, localizedSubtitle, et localizedContent (pour chaque langue dans la requête), et dans les champs de contenu riche par plateforme que l’expéditeur substitue (titre, contenu, bannière, icône, URL, paramètres de lien profond, etc., pour chaque plateforme). Les champs en dehors de cet ensemble, tels que richmedia, campaignCode, deeplink, ou filterCode, conservent un jeton exactement tel qu’il est écrit — Pushwoosh n’analyse pas la syntaxe de personnalisation à cet endroit.

Un jeton a besoin d’un modificateur que Pushwoosh reconnaît, car un jeton non modifié ou mal orthographié ne peut pas être formaté et atteindrait les utilisateurs sous forme d’accolades littérales. Un jeton avec un modificateur manquant ou inconnu ({Tag|}, {Tag|typo}) fait échouer l’appel avec InvalidArgument :

{
  "code": 3,
  "message": "personalization token {Tag|} has no known modifier, so it would be delivered as text; expected one of [capitalizefirst capitalizeallfirst uppercase lowercase regular base64 cent dollar comma euro jpy lira M-d-y m-d-y M d y M d Y l M d H:i m-d-y H:i]"
}

Attention

Sur UpdatePartial, cette vérification s’exécute sur l’ensemble des champs de contenu substitués enregistrés du préréglage, pas seulement sur les champs de la requête actuelle — un préréglage qui a déjà un jeton cassé dans un champ non modifié fera échouer chaque appel UpdatePartial ultérieur jusqu’à ce que ce jeton soit corrigé. localizedTitle, localizedSubtitle et localizedContent sont l’exception : ils ne sont vérifiés que lorsque le même appel les inclut.

Modificateurs acceptés

Le sélecteur de personnalisation du Panneau de Contrôle propose déjà tous les modificateurs ci-dessous pour les tags INTEGER/PRICE (y compris les formats de date) et pour les tags de chaîne, à l’exception de base64 — celui-ci n’est accessible que via l’API. gitlab.corp.pushwoosh.com/channels/sdk/pkg/dynamiccontent est la source de vérité que le Panneau de Contrôle et cette API utilisent pour la validation.

Modificateur	Type de tag	Notes
capitalizefirst	chaîne	Insensible à la casse
capitalizeallfirst	chaîne	Insensible à la casse
uppercase	chaîne	Insensible à la casse
lowercase	chaîne	Insensible à la casse
regular	chaîne ou entier	Insensible à la casse, aucun formatage appliqué
base64	chaîne	Insensible à la casse, API uniquement — non proposé par le sélecteur du PC
cent / dollar / comma / euro / jpy / lira	entier	Insensible à la casse
M-d-y, m-d-y, M d y, M d Y, l, M d, H:i, m-d-y H:i	entier	Modificateurs de format de date, correspondance exacte telle qu’écrite, casse incluse

Points de terminaison

Méthode	Chemin	Description
POST	/api/presets	Créer un nouveau préréglage push
GET	/api/presets	Lister les préréglages push d’une application
GET	/api/presets/{code}	Obtenir un seul préréglage push
PUT	/api/presets/{code}	Mettre à jour un préréglage push (écrasement complet)
PUT	/api/presets/{code}:partial	Mettre à jour un préréglage push (partiel)
POST	/api/presets/{code}:clone	Cloner un préréglage push
DELETE	/api/presets/{code}	Supprimer un préréglage push

Créer

Crée un nouveau préréglage push dans une application et le renvoie avec son code généré.

POST /api/presets

Corps de la requête

Paramètre	Type	Requis	Description
application	chaîne	Oui	Le code d’application dans lequel créer le préréglage.
name	chaîne	Oui	Nom du préréglage.
sendType	chaîne	Non	Canal du préréglage (par exemple push).
isV2	booléen	Non	Épingle l’indicateur d’origine du préréglage. Omettre pour utiliser la valeur par défaut true (v2) ; définir à false uniquement lors de la reproduction d’un préréglage v1 hérité.

Tous les autres champs — contenu localisé, plateformes, lien profond, boîte de réception, catégories, etc. — sont partagés avec Update et documentés une seule fois dans la référence de l’Objet Préréglage ci-dessous.

Exemple de requête

{
  "application": "XXXXX-XXXXX",
  "name": "20% de réduction",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Obtenez votre réduction de 20% dès maintenant",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Bonjour" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

Réponse

Renvoie { "preset": { ... } }, l’Objet Préréglage créé.

Lister

Liste les préréglages push d’une application — un ensemble de champs réduit, pas l’objet complet — avec pagination, tri et filtrage par nom ou catégorie.

GET /api/presets

Paramètres de la requête

Paramètre	Type	Requis	Description
application	chaîne	Oui	Le code d’application pour lequel lister les préréglages.
orderBy	chaîne	Non	NAME (par défaut), CREATED, ou UPDATED.
orderDirection	chaîne	Non	ASC (par défaut) ou DESC.
page	entier	Non	Index de page basé sur zéro.
perPage	entier	Non	Taille de la page. Par défaut à 100 si omis ou 0.
searchByName	chaîne	Non	Correspondance de sous-chaîne insensible à la casse sur le nom ou le code du préréglage (ILIKE %value%).
searchByCategory	tableau de chaînes	Non	Répétez le paramètre pour filtrer par plusieurs catégories, ex. ?searchByCategory=promo&searchByCategory=lifecycle.
showHidden	booléen	Non	Inclure les préréglages marqués comme cachés.

Note

isDefault est un filtre obsolète conservé uniquement pour l’ancien formulaire d’envoi de push dans le Panneau de Contrôle — ne vous y fiez pas.

Réponse

Chaque élément ne contient que : name, code, platforms, localized_content (texte brut par locale — pas localized_properties), localized_title, localized_subtitle, banner, icon, categories, journey_uuid, custom_data, is_v2, created, updated. Tous les autres champs de l’Objet Préréglage — localized_properties, platform_properties, deeplink, richmedia, url, etc. — sont omis, même s’ils sont définis sur le préréglage.

Champ	Type	Description
presets	tableau d’objets	La page actuelle de préréglages, dans la forme réduite décrite ci-dessus.
page	entier	L’index de page retourné.
per_page	entier	La taille de page utilisée pour cette réponse.
total	entier	Nombre total de préréglages correspondant aux filtres, sur toutes les pages.

Exemple de réponse

{
  "presets": [
    { "name": "20% de réduction", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Obtenir

Renvoie un seul préréglage push par son code, avec chaque champ de l’Objet Préréglage rempli.

GET /api/presets/{code}

Paramètres de chemin

Paramètre	Type	Description
code	chaîne	Le code du préréglage.

Réponse

Renvoie { "preset": { ... } }, l’Objet Préréglage complet.

Mettre à jour

Écrase un préréglage push existant par son code avec les champs fournis.

PUT /api/presets/{code}

Paramètres de chemin

Paramètre	Type	Description
code	chaîne	Le code du préréglage à écraser.

Corps de la requête

Mêmes champs que pour Créer (moins application), plus le reste des champs de l’Objet Préréglage. sendType est accepté mais ignoré — le canal d’un préréglage ne peut pas être modifié après sa création.

Omettre un champ ne signifie pas toujours 'laisser inchangé'

Update reconstruit les propriétés de contenu du préréglage à partir de zéro à chaque appel : localizedProperties, platformProperties, openAction/openActions, deeplink, deeplinkParams, richmedia, url, campaignCode, filterCode, geoZones, sendRate, cappingCount/cappingDays, les trois champs notification*Url, remotePage, wnsContent, originalUrl, les quatre indicateurs *Silent, inboxImage/inboxIcon/inboxDays/inboxDate, banner, icon, customData, et isV2 — omettez l’un de ces champs et il sera effacé (ou, pour isV2, réinitialisé à true).

name, platforms, categories, localizedTitle, localizedSubtitle, et localizedContent sont l’exception : chacun n’est modifié que lorsque vous l’envoyez, et laissé inchangé si omis.

Utilisez Mise à jour partielle si vous voulez que le premier groupe soit également laissé inchangé si omis.

La réponse n'a pas de champ de préréglage

Update renvoie {} — un objet vide. Le message de réponse définit techniquement un champ preset, mais le serveur ne le remplit jamais. Appelez Get par la suite si vous avez besoin de récupérer l’objet mis à jour.

Réponse

Un objet vide en cas de succès : {}.

Mise à jour partielle

Met à jour uniquement les champs fournis d’un préréglage push existant par son code, laissant les champs non définis inchangés.

PUT /api/presets/{code}:partial

Paramètres de chemin

Paramètre	Type	Description
code	chaîne	Le code du préréglage à patcher.

Corps de la requête

Mêmes champs que pour Mettre à jour, moins application. Contrairement à Update, chaque champ ici — y compris localizedProperties, platformProperties, categories, et le reste du groupe de propriétés de contenu listé dans l’avertissement de Mettre à jour — est laissé inchangé si omis, et n’est modifié que lorsque vous l’envoyez (un champ de type map/array que vous envoyez remplace toujours entièrement la valeur existante pour ce champ, mais n’affecte rien que vous n’ayez pas inclus). sendType est également accepté mais ignoré.

Note

isV2 est la seule exception même ici : il est réécrit à chaque appel UpdatePartial, prenant la valeur par défaut true si omis. Envoyez isV2: false explicitement si le préréglage doit rester un préréglage de style v1.

Exemple de requête

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

Réponse

Également un objet vide — voir l’avertissement ci-dessus.

Cloner

Duplique un préréglage push existant, sous un nouveau nom, dans la même application.

POST /api/presets/{code}:clone

Note

Contrairement à Clone de l’API des modèles d’e-mail, ce point de terminaison n’a pas de paramètre application — il clone toujours dans la propre application du préréglage source. Le clone est toujours créé avec hidden: false, quelle que soit la source.

Corps de la requête

Paramètre	Type	Requis	Description
code	chaîne	Oui	Code du préréglage source à dupliquer.
name	chaîne	Oui	Nom du nouveau préréglage.

Exemple de requête

{ "code": "AAAAA-BBBBB", "name": "20% de réduction (copie)" }

Réponse

Renvoie { "preset": { ... } }, le nouvel Objet Préréglage.

Supprimer

Supprime définitivement un préréglage push par son code.

DELETE /api/presets/{code}

Attention

Échoue si le préréglage est encore utilisé par un point send_push dans un journey en cours d’exécution ou en pause — retirez-le d’abord du journey. Cette action est irréversible.

Paramètres de chemin

Paramètre	Type	Description
code	chaîne	Le code du préréglage à supprimer.

Réponse

Un objet vide en cas de succès : {}.

Référence de l’objet

Les noms de champs ci-dessous correspondent à ce que Get, Create, Update et Clone renvoient réellement — les noms de champs proto en snake_case (voir Conventions). La forme lowerCamelCase utilisée dans les exemples de requête ci-dessus fonctionne de la même manière en entrée.

Objet Préréglage

Identité

Champ	Type	Description
code	chaîne	Généré lors de la Création. Identifie ce préréglage partout ailleurs dans l’API.
name	chaîne	Nom du préréglage.
send_type	chaîne	Canal du préréglage (par exemple push).
is_v2	booléen	true pour les préréglages créés ou migrés vers le modèle de contenu v2.
system	booléen	Marque le préréglage comme un préréglage système/interne.
hidden	booléen	Cache le préréglage des résultats de List (envoyez showHidden: true pour l’inclure).
created	chaîne (RFC 3339)	Horodatage de la création.
updated	chaîne (RFC 3339)	Horodatage de la dernière mise à jour.

Ciblage & contenu

Champ	Type	Description
platforms	map<string, boolean>	Quelles plateformes le préréglage cible, indexées par code de type d’appareil (ex. "1" pour iOS).
localized_properties	map<string, object>	Locale → contenu riche par plateforme. Même forme que LocalizedContent sur la charge utile Notify — une entrée par bloc de plateforme (ios, android, etc.). C’est la principale façon de définir un contenu push spécifique à la plateforme.
localized_title / localized_subtitle / localized_content	map<string, string>	Locale → texte brut. Une alternative plus simple à localized_properties pour le titre, le sous-titre et le corps lorsque vous n’avez pas besoin de surcharges par plateforme.
platform_properties	map<string, object>	Surcharges héritées par plateforme, indexées par le nom de l’énumération de la plateforme (IOS, ANDROID, HUAWEI_ANDROID, OSX). Voir Objet PlatformProperties ci-dessous.
open_action	OpenAction	Action déclenchée lorsque l’utilisateur ouvre la notification, appliquée à chaque plateforme. Mutuellement exclusif avec open_actions — la réponse en définit exactement un.
open_actions	map<string, OpenAction>	Surcharge par plateforme de open_action, indexée par code de type d’appareil.
deeplink	chaîne	Code de Lien Profond.
deeplink_params	map<string, string>	Paramètres passés au lien profond.
richmedia	chaîne	Code de Média Riche ouvert par la notification.
url	chaîne	URL ouverte par la notification, si vous n’utilisez pas de lien profond ou de Média Riche.

Boîte de réception

Champ	Type	Description
inbox_image	chaîne	URL de l’image affichée dans l’entrée de la Boîte de réception des messages.
inbox_icon	chaîne	URL de l’icône affichée dans l’entrée de la Boîte de réception des messages.
inbox_days	entier	Nombre de jours pendant lesquels l’entrée reste dans la Boîte de réception des messages.
inbox_date	chaîne (RFC 3339)	Date d’expiration explicite pour l’entrée de la Boîte de réception des messages, comme alternative à inbox_days.

Organisation & métadonnées

Champ	Type	Description
categories	tableau de chaînes	Noms de catégorie avec lesquels le préréglage est étiqueté.
campaign_code	chaîne	Code de campagne auquel ce préréglage est attribué.
filter_code	chaîne	Code de Segment / Filtre que ce préréglage cible par défaut.
geo_zones	chaîne	Ciblage par Géozone, si le préréglage est déclenché par la géolocalisation.
journey_uuid	chaîne	UUID du Customer Journey qui possède ce préréglage, s’il a été créé à partir d’un point Envoyer un push d’un journey.
custom_data	objet	JSON de forme libre transmis au SDK client en tant que paramètre u.
banner	chaîne	URL de l’image en grand format / pièce jointe.
icon	chaîne	URL de l’icône de notification personnalisée.

Limites de livraison

Champ	Type	Description
send_rate	entier	Limitation pour les envois utilisant ce préréglage, en messages/seconde — l’équivalent au niveau du préréglage de SendRate de Notify.
capping_count / capping_days	entier	Limite de fréquence par utilisateur pour ce préréglage — l’équivalent au niveau du préréglage de count / days de FrequencyCapping de Notify.

Webhooks

Champ	Type	Description
notification_sent_url	chaîne	URL de rappel demandée lorsqu’une notification utilisant ce préréglage est envoyée.
notification_delivered_url	chaîne	URL de rappel demandée lorsqu’une notification utilisant ce préréglage est livrée.
notification_click_url	chaîne	URL de rappel demandée lorsqu’une notification utilisant ce préréglage est cliquée.

Champs hérités

Ceux-ci proviennent du modèle de préréglage v1. Ils sont remplis pour la compatibilité avec le Panneau de Contrôle plutôt que pour de nouvelles intégrations.

Champ	Type	Description
remote_page	chaîne	Référence de page distante héritée.
wns_content	chaîne	JSON de modèle de toast Windows hérité, tel qu’accepté par les méthodes v1 createPreset/getPreset.
original_url	chaîne	La valeur de url avant raccourcissement, lorsque url a été remplacé par un lien raccourci.
ios_silent / android_silent / huawei_android_silent	booléen	Indicateurs de push silencieux (données uniquement) par plateforme.

Objet PlatformProperties

Champs disponibles dans chaque entrée platform_properties (IOS, ANDROID, HUAWEI_ANDROID, OSX) :

Champ	Type	Description
badge	chaîne	Surcharge du nombre de badges.
sound	chaîne	Nom du fichier son.
sound_off	booléen	Couper le son de la notification.
priority	chaîne	Priorité dans la barre de notifications (Android/Huawei uniquement).
delivery_priority	chaîne	Priorité de livraison NORMAL ou HIGH (Android/Huawei uniquement).
ios_interruption_level	chaîne	passive, active, time-sensitive, ou critical (iOS uniquement).

Sujets connexes

Notify

Référence de la charge utile

Référence des points de Customer Journey