The “Formula” Step is a code editor block where you can perform logical and arithmetic operations, use built-in functions, and manage variables.
With it, you can assign values to fields and variables, calculate metrics, compare data, and build complex scenarios directly inside BotHelp.

Where to Find It and How to Enable It

  1. In the flow builder, select Add Step → Formula.
  2. A code editor will open inside the step.

For convenience, you can use the expanded editing mode (the “expand” icon).

How the “Formula” Step Works

  1. The subscriber enters the step.
  2. The code in the “Formula” editor is executed (from top to bottom, line by line).
  3. If the execution is successful, the values are written to the selected variables, and the bot continues along the configured Next Step transition.
  4. If an error occurs during execution (for example, division by zero, an empty value, or incompatible types), the execution stops at the line where the error occurred.
    The results from the lines that were successfully executed are saved, and the remaining code is not executed.
    After that, the subscriber proceeds to the next step via the Next Step transition.

Working with Variables

Inside the step, you can use variables of different types. They allow you to store and transfer values between steps, users, and bots.

There are three types available:

  1. User Fields: available for reading and writing.
    Used with the prefix client. or via {%variable_name%}.
    Examples: client.price, {%Position%}
  2. Global Variables: available for reading and writing.
    Used with the prefix globals. or via {@variable_name@}.
    Examples: globals.order, {@discount@}
  3. Local Variables: used as helper variables and work only within a specific “Formula” step. Available for reading and writing.
    Used without a prefix.
    Example: age_years = 25
  4. System Fields: UserId, BotHelpId, CUID are read-only. Writing to them will cause an error.
    Accessible both with the client. prefix (if applicable) and via macros.

Variable Naming Rules

1. General Rules

  1. A variable name can only start with a letter, not a number.
    ✅ Sum1  ❌ 1Sum
  • Allowed characters: Latin letters, Cyrillic letters, numbers, and underscores.
  • Names cannot match:

    • system field names (user_id, bh_user_id, cuid, etc.);

    • the prefixes client and globals;

    • reserved programming language words, e.g., print, true, false, etc.

2. Spaces in Names
If you need spaces in a name, access the variable using index notation:

globals['возраст клиента'] = 27
client['ORDER ID'] = 'A-42'

3. Code Limitations

  • Total code size: up to 50 lines and 5000 characters (including line breaks and tabs).

  • String literals (text in quotes "...") — up to 1000 characters.

4. Recommendations

  • Use Latin letters for variable names.

  • For multiple words, use underscores: blog_webinar, order_total.

  • Give variables meaningful and unique names — it simplifies debugging and teamwork.

Data Types:

  • Number (integer and decimal): 10, 2.5

  • String: "text"

  • Boolean: True, False

  • Date/Time: "2025-10-10" or "10.10.2025 12:00:00"

  • Empty Value: null

Note: Lists ([1,2,3]), dictionaries ({"a":1}), and objects (None) are not supported in the “Formula” step.

Conversions:

  • str(number) → string

  • int("42"), float("12.5") → number

  • Comparing different types converts them to strings.

Commenting

To make the code easier to read and maintain, you can add comments.
Comments do not affect the execution of formulas and are intended only to explain the logic.

Comment Types:

Single-line Comment

# This is a single-line comment
a = 10 # Can also be written after an expression

Multi-line Comment

"""
Multi-line comment
For example, to describe calculation logic
"""

Available Functions in the “Formula” Step

The “Formula” step supports a set of built-in functions for working with numbers, strings, dates, and logical conditions.
They allow you to perform calculations, conversions, and validations directly within the scenario, without relying on external systems.

Mathematical Functions

Function Description Example
round(x) Rounds a number to the nearest integer (0.5 rounds up). round(2.5) → 3
abs(x) Returns the absolute value of a number. abs(-5) → 5
int(x) Converts a value to an integer. int("42") → 42
float(x) Converts a string to a floating-point number. float("12.34") → 12.34
str(x) Converts a value to a string. str(100) → "100"

Arithmetic operations supported: +, -, *, /

Logical and Conditional Functions

Function Description Example
if(condition, then_value, else_value) Checks a condition. Returns then_value if true, otherwise else_value. if(client.age >= 18, "Adult", "Minor")
if(condition, then_value) If else_value is not specified, returns an empty string. if(is_null(client.phone), "Phone not provided")
is_null(var) Checks if a variable is empty. is_null(client.email) → True
and, or, not Logical operators for combining conditions. if(a > 0 and b < 10, "ok")

Boolean values supported: True, False

String Functions

Function Description Example
len(text) Returns the number of characters in a string. len("Hello") → 5
substring(str, n1, n2) Trims a string: n1 = chars to keep from the start, n2 = chars to remove from the end. substring("BotHelp", 3, -2) → "tHel"
upper(text) Converts text to uppercase. upper("hello") → "HELLO"
lower(text) Converts text to lowercase. lower("HELLO") → "hello"
split(text, separator) Splits a string by a separator and returns the first part. split("Ivan Petrov", " ") → "Ivan"
match(text, pattern, ignore_case=True) Checks if a string contains a specified word (pattern). match("buy product", "buy") → True

Date and Time Functions

Function Description Example
get_current_time() Returns the current date and time in the workspace timezone. Format: %Y-%m-%d %H:%M:%S. globals.now = get_current_time() → "2025-11-11 16:30:00"
addYear(date, years) Adds or subtracts years (accounts for leap years). Use negative numbers to subtract. addYear("2020-01-01", 3) → "2023-01-01"
addMonth(date, months) Adds or subtracts months (accounts for month length and leap years). addMonth("2025-01-10", 2) → "2025-03-10"
addDays(date, days) Adds or subtracts days. Use negative numbers to subtract. addDays("20.08.2019", -99) → "13.05.2019"
addMinutes(date, minutes) Adds or subtracts minutes (for DateTime values). addMinutes(get_current_time(), 20) → "2025-11-11 16:50:00"
format_date(date, "format") Converts a date to the specified format. Supported formats: %Y-%m-%d, %d.%m.%Y, %Y-%m-%d %H:%M:%S, %d.%m.%Y %H:%M:%S. format_date("2025-10-10", "%d.%m.%Y") → "10.10.2025"
date_diff(date1, date2, unit) Returns the difference between two dates. unit can be "days" or "minutes". date_diff(get_current_time(), client.birth_date, "days") → 9125

All operations are performed in the workspace timezone. Multiplying or dividing dates will cause a Type Error.

Functional Notes

  • Code in the “Formula” step executes line by line, top to bottom, in an isolated BotHelp environment.

  • Syntax is similar to Python but not identical.

  • Only simple expressions are supported — no loops (for, while), functions (def), or external imports.

  • Code cannot call APIs or access external systems.

  • Variables are created upon first assignment.

Если вы не нашли ответ на свой вопрос, задайте его нам в чате внутри кабинета либо напишите в Telegram BotHelpSupportBot или на почту hello@bothelp.io 

Получите 14 дней полного функционала платформы для создания рассылок, автоворонок и чат-ботов BotHelp.

Получить 14 дней бесплатно

Была ли статья полезна?

Спасибо за обратную связь!