Substitutions et formules

Les substitutions sont des variables de la forme {{...}} qui sont insérées dans les textes des messages, les champs d'actions et les templates de boutons lors du déclenchement d'une réaction. Les substitutions non reconnues restent telles quelles. En plus des variables, il existe des formules pour les calculs. Le bouton « Substitutions » dans l'éditeur de message facilite l'insertion de variables.

Données de l'expéditeur

  • {{first_name}}, {{last_name}} — prénom et nom.
  • {{username}} — @username de l'utilisateur.
  • {{user_id}} — identifiant Telegram numérique.

Données de l'événement et du chat

  • {{text}} (alias {{received_message}}) — texte du message entrant.
  • {{message_id}} (alias {{received_message_id}}) — identifiant du message entrant.
  • {{chat_id}}, {{chat_title}} (alias {{chat_name}}) — chat où l'événement s'est produit.
  • {{topic_id}}, {{topic_url}} — sujet (pour les forums).

Date et heure

  • {{date}} — date (AAAA-MM-JJ), {{time}} — heure (HH:MM), {{datetime}} — date et heure.
  • Formatage : {{date:DD.MM.YYYY HH:mm}} — tokens YYYY, YY, MM, DD, HH, mm, ss.

Paramètres utilisateur

  • {{param.clé}} (alias {{params.clé}} ou {{recipient.clé}}) — valeur d'un paramètre de l'abonné. Les paramètres sont alimentés par les actions « Modifier les paramètres », « Enregistrer le message » et les réponses dans le dialogue.

Contexte d'exécution (ctx)

  • {{ctx.clé}} (alias {{context.clé}}) — valeurs temporaires de l'exécution en cours : données d'un webhook entrant, résultats des actions (requête web, requête vers une source, IA), données restaurées d'un bouton (Carry), éléments d'une boucle.
  • Dans une boucle sur une liste, l'élément est accessible via son alias, par exemple {{item.name}}.

Formules

La construction {{= expression}} évalue l'expression directement dans le texte. Le même moteur fonctionne dans l'action « Calcul » et dans les conditions des tableaux de décision. Dans les expressions, vous pouvez référencer des paramètres et des valeurs de ctx par leur nom, utiliser l'arithmétique, les comparaisons, la logique et des dizaines de fonctions (ROUND, IF, CONCAT, etc.).

Exemple : {{= ROUND(param.total * 0.9) }} — remise de 10 % sur le montant issu du paramètre.

Syntaxe complète et liste des fonctions — dans la section Formules.

HTML dans les substitutions

Les messages sont envoyés avec un balisage HTML. Pour qu'une valeur substituée ne casse pas la mise en page (par exemple lorsqu'un nom d'utilisateur contient <), les valeurs substituées sont échappées par défaut : les caractères HTML deviennent du texte sûr. Les balises que vous écrivez directement dans le texte de la réaction (<b>, <a>, …) restent intactes.

Si une valeur contient elle-même un balisage prêt à l'emploi (par exemple une annonce stockée dans un paramètre avec <b>...</b>) et que vous souhaitez l'insérer telle quelle, préfixez la substitution par & :

  • {{& key}} — insertion brute pour les substitutions {{...}}.
  • {&user:key}, {&recipient:key}, {&global:key} — insertion brute pour les substitutions de namespace.

Le préfixe & désactive l'échappement pour cette seule substitution — vous vous portez garant de la confiance accordée à la source de la valeur. Il vaut mieux laisser échappés les tokens contrôlés par l'abonné ({{first_name}}, …).

Lors de l'import de bots depuis d'autres constructeurs, les substitutions de namespace {user:…}/{recipient:…}/{global:…} sont automatiquement migrées vers la forme brute {&…} — elles contiennent généralement des valeurs avec un balisage prêt à l'emploi, comme cela fonctionnait dans le constructeur d'origine.

Important sur le format

Les substitutions {{...}} fonctionnent dans les textes, les légendes, les corps de requêtes et les templates de boutons. Donnez aux noms de paramètres et aux clés ctx des noms courts en caractères latins (email, total, order_id) — plus pratiques à insérer.

Pour aller plus loin