🧩 Variables
Variables play a central role in shaping the flow of a conversation with your virtual assistant.
They allow your assistant to store information and make decisions based on that data, enabling a dynamic, personalized experience for users. In the context of workflow configuration, variables are especially useful for controlling logic and triggering specific actions based on user inputs or external data.
What is a Variable?
A variable is essentially a container that holds a value. It is defined by:
A Name: Used to access the value stored in the variable.
A Type: Restricts and validates the type of value that can be assigned to the variable.
How Are Variables Used?
Variables are essential for interactive, advanced conversational flows.
They can be populated in different ways:
External Data via APIs: Variables can be filled with data retrieved from external systems through API calls.
User Input: Information extracted from user messages can be used to populate variables.
Capture Block: Values are extracted from user messages and stored within a variable.
Prompt Block: JSON data returned by a Prompt Block fills the variable with the required values.
Manual Configuration: You can set the value of a variable manually during the workflow configuration process.
Set Values Block: The value of a variable can be manually set during the workflow configuration.
Fallback Value: A default value can be assigned to a variable during its creation or modification (as explained below), ensuring the variable has an initial value if no other value is provided.
Once a variable is populated, it influences the conversation by helping determine the next step in the workflow or the response provided to the user.
Variable Categories
There are three main categories of variables:
System Variables: These are automatically created and managed by the platform. Examples include context variables (e.g., the last message exchanged), time-based variables (such as date and time), or system-related variables like those identifying whether the conversation is occurring in a live or test environment, or the URL where the web chat is installed. System variables cannot be modified through blocks such as Set Values or Capture.
Custom Variables: You can create your own custom variables tailored to your specific needs.
Secrets: Secrets are a special type of variable designed to securely store sensitive information like API tokens, authentication keys, or credentials. They’re encrypted, hidden from the interface, and only accessible during API calls—ensuring secure handling of confidential data.
Managing Variables
Variables are managed centrally through the link in the bottom left menu of your workspace. From there, you can view all available variables (including system variables) and create or modify them as needed.
Creating a Custom Variable
To create a new variable, go to Variables & Entities in the left sidebar, and click Create New.
A variable requires two things:
Name: A unique identifier for the variable. Il nome deve essere univoco (non possiamo creare due variabili con lo stesso nome) ma non ha particolari vincoli.
Type: Defines what kind of value the variable can hold. The platform supports the following types:
Text: Any kind of content.
Number: Whole or decimal numbers.
Boolean: A binary value (true/false).
Date/Time: A date and time value.
Agent/Workflow: A reference to an agent or workflow.
🆕 Map: A JSON object (key-value pairs), ideal for structured data.
🆕 List: A collection of values (strings, numbers, or even maps).
In the Values section, there are two optional fields:
Test Value: A value associated with the variable during API block testing.
Fallback Value: The initial value assigned to the variable. If not assigned, the variable defaults to
null.
Deep Dive: Map & List Variables
To support advanced workflows, especially those involving External Triggers and structured data exchanges, we introduced two powerful new variable types in June 2025: Map and List.
These variable types allow your virtual assistant to handle complex, structured payloads with greater flexibility and precision. They're particularly valuable when working with JSON inputs from APIs, Zapier automations, CRM records, ERP systems, or any external tool integrated via our Platform API.
🗺️ Map Variables
A Map variable stores key-value pairs in JSON format. Think of it as a mini-database your assistant can use to retrieve structured information. For example:
{
"name": "John Doe",
"email": "[email protected]",
"status": "active"
}Creating a Map Variable
You can create a Map variable like any other variable using the JSON editor to define fallback and test values.
Writing to a Map
Map variables must be updated by overwriting the entire map; individual fields cannot be modified directly. You can populate a Map variable through:
The variable creation modal
A Set Value block
An API block (via capture variable)
You cannot assign values to a Map variable directly from a Capture block.
Example update:
mappa1 = {
"key1": "value1",
"key2": "value2"
}Reading from a Map
Use dot notation to retrieve values:
{{mappa.key1}}→ returns "value1"Nested access is supported:
{{mappa.nested1.nested2}}
Using Map Variables in Condition Blocks
Map variables support the following conditions:
IS / IS NOT: Checks if two maps are (or aren’t) identical. Key order does not matter
IS NULL / IS NOT NULL: True if the variable is null (not just empty
{})CONTAINS / DOES NOT CONTAIN: Checks whether a key exists in the map
Example:
mappa1 CONTAINS key1→true
When using a Map in a Condition block, you must refer to the entire map; you cannot condition directly on an internal value.
📋 List Variables
A List variable holds an array of elements — such as strings, numbers, or even maps. For example:
["item1", 42, {"field": "value"}]Writing to a List
Lists are created and updated using the same JSON editor as maps. Like maps, the entire list must be updated; individual elements can’t be edited directly.
Reading from a List
Use index notation to retrieve values:
lista[0]→"item1"lista[1]→42lista[2]→{ "field": "value" }lista[2].field→"value"
Using List Variables in Condition Blocks
Supported operations include:
IS / IS NOT: Checks if two lists are (or aren’t) identical — order matters!
IS NULL / IS NOT NULL: Returns true if the list is null (not just empty
[])CONTAINS / DOES NOT CONTAIN: Checks if a value exists within the list
Example:
lista CONTAINS "item1"→true
Best Practices
Set Variables at the Start of the Conversation
It’s a best practice to initialize all variables (usually to null) at the beginning of the conversation, in the Welcome workflow. This ensures that the virtual assistant doesn't retain values from a previous user interaction.
Passing User Information or Other Data to Your Web Chat
At the beginning of the conversation, you may want to populate variables with data from external systems, such as your CRM.
A common use case is passing user-related information, like login status or identifying details.
This can be achieved by including parameters in the web chat script's URL. Doing so allows you to preset responses or personalize the chat based on user data, such as their ID or preferred contact methods. This approach enhances personalized interactions from the very start of the conversation.
Last updated
Was this helpful?