AI Action Variables

Anywhere you can type a value in an API Action (URL, headers, body, or query parameters) you can inject dynamic values using the {{...}} syntax. Quickchat substitutes these placeholders at request time, just before calling your endpoint.

Click the + Add AI Data button next to any value field to browse every variable available in the current scenario.

The + Add AI Data button is available next to every value field: the endpoint URL, each header value, body fields, and query parameters.

Three categories of variables

Category	Syntax	When it’s filled
AI parameters. Values your AI Agent extracts from the conversation. You define them under each Action’s Parameters section.	{{order_number}}, {{customer_email}}	The AI Agent fills these at call time, based on the rules you write into each parameter’s description.
Built-in variables. Conversation context Quickchat injects automatically.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Always available. Quickchat substitutes them on every request.
Conversation metadata. Custom key-value pairs attached to the conversation.	{{metadata_<key>}}	Whenever the corresponding key exists on the conversation (set by the widget, a channel integration, Smart Data Gathering, or the API).

Tip

Each variable is rendered as a coloured pill inside the editor. Blue means it’s an AI parameter or a built-in. Orange means it’s a metadata variable or a system token. Red means the name doesn’t match anything Quickchat knows (usually a typo).

The ”+ Add AI Data” dropdown

The dropdown lists every variable available for the current scenario, grouped into five sections:

1. Parameters: the AI parameters you defined on this Action.
2. Visitor: four metadata keys auto-captured for every visitor, when their channel provides them.
3. Metadata (used in recent conversations): custom metadata keys seen on this scenario’s last 20 conversations, with a sample value for each.
4. Built-in: the six conversation variables that are always available, with their current value or a sample shown inline.
5. System Tokens: credentials provided by a connected integration (e.g. HubSpot). Only appears if the integration is connected.

The dropdown groups variables into sections. Built-in rows show the live value where it’s already known (scenario_id) and e.g. … samples for the rest. The Metadata (used in recent conversations) group is rebuilt per scenario from real recent conversations. The System Tokens section (not shown here) appears only when an integration is connected.

Note

The Metadata (used in recent conversations) list is rebuilt from your scenario’s most recent 20 conversations and cached for 5 minutes per AI Agent. A metadata key set on a brand-new conversation may take up to 5 minutes to appear in this section. You can always type {{metadata_<your_key>}} directly: Quickchat doesn’t require the key to appear in the dropdown for the substitution to work.

Built-in variables

These six variables are always available. The + Add AI Data dropdown shows the live value (where it’s already known) or a sample value next to each row.

Variable	Example	What it is
{{scenario_id}}	abc123xyz	ID of the AI Agent the conversation belongs to.
{{conversation_id}}	conv-d8a8…	Unique identifier of the conversation.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Direct Inbox link to this conversation.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Channel the conversation is happening on.
{{language}}	en, nl, de, fr, …	ISO 639-1 lowercase code of the conversation language.
{{country}}	US, GB, NL, DE, …	ISO 3166-1 alpha-2 uppercase country code.

A few notes worth knowing:

• {{scenario_id}} is also visible in your browser URL while editing the Action. The + Add AI Data dropdown shows the live ID for the scenario you’re editing, not a sample.
• {{conversation_url}} is useful for posting clickable links into Slack, Jira, or any other tool that benefits from a direct jump back to the Inbox.
• {{language}} is derived from (in this order): the page URL prefix (for Shopify Markets), conversation metadata, then your AI Agent’s configured language.
• {{country}} is derived from (in this order): the page URL prefix, the URL host TLD, then a language-to-country fallback.

Conversation metadata

The metadata_ prefix is required. Quickchat looks up <key> in the conversation’s metadata and substitutes its value into the request.

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

Visitor metadata keys

These four keys describe the visitor’s session and get their own Visitor section in the dropdown. They are auto-captured by the channel, integration, widget/embed, or API. You don’t need to push them yourself.

Variable	Auto-captured by
{{metadata_fullPathURL}}	Website widget, website embed, or chat-channel integrations that include their own widget (HubSpot, Intercom, etc.).
{{metadata_visitor_name}}	Chat-channel profile (Telegram, Slack, etc.), channel integrations, Smart Data Gathering, your widget/embed, or the Quickchat API.
{{metadata_visitor_email}}	Chat-channel profile, channel integrations, Smart Data Gathering, your widget/embed, or the Quickchat API.
{{metadata_visitor_phone_number}}	WhatsApp and other phone-aware channels, channel integrations, Smart Data Gathering, your widget/embed, or the Quickchat API.

Custom metadata keys

You can attach arbitrary key-value pairs to a conversation and reference them as {{metadata_<key>}}.

From the website widget or embed

Pass custom_params when you initialise the widget. See the Website channel: Advanced Features: Custom Parameters section for the full snippet.

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

Reference them in any Action as {{metadata_order_id}} and {{metadata_customer_tier}}.

Caution

Metadata keys must match ^[a-zA-Z0-9_]+$ (letters, digits, underscores). Keys with spaces or other punctuation cannot be referenced as {{metadata_<key>}}. They will still appear in the conversation’s metadata view in the Inbox, but the Action substitution will skip them. Stick to snake_case names when you intend to use them in Actions.

From Smart Data Gathering

Each field name you configure in a Smart Data Gathering campaign becomes a metadata key under the same name. If your campaign collects delivery_address, you can immediately use {{metadata_delivery_address}} in any subsequent API Action.

From channel integrations

HubSpot, Intercom, Telegram, Slack, WhatsApp, and similar integrations push their own metadata onto the conversation (visitor name, email, page URL, account properties, etc.). Anything visible in the conversation’s metadata view in the Inbox can be referenced via {{metadata_<key>}}.

From the Quickchat API

Use POST /v1/api_core/conversations/{conv_id}/metadata to attach metadata programmatically. See Conversation Metadata in the API reference.

Pill colours in the editor

Every {{...}} reference is rendered as a coloured pill so you can tell at a glance whether Quickchat recognises the variable.

Pills work in every value field. Above: an orange {{metadata_user_type}} pill in the endpoint URL, and a blue {{language}} pill in a header value.

The same colour rules apply inside a JSON request body. Built-in variables like {{country}} render blue, metadata variables like {{metadata_fullPathURL}} render orange.

• 🔵 Blue: a built-in variable or an AI parameter you defined.
• 🟠 Orange: a metadata variable ({{metadata_*}}) or a System Token from a connected integration.
• 🔴 Red: Quickchat doesn’t recognise this name. Almost always a typo. Fix the spelling, define it as an AI parameter, or (if it really is a metadata key) make sure it starts with metadata_.

Tip

Typing {{metadata_anything}} directly is always valid, even if the key has never appeared on a conversation yet. The pill will be orange, not red. This is the right way to wire up keys you set yourself from a widget script or Smart Data Gathering before the first conversation has happened.

Testing your Action

The Test Response sheet (next to Done in the Action editor) lets you send a real HTTP request without going through a chat. For each variable referenced in the Action, you’ll see an input row to fill in the value Quickchat will substitute.

Two convenience pre-fills:

• {{language}} defaults to en
• {{country}} defaults to US

Override either field to test a different locale. All other variables (your AI parameters, {{metadata_*}} keys, and the other built-ins) start blank. Type any value to simulate what would happen in a live conversation.

FAQ

Why does my variable appear in red? The editor doesn’t recognise the name. Either it’s a typo, it doesn’t match any AI parameter you’ve defined, it isn’t a built-in variable, or it’s a metadata key that’s missing the metadata_ prefix.

Can I inject {{language}} or {{country}} even if I never set them? Yes. Quickchat always derives both from the conversation context (page URL, browser locale, or your AI Agent’s configured language). You’ll always get a value, even if it falls back to en / US.

What’s the difference between {{language}} and {{metadata_locale}}?

• {{language}} is the built-in. Always available, always in en / nl / de … format. Use this 99% of the time.
• {{metadata_locale}} only exists if a channel integration or your widget explicitly set a locale key on the conversation metadata, often in xx_YY format (e.g. en_GB). Reach for this only when you need the exact locale string verbatim.

Is there a limit on the number of AI parameters per Action? Yes, 30 per Action. If you genuinely need more, contact support.

Are built-in and metadata values sent to the AI? No. They’re injected into the HTTP request after the AI has decided to call the Action. The AI doesn’t see them and isn’t asked to fill them in. That’s why they don’t need to be defined as AI parameters.

How often is the “Metadata (used in recent conversations)” list refreshed? It’s cached for 5 minutes per AI Agent. A metadata key set on a brand-new conversation may take up to 5 minutes to appear in the dropdown, but you can always type {{metadata_<your_key>}} directly without waiting.

Are metadata key names case-sensitive? Yes. {{metadata_orderId}} and {{metadata_orderid}} are different keys. Use exactly the same casing you set on the widget, integration, or API side.

Does the Test Response sheet know about these variables? Yes. When your Action references {{language}} or {{country}}, the Test Response sheet pre-fills them with en and US respectively. All other variables start blank. Type any value to simulate a live call.

Related

• Custom Actions: how to create and configure an API Action.
• Website channel: Custom Parameters: how to push metadata from your website.
• API: Conversation Metadata: how to push metadata programmatically.