Overview

Variables let your agent remember and reuse information during a conversation - things like a user’s name, account details, or selections they’ve made. They act as your agent’s short-term memory, letting it personalize responses, make decisions, and pass data between steps.

Variables table with names, descriptions, and values
Review the variables available to the project.

Variables are scoped to individual users via user_id. If ten users are talking to your agent simultaneously, their variable values are completely independent.

Stored values and model context

A variable is a named value you explicitly capture or assign and reference elsewhere.

A variable is a named value you explicitly capture or assign and reference elsewhere. Model context is the information available to the model for a particular response, including the instructions that apply at that point. These are related, but they are not interchangeable.

For example, a playbook can collect an order ID into a required exit variable. After it returns through a Playbook step, the workflow can reference that variable in an API request. The API response can be captured into another variable for a later condition or message.

One value carries information through the process
PlaybookCollect the order ID
Save
order_idStored variable
Reference
WorkflowPrepare the lookup
Send the ID
Order APIFind the order
The same stored order ID connects the conversation to the lookup. Each step uses an explicit assignment or reference; instruction scope is separate from variable storage.

Values are scoped to the user identified by user_id. The Persist across sessions setting determines whether a value survives a new session for that user; it does not make a value shared with other users. See persistence settings.

Storing a value also does not make every earlier instruction available to a playbook. Instruction scope determines where that guidance belongs.

Creating variables

You can create a variable from anywhere your can insert them - type { in most text inputs across Voiceflow to see your existing variables or create a new one inline.

You can create a variable from anywhere your can insert them - type { in most text inputs across Voiceflow to see your existing variables or create a new one inline.

Create variable dialog with name, color, and default value
Name the variable and set its default value before creating it.

You can also manage variables from the Variables tab in the sidebar. Click New variable in the top right to create one, or click an existing variable to edit it. When creating a variable, you can optionally set a default value - this gives your agent a fallback if the variable hasn’t been set yet during a conversation. By default, variables are initialized automatically and set to 0.

Variables table with default values and search
Find a variable and review its default value.

Using variables

Reference a variable by typing { and selecting it from the searchable menu.

Reference a variable by typing { and selecting it from the searchable menu. Variables work inside playbook instructions, API tool URLs and headers, condition steps, response messages, and more. If you’re in a place where you need to use a variable, type { and it the menu will pop up.

Inside agent and playbook instructions, typing / inserts a reference to a tool, playbook, or workflow the same way.

Variable picker inside playbook instructions
Insert variables to use conversation data in your instructions.

Setting variable values

Assign values with Set and Code steps, tool responses or Playbook exit conditions.

Persisting variables across sessions

When you create or edit a variable, you can choose whether its value persists across sessions for the same user.

When you create or edit a variable, you can choose whether its value persists across sessions for the same user. This lets you decide, per variable, whether your agent remembers a value when someone returns and starts a new session with the same user_id, or starts fresh each time.

To set this, open the Variables tab in the sidebar, create or select a variable, and switch Persist across sessions on or off.

  • On: the variable keeps its value when the same user starts a new session, so your agent can pick up where it left off (eg: greeting a returning customer by name or remembering their plan tier).
  • Off: the variable resets to its default value at the start of each new session, so it only lasts for the duration of a single session.

Turn this off for values that should only apply to the current session, such as a one-time verification code, a temporary selection, or the user’s progress through a flow. Keep it on for long-lived details you want your agent to remember across visits, like a user’s name or their preferences.

Built-in variables

Every project has access to built-in variables that are automatically set when a conversation begins or when certain events occur.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.