Variables

Botpress uses variables to store information from one place and use it in other parts of a flow. Variables help make conversations more personalized and help track information about users. They can also help connect with third-party APIs and data sources.

Variable Scopes

Botpress also includes different types of variables. These Variable types differ in scope or where they can be accessed in your bot's flows.

Creating Variables in Botpress

1. Open up the Variables tab from the sidebar and click the + icon in the Variables section.
2. A new window will appear, allowing you to formulate a new Variable.
3. Assign a suitable scope (Workflow, Bot or User) to your Variable, select the Data Type (see below table), give it a name, and click Add to create the Variable.
4. (Optional) From the Additional Settings, you can also initialize your Variable with a default value.

Using Variables in Botpress

Once the Variable is established, employ {{workflow.variablename}} or @workflow.variablename to render it in a send message card.

Data Types for Variables

Botpress variables are typed, meaning they are limited in what data they can hold. Not only are these data types important to ensure the code behind Botpress runs smoothly, but these types also help AI tasks generate better results. Here are the different data types available for Botpress variables:

Workflow Variables

Workflow Variables are created and used only within a single workflow. These variables are great for single-use or in standalone flows, such as:

1. Storing an AI Task's output
2. Saving the user's answer to a question
3. Organizing data returned from an API call
4. Saving flags or tags that track the conversation

📘

Info

Workflow variables are not accessible in any workflow other than the one they were created in. For example, a workflow Variable created in a separate workflow will not be accessible in Main.

Creating a Workflow Variable

To create a Variable in your bot's workflow, you can follow these steps:

1. Select the appropriate workflow from the Flows section in the Side Panel.
2. Click on the + icon in the Variables section, at the bottom of the Side Panel.
3. Give your Variable a name, pick a type and click Add to create the Variable. (Default scope is Workflow)
4. Once the Variable is created, you can use {{workflow.variablename}} or @workflow.variablename to display it in a send message card.

Input and Output Workflow Variables

Workflows can have inputs and outputs to help pass information throughout the bot. This can be useful if your workflow returns information like a verified phone number, or requires information like a user id.

To mark an Input Variable

1. Go into your new workflow(not Main) and create a Variable and Click it's Entry node.
2. In the inspector panel, click on the Variable you want to make an input. It should get a blue border and appear in the Entry node.
3. When you call this workflow from another flow, there should be an input box for that Variable in the workflow's card. This will let you pass information or another Variable into that workflow.

To mark an Output Variable

1. Go into your new workflow(not Main) and create a Variable and click on the Exit node.
2. In the inspector panel, click on the Variable you want to make an output. It should get a blue border and appear in the Exit node.
3. When you call this workflow from another flow, the output Variable will be accessible by typing {{workflow.<workflow-cardName>.<variablename>}}, replacing <workflow-cardName> and <variablename> with the name of the card that represents your workflow and Variable respectively.

User Variables

User Variables are variables that follow a user between conversations. For example, if a user speaks with your bot on Monday and Wednesday, any user variables set on Monday will still be accessible on Wednesday. User variables are great for storing data that doesn't change very often, such as:
Storing users' personal details or id numbers

1. Collecting tags or notes from past conversations
2. Storing extra flags like VIP customer
3. Saving language preferences

Creating a User Variable

1. Open up the Variables tab and navigate to the + icon in the Variables section.
2. Change the scope to User, select the Data Type, give it a name, and click Add to create the Variable.

Using User Variables

Once the User Variable is established, employ {{user.variablename}} or @user.variablename to render it in a send message card.

Bot Variables

Bot Variables can be accessed by all users of the chatbot across all conversations. They are typically used for configuration and developer information, such as:

1. Storing the endpoint for the bot's API calls
2. Saving bot's version number
3. Storing the bot's name
4. Metadata about the bot/services

Bot variables are not encrypted or stored securely. Do not save secrets like API keys or passwords in bot variables - use configuration variables instead!

Creating a Bot Variable

1. Open up the Variables tab and navigate to the + icon in the Variables section.
2. Change the scope to Bot, select the Data Type, give it a name, and click Add to create the Variable.

Using Bot Variables

Bot variables can be used in text and other cards just like user variables - with either @bot.variablename or {{bot.variablename}}.

Session Variables

Session variables are available in all flows, but only for one conversation. These variables are great for data used throughout a conversation, such as:

1. Collecting items in a virtual shopping cart for the user to order
2. Saving raw data from an API call for further processing
3. Storing chat history for that conversation
4. Saving an order number or policy number

Creating a Session Variable

Session variables can only be created inside of an Execute Code card.

To create one, simply write: event.state.session.variablename = "Hello World" or for short session.variablename = "Hello World"

To use a Session Variable in a text or other card, enclose it in double curly brackets like {{event.state.session.variablename}} or for short {{session.variablename}}

Configuration Variables

Configuration variables are a special kind of secure bot Variable. They can also be managed from the Cloud Dashboard without opening the bot. Configuration variables can store secrets like:

• API Tokens
• Private IP Addresses
• Database usernames and passwords

Creating a Configuration Variable (or Environment Variable)

1. Click the Botpress icon in the upper-left corner and select Chatbot Settings
2. Scroll down and click on the button to add a Configuration Variable. Fill in the Variable's name and value and click Done.

You can use env.key in your code to get the value of the Configuration Variable. To use it in an Execute Code Card, you can write env.key to access its value.
Once a configuration Variable is created, you can access and manage it from the cloud admin dashboard. Just select your bot and then click on the tab for Configuration Variables.

Passing Variables between Flows

1. In your target workflow, define an input Variable from the workflow properties window.
2. Toggle it ON on the Entry node of the target workflow.
3. Now, on the exit node of the parent workflow, the one that brings the user to the target workflow, match the parent workflow Variable with the target workflow input Variable.
4. Now, when you call the target workflow from the parent workflow, you will see the input Variable in the card. You can pass a value or a Variable to it.

Using Variables in Code Card

Variables in code follow the pattern variabletype.variablename. Here's a breakdown and examples of how to use these:

1. Assigning a Value to a Variable

This is typically how you'd initialize a variable or change its value.

workflow.orderNumber = 12345
session.cartTotal = 59.99
user.lastName = 'Smith'
bot.version = '1.2.3'
env.databaseURL = 'https://example.com/db'

2. Using Variables in Conditional Statements

This checks the value of a variable and executes code accordingly.

if (user.firstName === 'John') {
  console.log('Hello John!')
} else {
  console.log('Welcome, user!')
}

3. Using Variables in Functions

Here, you might pass a variable as a function argument or use it inside a function.

function greetUser(firstName) {
  console.log('Hello, ' + firstName + '!')
}

greetUser(user.firstName)

4. Combining Variables

You might want to combine or concatenate variables.

var fullName = user.firstName + ' ' + user.lastName

//or

var welcomeMessage = 'Hello, ' + user.firstName + ' ' + user.lastName + '!'

5. Checking Variable Type

Botpress might throw an error if types don't match, you can use type checking before assigning values.

if (typeof workflow.userAcctId === 'number') {
  workflow.userAcctId = 67890 // This is okay.
} else {
  console.error('Invalid type for userAcctId!')
}

6. Using Variables with External APIs

If your bot interacts with external services, you might use an environment variable like env.apiKey.

const apiKey = env.API_KEY
const apiUrl = env.API_URL

const config = {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
}

const response = await axios.get(apiUrl, config)
const data = response.data

// Process the data as needed
// ...

// Example: Log the response data
console.log(data)

Special Variables

Botpress makes available several different variables that can be used in your bot's code. These variables are useful for debugging and for accessing information about the user and conversation.