> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables: put call data into prompts, messages and tools

> The kinds of variables an agent can use, where each value comes from, which wins when two share a name, and where you can write them.

Variables let one agent say and do the right thing for each caller. You write `{{customer_name}}` in a prompt, a message or a tool setting, and on the call the agent fills in the value. This page explains the kinds of variables, where each value comes from, and where you can use them.

## Kinds of variables

Every variable is written the same way, `{{name}}`, and they all share one set of names. As the app puts it, what separates them is where the value comes from.

| Kind | Where the value comes from | Agent types | Learn more |
| - | - | - | - |
| **System** | Provided automatically on every call: the date and time, the caller's number, the call direction | Flow and single prompt | [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md) |
| **Dynamic** | You send it when the call starts: from the API, the web SDK, a batch call file or a test call. Each one has a default value. | Flow and single prompt | [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md) |
| **Environment** | You set a value per environment (dev, staging, prod) on the agent | Flow and single prompt | [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md) |
| **Extracted** | The agent collects it during the call: from what the caller says, from a tool's response, or from keys the caller presses | Flow | [Extract values from the conversation](https://docs.tryhamsa.com/agents/variables/extracted-variables.md) |
| **Live** | The agent keeps it up to date from what the caller says, after every caller turn, in every step | Flow | [Live variables](https://docs.tryhamsa.com/agents/variables/live-variables.md) |
| **Local** | A step sets it to a value you choose when the call reaches that step | Flow | [Static and local variables](https://docs.tryhamsa.com/agents/variables/local-variables.md) |
| **Secrets** | Project credentials, written `{{secrets.NAME}}`, for tool settings only | Flow and single prompt | [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md) |

## See all variables

> [tab] Flow agent
>
> **1. Open the Variables dialog**
>
> In the flow builder, click **Variables** on the toolbar at the left edge of the canvas. You can also press Cmd+K (Mac) or Ctrl+K (Windows) and choose **Variables**.
>
> **2. Find a variable**
>
> Type in **Search variables...**, or jump to a section: **System**, **Extracted**, **Environment** or **Dynamic**.
>
> **3. Change dynamic or environment variables**
>
> Click **Manage** next to **Dynamic variables** or **Environment variables**. Use the back arrow to return to the list.

> [tab] Single prompt agent
>
> **1. Open the Variables section**
>
> In the agent's configuration, open **Variables** ("Manage system and dynamic variables for dynamic content."). It shows the system, dynamic and environment variables available to the agent.
>
> ![A single prompt agent's Variables section, listing system, dynamic and environment variables](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/single-prompt-variables-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=2719e91842e2e799725d2224ff3f3805)
>
> **2. Open the full list**
>
> Click **Manage variables**. The same **Variables** dialog opens, without the **Extracted** section.

![The Variables dialog in a flow agent, with the jump bar System, Extracted, Environment and Dynamic, showing extracted and environment variables](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/variables-dialog-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=7abae1251c7f4ef70c95ff874f5bf642)

## Insert a variable

In any text field that takes variables, type `{{` or click the variable button (**Insert variable**). A picker opens with the variables available at that point in the flow. Use the arrow keys to move, Enter or Tab to insert, and Esc to close.

You can also type the variable yourself: `{{customer_name}}` and `{{ customer_name }}` both work.

For conditions, loops and filters, use Jinja. See [Jinja syntax for prompts and messages](https://docs.tryhamsa.com/agents/variables/jinja.md).

## Where you can use variables

The agent fills in variables wherever it reads text from your agent, including:

* the prompt (single prompt agents) and the global prompt and step prompts (flow agents)
* the greeting, step messages, and processing, confirmation and final messages
* an API tool's URL, headers, auth token and parameters
* transition descriptions and condition values
* transfer phone numbers

## Which value wins when names clash

The app stops you from giving a dynamic variable, an extracted variable or a local variable the same name as an environment key. When a value still reaches the call under a name that's already taken, the call uses this order, highest first:

1. **Environment** values
2. **Local** variables with **Keep in sync** on
3. Values sent at call start, extracted values and other local variables (the most recent one written wins)
4. **System** variables

So a value sent at call start never replaces an environment value of the same name. See [Environment variables](https://docs.tryhamsa.com/agents/variables/environment-variables.md).

## Good to know

* **Every value is text.** On the call, numbers and true or false arrive as strings. Compare with `| int` or `== "True"`. See [Jinja](https://docs.tryhamsa.com/agents/variables/jinja.md#every-value-is-a-string).
* **A variable with no value renders empty.** The call goes on; nothing in braces is ever spoken.
* **Names are snake\_case.** Dynamic, extracted and local variable names use lowercase letters, numbers and underscores and start with a letter, up to 50 characters. Environment keys use capital letters, like `API_HOST`.
* **Variables carry over on a handoff.** A [Transfer to agent](https://docs.tryhamsa.com/agents/flow/steps/transfer-agent.md) step passes the current variables to the receiving agent unless you turn off **Handoff variables**. Environment values don't carry over: the receiving agent uses its own.
* **Deleting a variable that's in use** asks first, for every kind of variable in a flow: dynamic, local, live, and a step's own variables. The dialog says "\{name} is used in N steps:" and links each step; click one to go to it. Click **Delete anyway** to remove the variable; those steps then show the name as not defined until you add it back or change them.

## Related

> [card] [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md)
>
> Every variable the platform fills in, with its exact format.

> [card] [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md)
>
> Send customer data from the API, the web SDK or a batch call file.

> [card] [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md)
>
> Conditions, loops and filters that work on calls.

> [card] [Test values](https://docs.tryhamsa.com/agents/variables/test-values.md)
>
> Try your own values in test calls, and fix variables that aren't defined.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.