> For the complete documentation index, see [llms.txt](https://docs-conversational-ai.syntphony.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-conversational-ai.syntphony.com/studio/parameters-and-variables/variables-and-system-variables.md).

# Variables & System Variables

Store, update, and reuse conversation data, or access runtime information automatically provided by Syntphony Conversational AI.

## Overview

**Variables** and **System Variables** make it possible to work with **information that changes or becomes available while a conversation is running**.

Use **Variables** for information that your project needs to store and reuse during the conversation, such as user input, selected options, calculated values, or data returned during a flow. Use **System Variables** when you need information automatically provided by Syntphony Conversational AI, such as the current channel, language, session, or user identifiers.

***

## Understand the differences

<table><thead><tr><th width="157.30743408203125">Differences</th><th>Variable</th><th>System Variable</th></tr></thead><tbody><tr><td><strong>Created by</strong></td><td>User</td><td>Syntphony Conversational AI</td></tr><tr><td><strong>Value</strong></td><td>Can change during the conversation</td><td>Automatically provided at runtime</td></tr><tr><td><strong>Configuration</strong></td><td>Configurable</td><td>Read-only</td></tr><tr><td><strong>Use it when</strong></td><td>You need to store or reuse conversation data</td><td>You need information about the current interaction</td></tr></tbody></table>

***

## Variables

Variables are **project-level resources** used to store information that can change while a conversation is running. They make it possible to keep information available throughout the session and reuse it in supported fields and different parts of the flow.&#x20;

For example, you can use Variables to store a customer's name, keep a selected option, save a value generated during the flow, or pass information between cells.

### Creating a Variable

Go to **Parameters & Variables > Variable** and create a new Variable. Configure the following fields:

* **Name:** Identifies the Variable so it can be referenced throughout the project.
* **Description:** Describes what the Variable stores or how it should be used.
* **Context:** Defines the Context where the value is stored: **Hidden, Visible, or Open Context**.
* **Key:** Defines the key used to store and identify the Variable within the selected Context.
* **Type:** Defines the type of data stored by the Variable, such as **String, Number, Boolean, JSON, or Null**.
* **Default Value:** Defines the initial value of the Variable according to the selected type.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FP0NCCTDHf20VfDh8oaIc%2FCaptura%20de%20Tela%202026-10-19%20a%CC%80s%2017.29.28.png?alt=media&amp;token=e88f316e-9e4e-4297-adb9-ea86569187cc" alt="Project Variable Page"><figcaption><p>Project Variable Page</p></figcaption></figure>

#### Choose a context

The **Context** determines where the Variable is stored and how its information can be accessed during the conversation:

<table><thead><tr><th width="165.67938232421875">Context</th><th>Visibility</th><th>Use it for</th></tr></thead><tbody><tr><td><strong>Hidden Context</strong></td><td>Available to channels. Hidden from the end user.</td><td>Private or sensitive data.</td></tr><tr><td><strong>Visible Context</strong></td><td>Readable and editable by channels. Read-only for the end user.</td><td>Information that the end user may need to read.</td></tr><tr><td><strong>Open Context</strong></td><td>Readable and editable by the end user.</td><td>Data that the end user must read and update.</td></tr></tbody></table>

{% hint style="info" %}
**Important:** Do not store sensitive data in Open Context or Visible Context. Use **Hidden Context** for private information.
{% endhint %}

#### Choosing a Type and Default Value

The **Type** determines the kind of data the Variable can store. When applicable, you can also define a **Default Value**, which is used as the Variable's initial value.

<table><thead><tr><th width="180.04986572265625">Type</th><th>Example default value</th></tr></thead><tbody><tr><td><strong>String</strong></td><td><code>Hello</code></td></tr><tr><td><strong>Number</strong></td><td><code>42</code></td></tr><tr><td><strong>Boolean</strong></td><td><code>true</code></td></tr><tr><td><strong>JSON</strong></td><td><code>{"key": "value"}</code></td></tr><tr><td><strong>Null</strong></td><td>No default value</td></tr></tbody></table>

{% hint style="info" %}
**Note:** When **Null** is selected, the **Default Value** field is not displayed because the Variable starts without a defined value.
{% endhint %}

#### Variable example

For example, you can create a Variable to store the customer's name during the conversation and reuse it later in the flow.

> **Name:** \
> customer\_name
>
> **Description:**\
> Stores the customer's name during the conversation.
>
> **Context:** \
> Hidden Context
>
> **Key:** \
> customer\_name
>
> **Type:** \
> String
>
> **Default Value:** \
> Guest

Once the Variable is created, its value can be updated during the conversation and reused in supported fields.

For example:

> Hello, **$customer\_name**. How can I help you today?

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FcsqEbOf7lDpDyirf9b4M%2FCaptura%20de%20Tela%202026-10-19%20a%CC%80s%2017.39.45.png?alt=media&amp;token=e2a38d46-0c8d-4d13-ad34-19609d078f08" alt="Using a Variable in an Answer Cell content field"><figcaption><p>Using a Variable in an Answer Cell content field</p></figcaption></figure>

***

## Using Variables from the selector

In supported fields, the **Parameters & Variables selector** allows you to search for and insert an existing Variable without leaving your current configuration.

Select a Variable from the list to automatically add it to the field.

If the Variable you need does not exist yet, click **Add New** to create one directly from the selector. Once created, the new Variable is:

* stored in the project's **Variables** list;
* available for reuse in other supported fields throughout the project;
* automatically inserted into the field where it was created.

This allows you to **reuse existing Variables or create new ones directly where you need them**, while keeping all Variables centrally managed at project level.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2Fry1M9MKAK9Os6v0jwRXr%2FCaptura%20de%20Tela%202026-10-19%20a%CC%80s%2017.30.53.png?alt=media&amp;token=7507a4f4-8948-49ae-8472-6a6d2ee0d9b8" alt="Selecting or creating a Variable from the Parameters &#x26; Variables selector"><figcaption><p>Selecting or creating a Variable from the Parameters &#x26; Variables selector</p></figcaption></figure>

***

## Managing Variables

Variables can be **edited, disabled, or deleted** from the project's Variables list. Before making changes, consider where the Variable is being used, as the same Variable may be referenced in different supported fields.

#### **Edit a Variable**

Edit a Variable when you need to update its configuration. Changes apply to the Variable wherever it is referenced, so review its usage before changing configurations that may affect its behavior.

#### **Disable a Variable**

Disable a Variable when you want to temporarily prevent it from being used without deleting its configuration. The Variable remains available in the Variables list and its existing references remain visible, but **it is not resolved during execution**. Enable it again when you want to resume its use.

#### **Delete a Variable**

Delete a Variable when it is no longer needed. Deletion is permanent. If the Variable is still referenced in supported fields, review and update the affected configurations as needed. If necessary, recreate the Variable or replace its references with another one.

{% hint style="info" %}
**Tip:** Disable a Variable when you may need it again. Delete it only when you are sure it is no longer required.
{% endhint %}

***

## System Variables

System Variables are **predefined, read-only values automatically provided by Syntphony Conversational AI during execution**. Unlike Variables, you don't need to create or maintain them.

Use them whenever the flow needs information about the current conversation, project, channel, user, or session.

<figure><img src="https://4008706377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6zS4HeuuVpRHZEvDiFU%2Fuploads%2FdKjSi4VlMvBAvNalaJyo%2FCaptura%20de%20Tela%202026-10-19%20a%CC%80s%2017.29.45.png?alt=media&amp;token=4606dc2c-7c4c-451d-a450-60df12c055e5" alt="System Variables Page"><figcaption><p>System Variables Page</p></figcaption></figure>

<table data-search="false"><thead><tr><th width="193.24847412109375">Name</th><th width="269.2728271484375">Key</th><th>Use it to</th></tr></thead><tbody><tr><td>Text</td><td><code>$text</code></td><td>Stores the last text sent by the user.</td></tr><tr><td>SessionCode</td><td><code>$sessionCode</code></td><td>Contains the UUID/GUID of ongoing conversations. It's empty before user's first input.</td></tr><tr><td>Code</td><td><code>$code</code></td><td>Stores the code of the last message (unprocessed, raw input).</td></tr><tr><td>ProjectName</td><td><code>$ProjectName</code></td><td>Contains the project name.</td></tr><tr><td>ChannelName</td><td><code>$ChannelName</code></td><td>Contains the given name for the currently used channel.</td></tr><tr><td>ChannelType</td><td><code>$ChannelType</code></td><td>Contains the current channels type (whether its Web, Facebook, Alexa, etc).</td></tr><tr><td>ChannelClassification</td><td><code>$info.channelClassification</code></td><td>Contains the category of the existing channel in the channel library.</td></tr><tr><td>Locale</td><td><code>$info.locale</code></td><td>Contains the virtual agent's language and country. This must be the same as configured in the platform. Examples: en-US, es-ES or pt-BR.</td></tr><tr><td>UserRef</td><td><code>$info.userRef</code></td><td>Contains the user's identification through a technical value, depending on the channel. Some examples: for web chat (the user IP address), IVR (phone number), Messenger (Facebook's user ID).</td></tr><tr><td>BusinessKey</td><td><code>$info.businessKey</code></td><td>Contains the user's identification in a business level if the channel has information about the user. Examples: in a private section of a webpage that requires logging in, the business key might be the user login, user document number, client #.</td></tr><tr><td>OS</td><td><code>$info.operatingSystem</code></td><td>Information about the user's operating system. Example: for web chat, it might be Windows; and for a mobile app, iOS.</td></tr><tr><td>OSVersion</td><td><code>$info.operatingSystemVersion</code></td><td>Information about the version of the operating system.</td></tr><tr><td>Browser</td><td><code>$info.browser</code></td><td>Includes the user's current browser, if applicable.</td></tr><tr><td>BrowserVersion</td><td><code>$info.browserVersion</code></td><td>Contains user's current browser-version, when using one.</td></tr></tbody></table>

{% hint style="info" %}
**Note:** Unlike Variables, System Variables are managed by the platform and are always available when applicable. They **cannot be created, edited, disabled, or deleted**.
{% endhint %}

***

## Troubleshooting

<table data-search="false"><thead><tr><th>Issue</th><th>Possible cause</th><th>What to do</th></tr></thead><tbody><tr><td>A value should be shared across projects.</td><td>Project Variables belong to the project.</td><td>Use Environment Parameters when the value is static and shared.</td></tr><tr><td>A Variable does not resolve in a field</td><td>The field may not support Variables, the reference may be incorrect, or the Variable may be disabled.</td><td>Check whether the field supports Dynamic Content, verify the reference, and make sure the Variable is enabled.</td></tr><tr><td>A Rule condition does not work as expected</td><td>The Variable may be referenced using Dynamic Content syntax.</td><td>In Code and Rule cells, use the native Context syntax without the <code>$</code> prefix, for example: <code>openContext.quantity > 5</code>.</td></tr><tr><td>A Variable value is not available as expected</td><td>The Variable may be stored in a different Context or its Key may not match the reference.</td><td>Check the Variable's <strong>Context</strong> and <strong>Key</strong> and update the reference accordingly.</td></tr><tr><td>A Variable reference remains visible but does not resolve</td><td>The Variable has been disabled.</td><td>Enable the Variable or replace it with an active one.</td></tr><tr><td>A Variable reference is no longer valid</td><td>The Variable has been deleted.</td><td>Recreate the Variable or update the affected fields with another Variable.</td></tr><tr><td>Information is accessible where it should not be</td><td>The Variable may be stored in Open or Visible Context.</td><td>Review its Context and use <strong>Hidden Context</strong> for private or sensitive information.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs-conversational-ai.syntphony.com/studio/parameters-and-variables/variables-and-system-variables.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
