Variables

How to use variables

Let's explore what variables are and how to use them effectively when building chatbots in MaviBot.

Please be aware of the following system limits for variables and constants within a single project:

Template Variables:

Maximum quantity: 100 variables
Maximum name length: 100 characters

Project constants:

Maximum quantity: 50 constants
Maximum name length: 100 characters
Maximum value length: 5,000 characters

A variable is a named storage location for data, identified by a unique text label.

Fig. 1: A variable named total, storing a payment amount.

MaviBot provides several types of variables:

Built-in variables
System variables
User-defined variables — these are the ones you create yourself within the project.

To declare a variable means to assign a value to a named container. In other words, a statement like a=0 is the declaration of the variable a. We’ve just told (declared to) the builder that we’ll store a number in the variable a, and for now, that value is 0.

To assign a value to a variable carries the same meaning.

The expressions "assign a variable the value of a function" or "set a variable equal to a function" are also commonly used. The principle is the same: instead of assigning a specific value, you assign the result of a function. For example: s_id = tg_send_message(platform_id, "Hello!") In this case, the result of the function will be stored in the variable.

To reset a variable means to assign it the value 0.

Functions and methods are predefined sets of commands that are configured in advance by MaviBot. Most functions require parameters - values that the function or method can understand. Once the bot receives the necessary parameters, it executes a specific command.

tg_send_message(platform_id, "Hello!") — this function sends the message "Hello!" in Telegram.

Fig. 2. Example of a variable named text1 assigned to a function.

RULES FOR WORKING WITH VARIABLES:

A variable name can only start with a letter; it cannot begin with a number.
Age1 - ✅ correct
1Age - ❌ incorrect
age1 - ✅ correct - recommended option
A variable cannot contain spaces or special characters, except for the underscore (_).
Name_Surname - ✅ correct
Name Surname - ❌ incorrect
nameSurname - ✅ correct - recommended option
Reserved words from programming languages cannot be used as variable names, for example: print, true, false, count, sum, and so on.
It is strictly prohibited to use the names of built-in and system variables for user-defined variables. You can find the list of such variables here. ссылка
We recommend:
- Use Latin (English) names for variables.
- Use short but meaningful variable names, for example: totalSum, pay_name, ns, name_client, etc.

How to get the value of a variable

Place the variable name inside curly braces #{}. You can reference its value in the message text field this way. However, in the "Calculator" field, you should refer to the variable’s value simply by its name, without any additional syntax.

The #{} construction allows you to retrieve the value of a variable. It is used in the "Message text" field to insert the variable's value into the text.

Example:

The system supports nested variables, where the value of one variable is part of the name of another variable. For example: #{q#{test#{i}}}

In the "Calculator" field, refer to variables by their names without using the #{} notation. For example, if we have two variables: price (sum) and quantity (num).

num = 10

sum = 1500

How to display the total sum

Enter the following in the calculator:

total_sum = sum1 * num2 ✅ correct

How not to do it:

total_sum = #{sum1} * #{num2} - ❌ incorrect

How to delete a variable from the bot

To delete (clear) a variable, enter one of the following in the "Calculator" field: YourVariableName = or YourVariableName = ""

After the equals sign, either leave a space or use double (or single) quotation marks.

Please note! It’s important to use the correct prefix to indicate where the variable belongs.

For project-level variables (stored in the project settings), use the prefix project: Example: project.YourVariableName = or project.YourVariableName = ""

For client-level variables, use the prefix client: Example: client.YourVariableName = or client.YourVariableName = ""

For deal-level variables, no prefix is needed.

Built-in variables

Here is the list of built-in variables:

#{none} - ignore the message

#{api_key} - API token used in Salebot API calls

#{attachment_url} - contains the link to the attachment

#{attachments} - a JSON array of attachment URLs from the user's message

#{avatar} - link to the user's avatar (shown in the "Clients" section)

#{client_id} - client ID in the constructor, also used in API requests

#{client_type} - the type of messenger the client came from (values described [here])

#{current_date} - current date in dd.mm.yyyy format, based on the project's time zone

#{current_time} - current time in hh:mm format, based on the project's time zone

#{custom_answer} - the response received from the server specified in the "Server response URL" field

#{message_from_outside} - type of incoming message. Possible values: regular message = 0 message sent via API = 1 callback notification (yellow background in the dialog) = 3 telephony notification (light blue background in the dialog) = 5 This variable is generated with every incoming message but does not appear in the client card. You can use it in the "Variable for comparison" field to set up conditions for block triggers and connections.

#{date_of_creation} - date when user was added to the bot or messaged it for the first time

#{full_name} - full name of the user (first and last name)

#{group} - bot the client is linked to (shown as "Linked to bot" in client card)

#{main_client_id} - ID of the main client among a group of linked client cards

#{message_id} - current conversation state ID with the client (defaults to NONE)

#{messenger} - name of the messenger the client came from

#{name} - first name of the user

#{next_day} - tomorrow’s date in dd.mm.yyyy format (useful for scheduling messages)

#{order_id} - order identifier (client ID and internal order ID separated by a hyphen)

#{order} - contents of the order submitted by the user

#{platform_id} - client ID in the messaging platform

#{question} - message sent by the user

#{timestamp} - current timestamp including milliseconds

#{time_of_creation} - time when the user was added to the bot or messaged it for the first time

#{wa_bot} - WhatsApp number the user messaged (useful for passing to CRM fields and distributing leads among managers)

#{weekday} - day of the week as a number (Monday = 1, Tuesday = 2, etc.)

client_type values

Value

Messenger

for Telegram

for Viber

for Facebook

for online chat

for Instagram

e-mail

Telegram Business Account

Telegram account

TikTok

System variables

The system automatically generates various runtime variables during a bot's operation You can use these variables while building your bot. Here is a list of those that might be useful to you.

You can find additional system variables in the documentation. They are located within the sections relevant to their use.

phone - phone number

notSubscribed - if the variable equals 1, the client has unsubscribed from messages and will not receive any messages

clientBlocked - client is blocked, and the bot does not operate for them

story_url - identifier of the Instagram story the client replied to

viewed_page - page from which the user is writing in the online chat

wa_bot - phone number of the WhatsApp bot

To learn which variables can be created during payment, refer to the integration guides for payment services in the "Payment system" section.

Custom variables

Custom variables are divided into:

Project variables (also called common variables)
Client variables
Deal variables (also called regular variables)
Constants

Each type of variable will be explained below.

Please avoid using the same names for different types of variables to prevent confusion when the Builder displays or uses a value other than what you expected.

When assigning a value to a variable, it is important to specify its type by using the appropriate prefix:

client. (for client variables) and project. (for project variables). No prefix is used for deal variables.

The prefix is omitted when retrieving a variable’s value.

Example: Let's imagine you want to create a project variable called like to serve as a counter for likes from your clients.

project.like = 0 - declaration, done once

In the block where you need to count likes, write: project.like = like + 1

Variable priority order: deal variables have the highest priority, followed by client variables, then project variables.

Messenger ID (platform_id)

Messenger ID (platform_id) is the identifier of the user/chat/channel within the messenger. To find it, open the conversation with the desired client in the "Clients" section. On the right side of the chat window, navigate to the "About client - System variables" tab or the "All" tab.

The platform_id is a permanent, system-generated variable representing the user's unique messenger ID.

Persistence: This ID remains constant for a user. Even if you delete their record from the builder, their platform_id will be the same upon re-registration.
Origin: The ID is assigned by the messenger platform (e.g., Telegram, WhatsApp) when the user first interacts with the bot.

The following example shows how the platform_id appears in a client card.

The platform_id variable exists for regular users as well as for communities, channels, and chats.

To obtain the platform_id (messenger ID) of a Telegram channel where the bot is an administrator, simply send a message to the channel from your personal account. This will automatically create a dialog between the bot and the channel.

You can copy the channel’s platform_id value in the "About client" section.

In Telegram, the messenger ID for channels always starts with a minus sign (-). When using functions, make sure to include the entire value, including the minus sign.

How to use variables

Variables can be used in triggers, orders, user responses, blocks, and more. Let’s look at a concrete example while creating a funnel for a real estate agency.

So, let’s create a Start block:

Step 1: Create the "Thank you" block

Create a new block with a message thanking the user for their input.

Step 2: Configure the transition

On the connection leading to this block, configure the following trigger:

Enable the "User inputs data" toggle.
In the "Input data" field, enter the variable name: name.

The user's input is stored in the Name variable. This value can be reused in any subsequent block by invoking the variable with the #{Name} syntax, such as: Welcome, #{Name}!.

The bot will work as follows:

Now let’s make the task a bit more complex.

In this same block, we’ll ask the user whether he's interested in primary (new) or secondary (resale) housing:

Next, create connections from the "Primary housing" and "Secondary housing" buttons in the "Chat" block.

Now let’s look at the second way to use variables within blocks.

Select the right block and enter the following text in the "Calculator" field: client_interest = Primary housing. In the left block, enter: client_interest = Secondary housing.

A variable is assigned to the user when they transition to any of these blocks. We can use it later when creating an order.

Next, we’ll ask the client about their budget for purchasing real estate in these blocks, and create two more blocks with arrows leading to them based on the client’s response triggers.

From the block "What is your budget?", create a connection and set a trigger condition to segment users based on their input.

In the connection's settings, enable the checkbox for "User enters data".
Assign a variable name (e.g., budget) to store the client's response.
In the "Variable" field, use the built-in variable #{question} (which contains the user's last message) to create a condition.
- Example: #{question} <= 1000000

For all connections to "Leads" blocks, activate "User enters data" and define the variable.

You can also define an additional variable directly in the "Leads" block to provide more comprehensive deal information.

Now change the type of the last two blocks to "Leads" and see the results:

Let’s test the flow in action:

You can review the created deal and the client's stored data by going to the "Clients" section and opening the relevant conversation. The deal variables will be visible there.

Now you know how to use variables in at least three different ways:

Assign variable names to user input data (e.g., “Name”, “Budget”)
Assign a variable value when transitioning to a block (e.g., client_interest = Primary housing)

How to view variables

To view a client's variables, navigate to the "Clients" section and open their client card.

Variables are displayed in a list format within the client card:

Each variable occupies its own line.
The variable name is shown on the left.
Its corresponding value is displayed on the right.

To modify a variable:

Hover over its line in the list to reveal an action button. Clicking this button allows you to:

Edit the variable's name.
Edit the variable's value.
Delete the variable entirely.

System variables cannot be edited!

How to set client variables

Client variables are not deleted, reset, or lost when using the "End of data collection" block (red block).

A client variable can be set in two ways: explicitly and implicitly. An explicit way to define a variable is to set it in the "Calculator" field of one of the funnel blocks.

Example: client.age = 28 or client.age = 28:

The implicit way is to set a variable in the data input field of the arrow.

Example:

Let’s create a block where we ask for the client’s name, and also create a block below:

Next, navigate to the connection settings and enable the "User enters data" option.

Use the client. prefix when naming your variable (e.g., client.name) to store the user's input. This variable can then be referenced in later messages as #{client.name}.

Client variables are used exactly like regular variables in the builder, but without the client prefix.

How to set project variables

Global variables are not deleted, reset, or lost when using the "Leads" block (red block).

Global variables are accessible to all users of the bot. They are ideal for controlling bot behavior or facilitating interactions between different users.

Use case example: One user can post an item in a marketplace channel by setting a variable (e.g., project.latest_listing), and all other users can see it and respond.

Syntax for assignment

To create or update a global variable, use the project. prefix in the Calculator:

Examples:

project.product_shop = 28
project.age = 28

They can be used without any prefix.

Let's see how the data is displayed in the table.

Now, execute the "Start" block in test mode.

We can see the data that was written to the variable from the table in the message sent by the bot. Because we referenced the variable in the message using the #{} syntax, the data stored in it was displayed in the bot chat.

More details on how to work with the function get_records_from_table() are explained in the article "AI assistant with MaviBot table".

The project. prefix allowed the function to write the table data directly to the project's global variables, accessible in the "Variables" section.

You can edit project variables in the project settings.

Example: using project variables

Create a system that assigns a sequential number to each new client who enters the bot.

Implementation:

Navigate to your Project settings.
Create a new project variable (e.g., project.client_counter).

Set its initial value (e.g., 0) which means "No clients in the bot":

In the bot's start block, add logic that:

Increments the project variable's value by 1.
Assigns the new value to a client-specific variable for the current user.

Don’t forget to set a restriction so that the counter cannot be incremented for the same client twice.

How to set constant variables

Constants are fixed values that remain unchanged (or rarely change) throughout a project's lifecycle.

Key difference from global variables:

Unlike global variables, constants are client-specific. If a constant's value is modified, the change applies only to that individual client's session.

Common use cases:

Constants are ideal for storing static data such as:

Product prices and customer discounts
Integration tokens and API keys
Seller or support contact information
Any other fixed configuration values

Example: using constant variables

For example, a client's discount could be 10% by default, but change to 25% upon entering a promo code.

In "Project settings" → "Constants", enter: Discount : 10

To enter a promo code, add a "Trigger" block, where we assign the variable discount the value of 25.

Display the variable that shows the discount amount in the green block:

Step 1: Configure the automatic transition Create a connection with a zero-second timer from the gray block. This ensures the discount is applied immediately and the client proceeds to the message in the start block.

Step 2: Test the flow Now, write a message to the bot to trigger and test the entire sequence.

The standard discount is 10% without a promo code. However, entering a valid promo code changes the situation.

Thus, after entering the promo code, the variable "discount" for this client became 25.

This happened because an assignment like discount = 25 set the value for the deal variable, rather than changing the value of the constant with the same name.

Key deal variables

name - deal name. The term Name is used for the international version of the project.

description - tdeal description. Description is used in the international version of the project

budget - deal amount (number).

To edit variables using the API request /set_order_vars, you must use the names from this guide exactly as shown, including case sensitivity and the project version.

Limits

Maximum variable name length: 500 characters

Maximum variable value length: 100,000 characters

Maximum number of variables per client or deal: 1,000 characters.

How to work with variables correctly

When should you enclose a variable's value in quotation marks?

For example, client_id = 1202020202 or client_id = '1202020202'?

Both syntax options are functionally correct. Using quotation marks around a value only affects its visual highlighting in the calculator editor.

However, following consistent coding conventions improves readability and maintainability:

Omit quotes for numeric values (e.g., discount = 25).
Use quotes for string values (e.g., status = "active").

What is the correct syntax for passing identifiers such as Client ID, Site ID, Block ID, or Certificate ID to functions—should they be enclosed in quotation marks?

An ID should not be enclosed in quotation marks when passed to a method or function:

Which should be used: double quotes or single quotes?

There is no difference between using single or double quotation marks, but we recommend using double quotes. This way, for example, when inserting a variable inside a string, the variable will be highlighted in a different color, making it easier to notice.

How should spaces be placed?

Does it work the same if there is a space between the variable and the equals sign (for example, ans="yes", ans = "yes", ans= "yes", ans ="yes"?

Spacing does not affect the operation of methods, variables, or functions. However, it is recommended to use spaces in the code to improve readability.

How to write comments in the calculator correctly

For more details on how to write comments in the Calculator, please see this article.

How to compare variables

You can control the chatbot's flow by comparing variable values. This allows you to create conditional logic, such as verifying a user's age for legal compliance or routing interactions based on the user's messenger platform.

Here’s how to split the funnel by different messengers or by different accounts of the same messenger explained here.

Supported operators:

"+": addition "-"': substraction "*" multiplication "/": division "%'": remainder of division "^" "**": exponentiation "and" "AND" "&&": logical AND "or" "OR" "||": logical OR

Comparison operators: "==" — equal to "!=" — not equal to ">" — greater than "<" — less than ">=" — greater than or equal to "<=" — less than or equal to

IMPORTANT! To check that the built-in variable tag (the bot launch tag) is not present in the client’s card, use the following comparison method: tag == "NONE"

Variables should be compared in the condition within the "Variable" field (both in the connection settings and in the block settings):

Example of variable comparison in the "Variable" field of a trigger block.

Example of variable comparison in the "Variable" field of a block connection.

How variables and triggers work together

For a connection to be activated, both triggers must be met:

The condition in the "Trigger" field.
The comparison logic in the "Variable" field.

Understanding the "Variable" field

If you enter only a variable name (e.g., client_type) in the "Variable" field without an expression, the system checks for the existence or truthiness of the variable's value. It does not compare it to the user's raw input.

Example: The configuration below checks if the client is from WhatsApp by verifying that the client_type variable equals 6 (where 6 represents WhatsApp).

client_type == 6

The example below works identically:

Please note! You cannot specify multiple values for variable comparison in the "Trigger" field.

This is incorrect!

If you need to compare multiple variables, specify their values in the "Variable" field.

These options are correct.

client_type == 3 transition if the variable value equals 3 attachments != None transition if the variable contains any value attachments == None transition if the variable is not set product_quantity >= 100 transition if the product quantity is greater than or equal to 100 product_quantity <= 100 transition if the product quantity is less than or equal to 100 name == "John" transition if the variable name equals John

To check if a variable is empty or not, use the expressions: "#{value}" == "" "#{value}" != ""

(where value is the variable name).

The result of the comparison operation returns a boolean value: True or False.

Maximum expression length: 1000 characters

The default value will be returned as a result when attempting to compare values of different types.

"==" - False "<" - False "!=" - True ">=" - False ">" - False "<=" - False

IMPORTANT! To check that the built-in variable tag (the bot launch tag) is not present in the client’s card, use the following comparison method: tag == "NONE"

Example: a bot that checks a user's age (age).

If age < 18, it sends a message for minors.
If age >= 18, it sends a message for adults.

Note that the flow includes a block without a trigger, with timed connections leading from it.

This block is intentionally designed to demonstrate how to build flows where the bot reacts not to user actions, but to calculation results. At the first step, the answer is saved to a variable, and then the comparison takes place. The delay on the arrows is set to 0 for an instant response.

The comparison "Age >= 18" can also be expressed as "greater than or equal to 18."

Please note the errors in the triggers:

A number cannot be simultaneously greater than, less than, and equal to 18!

These triggers are meaningless. Every number is either less than 18, greater than 18, or equal to 18.

Important!

Logical triggers with variables must be written in the "Variable" field, not in the "Trigger" field!

For example, in the image below, the block will be triggered if the variable phone is filled (i.e., not equal to None):

The next example shows how to combine operators:

If the client has an age variable with a value between 18 and 99, the block will be triggered. If the variable is missing, or the age is less than 18 or greater than 99, the block will not activate.

Note!

If you compare a variable to a value in quotation marks, make sure there are no spaces between the quotes and the value; otherwise, the block may fail to trigger or behave incorrectly!

Correct (no space before the quotation mark or after the value my_new_bot):

Incorrect (with a space before the quotation mark):

PreviousVariables and functions NextCalculator

Last updated 12 days ago