Variables des AI Actions

Partout où vous pouvez saisir une valeur dans une API Action (URL, headers, body ou query parameters), vous pouvez injecter des valeurs dynamiques avec la syntaxe {{...}}. Quickchat substitue ces marqueurs au moment de la requête, juste avant d’appeler votre endpoint.

Cliquez sur le bouton + Add AI Data à côté de n’importe quel champ de valeur pour parcourir toutes les variables disponibles dans le scénario en cours.

Le bouton + Add AI Data est disponible à côté de chaque champ de valeur : l’URL du endpoint, la valeur de chaque header, les champs du body et les query parameters.

Trois catégories de variables

Catégorie	Syntaxe	Quand elle est remplie
Paramètres IA. Valeurs que votre Agent IA extrait de la conversation. Vous les définissez dans la section Parameters de chaque Action.	{{order_number}}, {{customer_email}}	L’Agent IA les remplit au moment de l’appel, selon les règles que vous écrivez dans la description de chaque paramètre.
Variables intégrées. Contexte de la conversation que Quickchat injecte automatiquement.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Toujours disponibles. Quickchat les substitue à chaque requête.
Métadonnées de conversation. Paires clé-valeur personnalisées rattachées à la conversation.	{{metadata_<key>}}	Dès que la clé correspondante existe sur la conversation (définie par le widget, une intégration de canal, Smart Data Gathering ou l’API).

Astuce

Chaque variable est rendue sous forme de pill coloré dans l’éditeur. Bleu signifie qu’il s’agit d’un paramètre IA ou d’une variable intégrée. Orange signifie qu’il s’agit d’une variable de métadonnées ou d’un system token. Rouge signifie que le nom ne correspond à rien que Quickchat connaisse (généralement une faute de frappe).

Le dropdown ”+ Add AI Data”

Le dropdown liste toutes les variables disponibles pour le scénario en cours, regroupées en cinq sections :

1. Parameters : les paramètres IA que vous avez définis sur cette Action.
2. Visitor : quatre clés de métadonnées auto-capturées pour chaque visiteur, lorsque son canal les fournit.
3. Metadata (used in recent conversations) : clés de métadonnées personnalisées observées dans les 20 dernières conversations de ce scénario, avec un exemple de valeur pour chacune.
4. Built-in : les six variables de conversation toujours disponibles, avec leur valeur actuelle ou un exemple affiché en ligne.
5. System Tokens : identifiants fournis par une intégration connectée (p. ex. HubSpot). N’apparaît que si l’intégration est connectée.

Le dropdown regroupe les variables par section. Les lignes Built-in affichent la valeur en direct lorsqu’elle est déjà connue (scenario_id) et des exemples e.g. … pour les autres. Le groupe Metadata (used in recent conversations) est reconstruit par scénario à partir des conversations récentes réelles. La section System Tokens (non illustrée ici) n’apparaît que lorsqu’une intégration est connectée.

Note

La liste Metadata (used in recent conversations) est reconstruite à partir des 20 conversations les plus récentes de votre scénario et mise en cache pendant 5 minutes par Agent IA. Une clé de métadonnées définie sur une toute nouvelle conversation peut mettre jusqu’à 5 minutes à apparaître dans cette section. Vous pouvez toujours taper {{metadata_<your_key>}} directement : Quickchat n’exige pas que la clé apparaisse dans le dropdown pour que la substitution fonctionne.

Variables intégrées

Ces six variables sont toujours disponibles. Le dropdown + Add AI Data affiche la valeur en direct (lorsqu’elle est déjà connue) ou un exemple de valeur à côté de chaque ligne.

Variable	Exemple	Ce que c’est
{{scenario_id}}	abc123xyz	ID de l’Agent IA auquel appartient la conversation.
{{conversation_id}}	conv-d8a8…	Identifiant unique de la conversation.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Lien direct vers cette conversation dans la Boîte de réception (Inbox).
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Canal sur lequel se déroule la conversation.
{{language}}	en, nl, de, fr, …	Code ISO 639-1 en minuscules de la langue de la conversation.
{{country}}	US, GB, NL, DE, …	Code pays ISO 3166-1 alpha-2 en majuscules.

Quelques précisions utiles :

• {{scenario_id}} est également visible dans l’URL du navigateur pendant que vous éditez l’Action. Le dropdown + Add AI Data affiche l’ID en direct du scénario en cours d’édition, pas un exemple.
• {{conversation_url}} est utile pour publier des liens cliquables dans Slack, Jira ou tout autre outil qui bénéficie d’un saut direct vers la Boîte de réception.
• {{language}} est dérivé (dans cet ordre) : du préfixe d’URL de la page (pour Shopify Markets), des métadonnées de la conversation, puis de la langue configurée de votre Agent IA.
• {{country}} est dérivé (dans cet ordre) : du préfixe d’URL de la page, du TLD de l’hôte de l’URL, puis d’un fallback langue-vers-pays.

Métadonnées de conversation

Le préfixe metadata_ est requis. Quickchat cherche <key> dans les métadonnées de la conversation et substitue sa valeur dans la requête.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

Clés de métadonnées du visiteur

Ces quatre clés décrivent la session du visiteur et bénéficient de leur propre section Visitor dans le dropdown. Elles sont auto-capturées par le canal, l’intégration, le widget/embed ou l’API. Vous n’avez pas besoin de les pousser vous-même.

Variable	Auto-capturée par
{{metadata_fullPathURL}}	Widget de site web, embed de site web ou intégrations de canal de chat qui incluent leur propre widget (HubSpot, Intercom, etc.).
{{metadata_visitor_name}}	Profil de canal de chat (Telegram, Slack, etc.), intégrations de canal, Smart Data Gathering, votre widget/embed ou l’API Quickchat.
{{metadata_visitor_email}}	Profil de canal de chat, intégrations de canal, Smart Data Gathering, votre widget/embed ou l’API Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp et autres canaux conscients du téléphone, intégrations de canal, Smart Data Gathering, votre widget/embed ou l’API Quickchat.

Clés de métadonnées personnalisées

Vous pouvez attacher des paires clé-valeur arbitraires à une conversation et les référencer en tant que {{metadata_<key>}}.

Depuis le widget ou l’embed du site web

Passez custom_params lors de l’initialisation du widget. Consultez la section Canal Website : Advanced Features : Custom Parameters pour l’extrait complet.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

Référencez-les dans n’importe quelle Action en tant que {{metadata_order_id}} et {{metadata_customer_tier}}.

Attention

Les clés de métadonnées doivent correspondre à ^[a-zA-Z0-9_]+$ (lettres, chiffres, underscores). Les clés avec des espaces ou d’autres signes de ponctuation ne peuvent pas être référencées via {{metadata_<key>}}. Elles apparaîtront tout de même dans la vue des métadonnées de la conversation dans la Boîte de réception, mais la substitution dans l’Action les ignorera. Restez sur des noms en snake_case lorsque vous comptez les utiliser dans des Actions.

Depuis Smart Data Gathering

Chaque nom de champ que vous configurez dans une campagne Smart Data Gathering devient une clé de métadonnées sous le même nom. Si votre campagne collecte delivery_address, vous pouvez immédiatement utiliser {{metadata_delivery_address}} dans toute API Action ultérieure.

Depuis les intégrations de canal

HubSpot, Intercom, Telegram, Slack, WhatsApp et les intégrations similaires poussent leurs propres métadonnées sur la conversation (nom du visiteur, e-mail, URL de la page, propriétés de compte, etc.). Tout ce qui est visible dans la vue des métadonnées de la conversation dans la Boîte de réception peut être référencé via {{metadata_<key>}}.

Depuis l’API Quickchat

Utilisez POST /v1/api_core/conversations/{conv_id}/metadata pour attacher des métadonnées par programmation. Consultez Conversation Metadata dans la référence de l’API.

Couleurs des pills dans l’éditeur

Chaque référence {{...}} est rendue sous forme de pill coloré pour que vous puissiez voir d’un coup d’œil si Quickchat reconnaît la variable.

Les pills fonctionnent dans chaque champ de valeur. Ci-dessus : un pill orange {{metadata_user_type}} dans l’URL du endpoint, et un pill bleu {{language}} dans la valeur d’un header.

Les mêmes règles de couleur s’appliquent à l’intérieur d’un body JSON de requête. Les variables intégrées comme {{country}} apparaissent en bleu, les variables de métadonnées comme {{metadata_fullPathURL}} en orange.

• 🔵 Bleu : une variable intégrée ou un paramètre IA que vous avez défini.
• 🟠 Orange : une variable de métadonnées ({{metadata_*}}) ou un System Token d’une intégration connectée.
• 🔴 Rouge : Quickchat ne reconnaît pas ce nom. Presque toujours une faute de frappe. Corrigez l’orthographe, définissez-le comme paramètre IA, ou (s’il s’agit vraiment d’une clé de métadonnées) assurez-vous qu’il commence par metadata_.

Astuce

Taper {{metadata_anything}} directement est toujours valide, même si la clé n’est jamais apparue dans une conversation. Le pill sera orange, pas rouge. C’est la bonne façon de câbler les clés que vous définissez vous-même depuis un script de widget ou Smart Data Gathering avant que la première conversation n’ait eu lieu.

Tester votre Action

Le panneau Test Response (à côté de Done dans l’éditeur d’Action) vous permet d’envoyer une vraie requête HTTP sans passer par un chat. Pour chaque variable référencée dans l’Action, vous verrez une ligne de saisie pour renseigner la valeur que Quickchat substituera.

Deux pré-remplissages pratiques :

• {{language}} vaut en par défaut
• {{country}} vaut US par défaut

Remplacez l’un ou l’autre champ pour tester une autre locale. Toutes les autres variables (vos paramètres IA, clés {{metadata_*}} et les autres built-ins) démarrent vides. Tapez n’importe quelle valeur pour simuler ce qui se passerait dans une conversation en direct.

FAQ

Pourquoi ma variable apparaît-elle en rouge ? L’éditeur ne reconnaît pas le nom. Soit c’est une faute de frappe, soit il ne correspond à aucun paramètre IA que vous avez défini, soit ce n’est pas une variable intégrée, soit c’est une clé de métadonnées à laquelle il manque le préfixe metadata_.

Puis-je injecter {{language}} ou {{country}} même si je ne les définis jamais ? Oui. Quickchat dérive toujours les deux à partir du contexte de la conversation (URL de la page, locale du navigateur, ou langue configurée de votre Agent IA). Vous obtiendrez toujours une valeur, même si elle retombe sur en / US.

Quelle est la différence entre {{language}} et {{metadata_locale}} ?

• {{language}} est la variable intégrée. Toujours disponible, toujours au format en / nl / de … Utilisez-la dans 99 % des cas.
• {{metadata_locale}} n’existe que si une intégration de canal ou votre widget a explicitement défini une clé locale dans les métadonnées de la conversation, souvent au format xx_YY (p. ex. en_GB). N’y recourez que lorsque vous avez besoin de la chaîne de locale exacte au mot près.

Y a-t-il une limite au nombre de paramètres IA par Action ? Oui, 30 par Action. Si vous avez vraiment besoin de plus, contactez le support.

Les valeurs intégrées et de métadonnées sont-elles envoyées à l’IA ? Non. Elles sont injectées dans la requête HTTP après que l’IA ait décidé d’appeler l’Action. L’IA ne les voit pas et il ne lui est pas demandé de les remplir. C’est pourquoi elles n’ont pas besoin d’être définies comme paramètres IA.

À quelle fréquence la liste « Metadata (used in recent conversations) » est-elle rafraîchie ? Elle est mise en cache pendant 5 minutes par Agent IA. Une clé de métadonnées définie sur une toute nouvelle conversation peut mettre jusqu’à 5 minutes à apparaître dans le dropdown, mais vous pouvez toujours taper {{metadata_<your_key>}} directement sans attendre.

Les noms de clés de métadonnées sont-ils sensibles à la casse ? Oui. {{metadata_orderId}} et {{metadata_orderid}} sont des clés différentes. Utilisez exactement la même casse que celle définie côté widget, intégration ou API.

Le panneau Test Response connaît-il ces variables ? Oui. Lorsque votre Action référence {{language}} ou {{country}}, le panneau Test Response les pré-remplit respectivement avec en et US. Toutes les autres variables démarrent vides. Tapez n’importe quelle valeur pour simuler un appel en direct.

En rapport

• Custom Actions : comment créer et configurer une API Action.
• Canal Website : Custom Parameters : comment pousser des métadonnées depuis votre site web.
• API : Conversation Metadata : comment pousser des métadonnées par programmation.