Une variable est un emplacement réservé dans le texte d'un message. À sa place, chaque destinataire reçoit sa propre valeur — un prénom, le nom d'une société, un numéro de commande. Vous envoyez ainsi un seul texte à des milliers de personnes et chacune d'elles lit un message rédigé pour elle. Les variables s'écrivent de la même manière dans une campagne et dans l'API. ## Comment écrire une variable Une variable est un nom entre chevrons, par exemple ``. Lors de l'envoi du message, elle est remplacée par la valeur dont vous disposez pour ce destinataire : | texte du message | ce que reçoit le destinataire | |:--|:--| | `Bonjour , votre commande est en route.` | `Bonjour Pierre, votre commande est en route.` | - **Le nom doit correspondre exactement.** La casse et les espaces comptent — ni `` ni `< first_name >` ne sont remplacés par la valeur de `first_name`. - **Une valeur vide équivaut à une absence de valeur.** Un texte vide ou composé uniquement d'espaces compte comme une valeur manquante — ce qui se passe alors est décrit dans [Lorsque la valeur est manquante](#lorsque-la-valeur-est-manquante). > [!WARNING] > Tout ce qui s'écrit sous la forme ``, `` ou `` est toujours considéré comme une variable, même si vous n'avez aucune variable de ce nom, et se trouve modifié dans le message envoyé. L'écrire sous la forme `<` n'y change rien non plus. Un `<` isolé ou `` reste tel quel. ## Lorsque la valeur est manquante Lorsque vous n'avez pas de valeur pour un destinataire, la variable reste dans le message **telle quelle** — le destinataire reçoit `Bonjour , …`. Vous l'évitez grâce à une valeur par défaut écrite après deux-points : | notation | ce que reçoit un destinataire sans valeur | |:--|:--| | `` | littéralement `` | | `` | le texte de remplacement `cher client` | | `` | rien — la variable est omise | Un destinataire pour lequel vous disposez d'une valeur reçoit sa propre valeur dans les trois cas. > [!TIP] > N'utilisez une variable sans valeur par défaut que là où vous disposez des données de chaque destinataire. Sinon, ajoutez un texte de remplacement ou laissez la variable être omise. ## Filtres Un filtre ajuste la valeur insérée — il la met en majuscules, supprime les espaces, transforme un nom en formule d'appel ou surveille sa longueur. Vous l'écrivez après une barre verticale, juste après le nom de la variable : ``. Vous pouvez écrire plusieurs filtres à la suite ; ils s'appliquent de gauche à droite : `` — plus de détails dans [Enchaîner les filtres](#enchainer-les-filtres). ### Casse des lettres | notation | ce que fait le filtre | exemple | |:--|:--|:--| | `` | met toute la valeur en majuscules | `Jean Dupont` → `JEAN DUPONT` | | `` | met toute la valeur en minuscules | `Jean Dupont` → `jean dupont` | | `` | met la première lettre en majuscule et laisse le reste inchangé | `jean dupont` → `Jean dupont` | | `` | commence chaque mot par une majuscule, toutes les autres lettres sont en minuscules | `jEAN dUPONT` → `Jean Dupont` | ### Ajustements du texte | notation | ce que fait le filtre | exemple | |:--|:--|:--| | `` | supprime les espaces au début et à la fin | `" Jean Dupont "` → `"Jean Dupont"` | | `` | supprime les diacritiques | `Šťastný` → `Stastny` | | `` | transforme la valeur en une forme utilisable dans une adresse web — sans diacritiques, en minuscules, les mots reliés par un trait d'union | `Ústí nad Labem` → `usti-nad-labem` | | `` | sélectionne un mot d'après sa position ; si la valeur ne contient pas autant de mots, rien n'est inséré | `Kytary Novák` → `Kytary` | | `` | initiales — la première lettre de chaque mot, en majuscule et suivie d'un point | `Kytary Novák` → `K. N.` | ### Nom et formule d'appel Deux filtres travaillent avec des noms tchèques : `vocative` crée la formule d'appel au vocatif tchèque et `gender` choisit, d'après le nom, un texte pour un homme ou pour une femme. Ils suivent les mêmes règles que les variables `` et `` — la manière dont le vocatif est créé est décrite dans [Vocatif tchèque](https://www.bulkgate.com/fr/centre-d-aide/outils/vocatif-tcheque/). | notation | ce que fait le filtre | exemple | |:--|:--|:--| | `` | met chaque mot de la valeur au vocatif | `Petr Novák` → `Petře Nováku` | | `` | insère le premier texte pour un prénom masculin et le second pour un prénom féminin — la valeur elle-même n'est pas insérée | `Jana` → `Milá` | - **Le vocatif à partir de n'importe quelle variable.** Contrairement à ``, le filtre `vocative` peut s'appliquer à n'importe quelle variable — par exemple à un nom complet enregistré dans un seul champ, ou à une valeur que vous envoyez dans l'API. - **Le genre et le type de nom** sont reconnus par le filtre `vocative` lui-même d'après la terminaison. S'il se trompe, vous les définissez à l'aide de paramètres : le premier est `man` ou `woman`, le second `first` (prénom) ou `last` (nom de famille), par exemple ``. La valeur par défaut des deux paramètres, `auto`, laisse la décision au filtre. - **Casse des lettres.** Au vocatif, chaque mot commence par une majuscule et les autres lettres sont en minuscules : `NOVÁK` → `Nováku`. - **La valeur par défaut est elle aussi déclinée**, écrivez-la donc au nominatif : un destinataire sans nom reçoit `Zákazníku` à partir de ``. - **Le texte du genre remplace la valeur**, écrivez donc la variable deux fois dans le texte : ` ` donne `Milý Petře` ou `Milá Jano`. Le texte peut aussi n'être que la fin d'un mot : `Vážen` donne `Vážený pane` ou `Vážená paní`. Les deux textes sont obligatoires mais peuvent être vides ; ils ne doivent contenir ni `<`, ni `>`, ni `|`, ni virgule. - **Sans nom**, le genre est déterminé d'après la valeur par défaut — `` donne `Milý` à un destinataire sans nom. Une valeur par défaut vide donne toujours le texte pour un homme. > [!WARNING] > Les deux filtres suivent les règles du tchèque, quelle que soit l'origine du nom. Le prénom anglais John reçoit la forme `Johne`. Utilisez-les uniquement dans des messages destinés à des destinataires tchèques et, pour les noms inhabituels, vérifiez le résultat avec un message de test. ### Limite de longueur Les filtres avec un nombre surveillent le nombre maximal de caractères que la valeur peut comporter. Ils sont utiles pour les valeurs longues, comme le nom d'une société ou une adresse, qui feraient sinon déborder le message sur une partie SMS supplémentaire. Le filtre détermine ce qu'il advient d'une valeur plus longue : | notation | ce qu'il advient d'une valeur plus longue | « Kytary Novák » avec une limite de 8 | |:--|:--|:--| | `` | coupée à la limite — si possible entre des mots entiers | `Kytary` | | `` | coupée et complétée par `...`, le tout dans la limite | `Kytar...` | | `` | remplacée par `(...)` | `(...)` | | `` | omise | rien | | `` | remplacée par la valeur par défaut de la variable ; si elle n'en a pas, omise | `votre société` | Une valeur qui tient dans la limite est insérée en entier. Avec `truncate`, `ellipsis` et `fallback`, vous pouvez écrire après une virgule votre propre texte, qui est utilisé à la place du texte par défaut : | notation | « Kytary Novák » avec une limite de 8 | |:--|:--| | `` | `Kytary…` | | `` | `votre société` | | `` | `votre société` | Votre propre texte ne doit contenir ni `<`, ni `>`, ni `|`, ni virgule. Un texte vide (`truncate:8,`) coupe la valeur sans suffixe. ### Enchaîner les filtres Vous pouvez combiner les filtres librement — il suffit de les écrire les uns après les autres, chacun après sa propre barre verticale. Ils s'appliquent successivement de gauche à droite et chaque filtre reçoit le résultat du précédent. Vous pouvez ainsi combiner une limite de longueur avec un changement de casse et la suppression des espaces. | notation | valeur du contact | ce que reçoit le destinataire | |:--|:--|:--| | `` | `DUPONT` | `Dupont` | | `` | `" la rochelle "` | `La Rochelle` | | `` | `" Kytary Novák "` | `KYTARY…` | | `` | `Petr Pavel` | `Petře` | Dans le troisième exemple, `trim` supprime d'abord les espaces, `truncate:8,…` raccourcit la valeur à `Kytary…` et `upper` la met enfin en majuscules. - **L'ordre compte.** Les mêmes filtres dans un ordre différent donnent un résultat différent. Pour la valeur `" Ústí nad Labem "`, `` donne `Ústí`, alors que `` raccourcit d'abord la valeur aux seuls espaces initiaux, puis les supprime — il ne reste rien. - **La valeur par défaut se place avant les filtres**, et toute la chaîne l'ajuste elle aussi : un destinataire sans prénom reçoit `CHER CLIENT` à partir de ``. - **Chaque occurrence d'une variable a ses propres filtres.** Vous pouvez utiliser une même variable plusieurs fois dans le texte, chaque fois différemment : à partir de `Bonjour , `, un destinataire dont la valeur est `jean` reçoit `Bonjour Jean, JEAN`. - **Dans l'éditeur de campagne**, la chaîne suit l'ordre des filtres dans la boîte de dialogue de la variable, et vous le modifiez par glisser-déposer. Chaque filtre ne peut y être utilisé qu'une seule fois. > [!TIP] > Placez `trim` avant les filtres qui limitent la longueur. Sinon, les espaces initiaux comptent eux aussi dans la limite : à partir de la valeur `" Kytary Novák "`, `` ne donne que `" Kytary"`, alors que `` donne `Kytary`. ### Points d'attention Écrivez le nom du filtre en minuscules et sans espaces, et le nombre uniquement en chiffres. > [!IMPORTANT] > Ni un filtre ni une limite n'empêchent une variable sans valeur de rester dans le texte. Un destinataire pour lequel vous n'avez pas de valeur reçoit littéralement `` à partir de ``. Si vous voulez un texte de remplacement, écrivez-le après deux-points, avant les filtres : ``. > [!WARNING] > Une faute de frappe dans un filtre casse la variable. Avec un filtre inconnu ou un nombre manquant — ``, `` — la notation cesse d'être une variable et reste littéralement dans le texte, même pour les destinataires qui ont un prénom. Lorsque la variable a une valeur par défaut, le filtre erroné devient une partie du texte de remplacement : `` insère le prénom, ou `cher client|Upper`. ### Ancienne notation avec le signe égal Autrefois, la longueur se limitait à l'aide d'un raccourci : la limite s'écrivait après un signe égal, suivie d'une lettre qui déterminait ce qu'il advient d'une valeur plus longue. **Cette notation est obsolète** — utilisez les filtres dans les nouveaux messages. Les messages qui la contiennent continuent de fonctionner et l'éditeur de campagne la réécrit en filtre. | ancienne notation | remplacer par le filtre | |:--|:--| | `` ou `` | `` | | `` | `` | | `` | `` | | `` | `` | | `` | `` | Le raccourci est appliqué comme premier filtre, même si d'autres filtres le suivent : `` équivaut à ``. ## Variables dans une campagne Une campagne reprend les valeurs des contacts que vous y ajoutez — depuis le carnet d'adresses, depuis l'import d'un fichier et depuis les numéros saisis manuellement. 1. **Ajoutez d'abord les destinataires.** Le menu des variables n'affiche que les champs renseignés chez au moins un destinataire de la campagne. Sans destinataires, il est vide. 2. Dans l'éditeur de texte, cliquez sur l'icône `Ajouter une variable` ou tapez simplement `@`. La saisie d'un nom affine le menu. 3. Choisissez la variable. Pour chacune, vous voyez quel pourcentage de destinataires dispose de ces données. La variable apparaît dans le texte sous la forme d'une étiquette portant le nom du champ, et sa couleur vous indique où vous en êtes avec les données : - **sans mise en évidence** — tous les destinataires ont les données, ou une valeur par défaut est définie, - **avertissement** — 30 à 99 % des destinataires ont les données, - **erreur** — moins de 30 % des destinataires ont les données, ou ce champ n'existe pas. Cliquez sur l'étiquette pour afficher un récapitulatif de la variable, y compris ses filtres actifs dans l'ordre de leur application, et modifiez-la à partir de là : - **Lorsque la valeur est manquante** — ajoutez un texte de remplacement, laissez la variable être omise ou conservez-la dans le texte. - **Filtres** — ajoutez-les un par un depuis un menu divisé en casse des lettres, ajustements du texte, nom et formule d'appel, et longueur. Pour les filtres avec un paramètre, vous saisissez un nombre ou un texte, ou choisissez une option. Vous modifiez l'ordre en faisant glisser la poignée — les filtres s'appliquent de haut en bas — et vous supprimez un filtre dont vous n'avez pas besoin. Une valeur d'exemple montre l'effet du filtre. L'éditeur enregistre la variable dans la même notation que celle décrite dans [Lorsque la valeur est manquante](#lorsque-la-valeur-est-manquante) et [Filtres](#filtres), par exemple ``. Un ancien raccourci avec le signe égal est réécrit en filtre au passage. ### Quels champs pouvez-vous utiliser | variable | ce qu'elle contient | |:--|:--| | ``, `` | prénom et nom | | ``, `` | prénom et nom au vocatif tchèque — remplis automatiquement, voir [Vocatif tchèque](https://www.bulkgate.com/fr/centre-d-aide/outils/vocatif-tcheque/) | | ``, `` | titre avant et après le nom | | `` | nom de la société | | ``, `` | numéro d'identification de la société et numéro de TVA | | `` | e-mail | | `` | adresse web | | ``, ``, ``, ``, ``, `` | adresse — rue, ville, code postal, État, pays | | `` | numéro de téléphone | | `` | note | | `` à `` | champs personnalisés | Lorsque vous [importez depuis un fichier](https://www.bulkgate.com/fr/centre-d-aide/campagne/importer-des-contacts-depuis-csv-excel/), vous associez chaque colonne à l'un de ces champs. Une colonne qui ne correspond à aucun d'eux — un numéro de commande, un montant de remise — va dans un champ personnalisé, et dans le texte vous utilisez alors, par exemple, ``. ### Canaux, longueur et aperçu - **Canaux.** Les variables fonctionnent dans le texte des messages SMS, Viber et RCS, et pour RCS également dans le titre. - **Longueur et prix.** Le compteur de caractères de l'éditeur tient compte des valeurs du contact sélectionné dans l'aperçu. Chaque destinataire peut toutefois avoir des valeurs de longueur différente — le nombre de parties SMS et le prix sont donc calculés pour chaque destinataire séparément, après l'insertion des valeurs. - **Unicode.** Les diacritiques d'une valeur insérée ne font passer le SMS en Unicode que si vous l'avez activé dans les paramètres du texte. - **Aperçu.** L'aperçu du message comme `Envoyer un message de test` insèrent les valeurs du contact sélectionné dans l'aperçu — vous voyez ainsi le rendu du texte avant l'envoi. Les filtres `vocative` et `gender` font exception : l'aperçu de l'éditeur ne décline pas le nom, il le marque seulement de 🗣️, et pour `gender` il affiche les deux textes, par exemple `Milý/Milá`. Le compteur de caractères tient compte, lui aussi, de ces formes. Le résultat réel s'affiche dans un message de test. ## Variables dans l'API Dans l'API, vous envoyez les valeurs directement dans la requête, dans le paramètre `variables` : un objet dont la clé est le nom de la variable et la valeur ce qui doit être inséré. Le texte utilise la même notation, y compris les valeurs par défaut et les [filtres](#filtres). ```json { "number": "420777777777", "text": "Bonjour , la commande est en route.", "variables": {"first_name": "Pierre", "order": "12345"} } ``` Le destinataire reçoit `Bonjour Pierre, la commande 12345 est en route.` Vous pouvez nommer une variable comme vous le souhaitez — `` dans l'exemple n'est pas un champ de contact, mais simplement une clé de `variables`. ### Où placer les variables | API | où placer `variables` | |:--|:--| | [Advanced API – messages transactionnels](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-transactional/2.0/) | avec l'ensemble du message ; en version 2.0, également avec chaque numéro de `number` séparément — les valeurs associées au numéro ont la priorité | | [Advanced API – messages promotionnels](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-promotional/2.0/) | avec chaque numéro de `number` séparément ; `variables` au niveau de l'ensemble du message n'est pas utilisé | | [Advanced API – groupes du carnet d'adresses](https://www.bulkgate.com/fr/documentation/advanced-api/advanced-promotional-envoi-aux-groupes-du-carnet-d-adresses/) | non envoyé — ce sont les champs des contacts du carnet d'adresses qui sont insérés, avec les mêmes noms que dans une [campagne](#quels-champs-pouvez-vous-utiliser) | | [Integration API](https://www.bulkgate.com/fr/documentation/integration-api/integration-transactional/) | avec chaque message | ### Quelles valeurs envoyer - **Texte ou nombre.** Les nombres sont insérés tels quels (`12` → `12`). - **`null`, `false` et un texte vide** comptent comme une valeur manquante — la [valeur par défaut](#lorsque-la-valeur-est-manquante) s'applique, sinon la variable reste littéralement dans le texte. - **Un tableau ou un objet comme valeur** n'est pas accepté par l'Advanced API, qui renvoie l'erreur `invalid_input_parameters`. - **Les clés superflues** qui ne figurent pas dans le texte sont ignorées. - **Vocatif.** À partir de `first_name` et `last_name`, l'Advanced API calcule elle-même `first_name_vokativ` et `last_name_vokativ` — elle écrase vos propres valeurs de ces deux clés. L'Integration API ne calcule pas le vocatif. Son fonctionnement est décrit dans [Vocatif tchèque](https://www.bulkgate.com/fr/centre-d-aide/outils/vocatif-tcheque/). ### Canaux et longueur | canal | où les variables sont insérées | |:--|:--| | SMS | texte | | Viber | texte, libellé du bouton et lien | | RCS | texte, titre et description de la carte | | Voix | texte | Le nombre de parties SMS et le prix sont tous deux calculés à partir du texte après l'insertion des valeurs. Les diacritiques d'une valeur insérée ne font passer le SMS en Unicode qu'avec `"unicode": true`. Un texte Viber, RCS ou WhatsApp qui dépasse la limite du canal après l'insertion des valeurs (Viber 1 000 caractères, RCS et WhatsApp 5 000) est tronqué. > [!NOTE] > Les plugins pour e-shops ont leur propre jeu de variables, par exemple ``. Ils sont décrits dans [SMS clients](https://www.bulkgate.com/fr/centre-d-aide/integrations/modules-sms/sms-clients/).