# Variables

Variables let you define reusable values that any node in your workflow can access. Use them to configure agent behavior, track conversation state, and personalize responses based on user input or system data. You can reference them in any text box using the `{{variableName}}`  syntax.

### What Is a Variable

A variable is a named key-value pair that stores data your agent can read and write during a conversation. Variables act as the shared memory between nodes — one node sets a value, and any downstream node can consume it to make decisions, personalize messages, or call external APIs. 

Every conversation gets its own copy of variable values. Two users chatting with the same agent at the same time each have independent variable states, so one conversation never leaks data into another.

Variables can be overwritten at runtime unless marked as constant. You reference them anywhere in your workflows using the `{{variableName}}` syntax.

<table data-column-title-hidden data-view="cards"><thead><tr><th>Method</th><th>Description</th><th data-hidden data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-table-columns">:table-columns:</i></h4><h4>Variables Dashboard</h4></td><td>Define static variables with default values in <strong>Designer > AI > Variables</strong>. </td><td><a href="#the-variables-dashboard">#the-variables-dashboard</a></td></tr><tr><td><h4><i class="fa-brackets-curly">:brackets-curly:</i></h4><h4>Variable Node</h4></td><td>Set or update a variable mid-workflow with the Variable node. </td><td><a href="#using-the-variable-node">#using-the-variable-node</a></td></tr><tr><td><h4><i class="fa-hexagon-nodes">:hexagon-nodes:</i></h4><h4>LLM Node</h4></td><td>Map JSON response properties from the LLM  output directly to variables.</td><td><a href="#setting-variables-from-llm-nodes">#setting-variables-from-llm-nodes</a></td></tr></tbody></table>

#### Controlling Workflow Logic with Variables

Variables become especially useful when paired with a Flow Control node. The typical pattern is:

1. An LLM or Variable node sets a value based on something that happened earlier in the conversation — for example, storing the user's selected department as `{{department}}`
2. A Flow Control node reads that variable and branches the workflow into different paths depending on its value
3. Each branch leads to a different sequence of nodes (e.g., one path for billing, another for technical support)

This lets you build workflows that adapt to each conversation. Instead of creating separate workflows for every scenario, you use variables to route users dynamically within a single workflow.

### Variable Types

The platform supports five types of variables.&#x20;

<table><thead><tr><th width="147">Type</th><th width="189">Scope</th><th width="198">Managed In</th><th>Persists After Session</th></tr></thead><tbody><tr><td><strong>Question</strong></td><td>Single conversation</td><td>Question node</td><td>No</td></tr><tr><td><strong>Session</strong></td><td>Single conversation</td><td>Variable node</td><td>No</td></tr><tr><td><strong>Contact</strong></td><td>Across sessions per contact</td><td>Variable node / Built-in</td><td>Yes</td></tr><tr><td><strong>Static</strong></td><td>Agent-wide defaults</td><td><strong>Designer > AI > Variables</strong></td><td>N/A — initializes per session</td></tr><tr><td><strong>System</strong></td><td>Platform-provided</td><td>Built-in</td><td>N/A — read-only</td></tr></tbody></table>

<details>

<summary><strong>Question Variables</strong></summary>

Automatically created when you add a Question node to a workflow. The user's answer is stored in a variable named after the question, making it available to any subsequent node in the same session.

Use for: capturing user input like names, email addresses, or selections without manually configuring a Variable node.

</details>

<details>

<summary><strong>Session Variables</strong></summary>

Scoped to a single conversation. The value initializes when the session starts and is discarded when the session ends.

Use for: temporary state like `session_topic`, conversation counters, or routing flags.

</details>

<details>

<summary><strong>Contact Variables</strong></summary>

Persists across sessions. The value is stored on the contact record and carries over to future conversations with the last assigned value. The platform includes several built-in contact variables; you can find the full breakdown in the reference section below.

Use for: user preferences, language selection, or any data that should survive between sessions.

{% hint style="warning" %}
A contact is any user who has interacted with an agent from any channel. Since users are typically not authenticated, each channel creates a separate contact — the same person chatting via Webchat and WhatsApp is treated as two different contacts.
{% endhint %}

</details>

<details>

<summary><strong>Static Variables</strong></summary>

Agent-level configuration values managed in **Designer > AI > Variables**. These act as defaults that initialize at the start of every conversation. Each conversation gets its own copy.

Use for: agent role definitions (`agentRole`), personality settings (`agentPersonality`), API tokens, or any value that should be consistent across all conversations.

{% hint style="info" %}
Mark a static variable as constant to prevent workflows from overwriting it at runtime.
{% endhint %}

</details>

<details>

<summary><strong>System Variables</strong></summary>

Built-in, read-only values provided by the platform. Available in every workflow without creating them. See the full list in the System Variables Reference section below.

</details>

### Referencing Variables

How you reference a variable depends on the node type. Look out for any place with the `{x}`  symbol. Click it to open a selection drop-down that includes all available variables.&#x20;

{% tabs %}
{% tab title="Message, Question, and LLM nodes " %}
Type `{{VariableName}}` in the text editor or use the autocomplete option after typing `{{` . Alternatively, click on the variable `{x}` button in the text editor toolbar to search all variables.
{% endtab %}

{% tab title="Flow Control nodes" %}
Select the variable from the drop-down. No manual syntax needed
{% endtab %}
{% endtabs %}

### The Variables Dashboard

Go to **Designer > AI > Variables** to manage static variables for your agent. This is where you define the default values that initialize at the start of every conversation.&#x20;

<details>

<summary><strong>Manage variables</strong></summary>

Edit or delete the variables using the action buttons. Click on any variable to open the edit menu.&#x20;

{% hint style="danger" %}
Deleting a variable is permanent. Verify that no active workflow depends on the variable before deleting.
{% endhint %}

</details>

<details>

<summary><strong>Default variables</strong></summary>

The dashboard comes pre-populated with a set of default variables that every new agent inherits automatically

</details>

<details>

<summary><strong>Variable description</strong></summary>

The description is optional and is used for documentation and collaboration purposes.

</details>

<details>

<summary><strong>Constant switch</strong></summary>

Enable the constant switch to lock a variable's value so workflows cannot overwrite it at runtime — useful for tokens, IDs, and other configuration that should stay fixed.

</details>

<details>

<summary><strong>Multiple languages</strong></summary>

Secondary languages inherit the static variables defined for the primary language. You can only create, edit, or delete static variables when the primary language is selected.

</details>

#### Creating a Static Variable

{% stepper %}
{% step %}

#### Open the Dashboard

Go to **Designer > AI > Variables** and click **Add Variable**.
{% endstep %}

{% step %}

#### Configure the Variable

Give a descriptive name for the variable and an initial value. The description explains what the variable is for and is visible to all team members. Change the variable to constant if you want to lock its value at runtime.
{% endstep %}

{% step %}

#### Submit

Click **Submit**. The variable appears in the table and is immediately available in your workflows.
{% endstep %}
{% endstepper %}

### Using the Variable Node

The Variable node lets you set or update a variable mid-workflow. The variable is created or updated the moment the node executes — any node that comes after it in the workflow can read the new value.

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Method</th><th>Description</th><th data-hidden data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-key">:key:</i></h4><h4>Name</h4></td><td>The key of the key-value pair. Select an existing variable from the dropdown or type a new name to create one on the fly. </td><td><a href="#the-variables-dashboard">#the-variables-dashboard</a></td></tr><tr><td><h4><i class="fa-brackets-curly">:brackets-curly:</i></h4><h4>Value</h4></td><td>The value to assign. This can be a static string, a number, or a reference to another variable using <code>{{variableName}}</code>.</td><td><a href="#using-the-variable-node">#using-the-variable-node</a></td></tr><tr><td><h4><i class="fa-subtitles">:subtitles:</i></h4><h4>Description</h4></td><td>Explains the variable's purpose (optional, but recommended for team visibility).</td><td><a href="#setting-variables-from-llm-nodes">#setting-variables-from-llm-nodes</a></td></tr><tr><td><h4><i class="fa-database">:database:</i></h4><h4>Storage Type</h4></td><td>Choose between session (scoped to the current conversation) or contact (persists across sessions). This determines the variable type.</td><td></td></tr></tbody></table>

### Setting Variables from LLM Nodes

LLM nodes can write directly to variables when you configure the response format as JSON. This turns the LLM into a decision-maker that extracts structured data from a conversation and stores it for downstream nodes to use.

To set this up:

1. In the LLM node configuration, set the response format to JSON![](https://604830754-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBM1xs3i59ajeTgi4uVfN%2Fuploads%2Fi2PocHkaCbQI43GUPPsX%2FScreenshot%202026-03-05%20at%201.37.52%E2%80%AFPM.png?alt=media\&token=f040bb14-a3d1-4b04-957b-057283df4de7)
2. Define the expected JSON structure in the LLM prompt — for example, instruct it to return `{"department": "billing", "urgency": "high"}`
3. Map each JSON property to a variable in the **Extract Parameter** section— `department` maps to `{{department}}`, `urgency` maps to `{{urgency}}`.

Once the LLM node executes, the mapped variables are available to every node that follows.&#x20;

{% hint style="info" %}
If you do not enable JSON response format, the LLM output is not automatically saved to any variable. JSON mode is required for the variable mapping to appear.
{% endhint %}

### System Variables Reference

The platform provides built-in system variables you can use in any workflow without creating them.&#x20;

| Variable                              | Description                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------- |
| `{{sessionId}}`                       | The session identifier                                                       |
| `{{userId}}`                          | The user identifier                                                          |
| `{{workspaceId}}`                     | The workspace identifier                                                     |
| `{{BotId}}`                           | The bot's identifier                                                         |
| `{{deploymentId}}`                    | The deployment identifier                                                    |
| `{{deploymentChannel}}`               | The deployment channel                                                       |
| `{{messageId}}`                       | The message identifier                                                       |
| `{{userTextMessage}}`                 | The user's latest text message                                               |
| `{{sessionHistory}}`                  | The session transcript                                                       |
| `{{Today}}`                           | Today's date                                                                 |
| `{{TodayDayOfTheWeek}}`               | Today's day of the week                                                      |
| `{{Now}}`                             | Current time                                                                 |
| `{{NowInMilliseconds}}`               | Unix timestamp in milliseconds since epoch                                   |
| `{{CurrentDate}}`                     | Current date in YYYY-MM-DD format (bot's time zone)                          |
| `{{CurrentDateLongForm}}`             | Current date in long format, e.g. Tuesday, August 06, 2024 (bot's time zone) |
| `{{CurrentDatetimeISO8601}}`          | Date and time in ISO 8601 format (bot's time zone)                           |
| `{{CurrentDatetimeISO8601_UTC}}`      | Date and time in ISO 8601 format (UTC)                                       |
| `{{CurrentYear}}`                     | Current year in YYYY format (bot's time zone)                                |
| `{{CurrentMonth}}`                    | Current month in MM format (bot's time zone)                                 |
| `{{CurrentDay}}`                      | Current day in DD format (bot's time zone)                                   |
| `{{CurrentHour}}`                     | Current hour in hh format (bot's time zone)                                  |
| `{{CurrentMinute}}`                   | Current minute in mm format (bot's time zone)                                |
| `{{CurrentTime12h}}`                  | Current time in 12h format (bot's time zone)                                 |
| `{{CurrentTime24h}}`                  | Current time in 24h format (bot's time zone)                                 |
| `{{Timezone}}`                        | The bot's time zone identifier                                               |
| `{{TimezoneOffset}}`                  | The UTC offset of the bot's time zone                                        |
| `{{missedQuestionsCount}}`            | Missed questions count in the current session                                |
| `{{consecutiveMissedQuestionsCount}}` | Consecutive missed questions in the current session                          |
| `{{WebchatFullUrl}}`                  | The webchat full URL                                                         |
| `{{WebchatOrigin}}`                   | The webchat origin URL                                                       |

### Contact Variables Reference

| Variable                  | Description       |
| ------------------------- | ----------------- |
| `{{UserInfo.email}}`      | User's email      |
| `{{UserInfo.firstName}}`  | User's first name |
| `{{UserInfo.lastName}}`   | User's last name  |
| `{{UserInfo.fullName}}`   | User's full name  |
| `{{UserInfo.language}}`   | User's language   |
| `{{UserInfo.salutation}}` | User's salutation |

### Best Practices

* Name variables descriptively: `agentRole` and `agentPersonality` are clear; `var1` and `temp` are not
* Mark configuration values as constant: tokens, IDs, and role definitions should not change at runtime
* Use session variables for temporary state: anything that only matters during a single conversation belongs in a session variable
* Use contact variables sparingly: only store data that genuinely needs to persist across sessions
* Add descriptions to every variable: the Variables dashboard is shared by your team — descriptions prevent confusion
* Keep system variables in mind: check the built-in list before creating a custom variable that duplicates existing data

{% hint style="success" %}
You now know how to create, store, reference, and manage variables across your agent's workflows.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helvia.ai/build/variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.