Documentation
Automation

Expression Language

Use expressions in builder text blocks, variables, and message templates.

The expression language is used for substitutions, text transformations, and simple conditions in builder blocks and message templates.

Expressions are written inside {...}.

Where Expressions Are Used

Expressions are available in two places:

  • builder blocks;
  • message templates.

Basic Syntax

Use an expression inside a text string when you want to insert a value:

Hello, {client.name}!

If a whole field contains only one expression, the full field value is taken from that expression:

{funnel.order_total}

When an expression is embedded inside normal text, its result is inserted into the final string.

Embedded expressions must return a simple value:

  • string
  • number
  • boolean
  • null

Rendering behavior:

  • null becomes an empty string;
  • true and false become the strings true and false;
  • an object or array inside a normal text template causes an error.

Available Variables

Message Templates

Message templates can use:

  • client.*
  • chat.*
  • operator.*
  • message.*

The same values are also available through sys.*:

  • sys.client.*
  • sys.chat.*
  • sys.operator.*
  • sys.message.*

Builder Blocks

Builder blocks use system variables through sys.*:

  • sys.client.*
  • sys.chat.*
  • sys.operator.*
  • sys.message.*
  • sys.execution.*
  • sys.date, sys.time, and sys.datetime

Builder blocks can also use:

  • funnel.<key>
  • env.<KEY>

System Variables

Client

  • client.name
  • client.id
  • client.external_id
  • client.phone
  • client.comment

Chat

  • chat.id
  • chat.status
  • chat.channel

Operator

  • operator.id
  • operator.name

Message

  • message.id
  • message.text
  • message.type
  • message.direction

Builder expressions also expose these message details through sys.message.*:

  • sys.message.has_media — whether the inbound message has media attachments;
  • sys.message.has_text — whether the inbound message has non-empty text;
  • sys.message.reply_to_id — ID of the message being replied to, when available.

Inbound message media details are available through sys.message.media.*:

  • sys.message.media.count
  • sys.message.media.photo_count
  • sys.message.media.document_count
  • sys.message.media.video_note_count
  • sys.message.media.voice_count
  • sys.message.media.urls — an array of public media URLs;
  • sys.message.media.items — an array of media objects with id, url, type, mime_type, filename, and size fields.

For example, check whether an inbound message contains media or join its URLs:

sys.message.media.count > 0
join(sys.message.media.urls, ", ")

Execution

These variables are available in builder expressions:

  • sys.execution.id — ID of the current automation run;
  • sys.execution.trigger — trigger type that started the run.

Current Date and Time

These variables are available in builder expressions and use UTC:

  • sys.date — current date in d.m.Y format, for example 23.10.2026;
  • sys.time — current time in H:i format, for example 14:35;
  • sys.datetime — current date and time in ISO 8601 format with timezone offset.

sys.date can be passed directly to date functions:

ADD_DAYS(sys.date, -5)

This returns the date five days earlier, in the same d.m.Y format.

Client Custom Fields

Client custom fields are available as:

client.customfield.<field_key>

In builder blocks, the common form is:

sys.client.customfield.<field_key>

Funnel Variables

Use funnel variables for values collected or calculated inside the funnel:

funnel.order_total
funnel.stage_code
funnel.is_repeat_client

Funnel variable keys must:

  • be lowercase;
  • start with a letter;
  • contain only letters, digits, and _.
  • be no longer than 64 characters.

Funnel variables can contain strings, numbers, booleans, or arrays. Array values can be read and passed to array functions such as join, count, and first.

Environment Variables

Use environment variables for configured values:

env.API_URL
env.COUNTRY_CODE

Environment variable names must:

  • be uppercase;
  • start with a letter;
  • contain only letters, digits, and _.
  • be no longer than 64 characters.

Environment variables can contain strings, numbers, or arrays. Boolean values are not supported.

Functions

Lowercase

Signature: lowercase(value): string

Converts a string to lowercase.

lowercase(sys.message.text)

Uppercase

Signature: uppercase(value): string

Converts a string to uppercase.

uppercase(sys.client.name)

Length

Signature: length(value): number

Returns the string length.

length(sys.message.text)

Replace

Signature: replace(value, search, replace): string

Replaces all occurrences of a string.

replace(sys.message.text, "hello", "hi")

Regex Replace

Signature: regex_replace(value, pattern, replacement): string

Replaces text with a regular expression.

regex_replace(sys.message.text, '#^/start\\s+#', '')

If the regular expression is invalid, the expression returns an error.

Base64

Signature: base64(value): string

Encodes a string as Base64.

base64(sys.client.id)

Numbers

Random

Signature: random(min, max): number

Returns a random integer between min and max, inclusive.

random(5, 10)

Floor

Signature: floor(value): number

Rounds a number down to the nearest integer.

floor(funnel.order_total)

Array Functions

Join

Signature: join(value, separator = ", "): string

Joins array items into a string. The separator is optional and defaults to ", ".

join(sys.message.media.urls, " | ")

Count

Signature: count(value): number

Returns the number of items in an array.

count(sys.message.media.urls)

First and Last

Signatures: first(value, fallback = null): mixed, last(value, fallback = null): mixed

Return the first or last array item. If the array is empty, they return the optional fallback, or null when no fallback is provided.

first(sys.message.media.urls, "no media")
last(funnel.answers)

Slice

Signature: slice(value, offset, limit = null): array

Returns a portion of an array starting at offset. A negative offset counts from the end. The optional limit sets the maximum number of returned items.

slice(funnel.answers, -3)
slice(sys.message.media.urls, 0, 2)

Pluck

Signature: pluck(value, key): array

Returns the value of key from each object in an array.

pluck(sys.message.media.items, "url")

Unique

Signature: unique(value): array

Removes duplicate items from an array while preserving their order.

unique(funnel.selected_tags)

Contains

Signature: contains(value, needle): boolean

Checks whether an array contains the given value.

contains(sys.message.media.urls, "https://cdn.example.com/photo.jpg")

Date Functions

Date functions accept these input formats: d.m.Y H:i:s, d.m.Y, H:i:s, Y-m-d H:i:s, and Y-m-d. Date arithmetic preserves the input format. Invalid dates cause an expression error.

Format Date

Signature: DATE_FORMAT(date, format): string

Formats a date using PHP date format tokens.

DATE_FORMAT("15.09.2023 15:34:12", "d F Y")

Add to a Date

Signatures: ADD_DAYS(date, amount): string, ADD_MONTHS(date, amount): string, ADD_YEARS(date, amount): string, ADD_HOURS(date, amount): string, ADD_MINUTES(date, amount): string, ADD_SECONDS(date, amount): string

Adds the given number of days, months, years, hours, minutes, or seconds to a date or time.

ADD_DAYS("03.09.2023", 4)
ADD_MINUTES("15.09.2023 15:34:12", 30)

JSON Decode

Signature: jsonDecode(value): mixed

Parses a JSON string and returns its value. JSON objects can be accessed by property, and JSON arrays can be accessed by index or passed to array functions.

jsonDecode('{"message":"Hello"}').message
jsonDecode('["red", "blue"]')[0]

You can use a decoded property in a condition or as a scalar in a text template:

jsonDecode(funnel.api_response).status == "ok"
Status: {jsonDecode(funnel.api_response).status}

Invalid JSON causes an evaluation error. A decoded object or array cannot be inserted directly into ordinary text; select a scalar property or array item instead.

Operators

Supported operators:

  • and
  • or
  • not
  • ==
  • !=
  • >
  • >=
  • <
  • <=
  • +
  • -
  • *
  • /
  • %
  • ~
  • in
  • matches
  • ??

Use ~ for string concatenation.

Conditions

Conditions can be used inside expressions to calculate the required value.

Supported comparisons and logical operators:

  • ==
  • !=
  • >
  • >=
  • <
  • <=
  • and
  • or
  • not

Examples:

sys.client.customfield.tariff == "premium" and sys.chat.channel == "telegram"
length(message.text) > 10
sys.chat.channel == "telegram" ? "TG client" : "Other client"

Conditions also support:

  • strings in single or double quotes;
  • numbers;
  • true, false, null;
  • arrays: [1, 2, 3];
  • in;
  • matches;
  • ternary expressions: condition ? a : b;
  • null coalescing: a ?? b.

Examples:

"telegram" in ["telegram", "whatsapp"]
sys.message.text matches '#^/start\\s+#i'
funnel.discount ?? 0

in checks whether a value is present in an array. matches tests a string against a delimited PCRE pattern. ?? returns the right-hand value when the left-hand value is null.

Regular Expressions in Conditions

Use matches to test whether a string matches a regular expression. The right-hand value must be a string containing a PHP-compatible PCRE pattern, including its delimiters:

sys.message.text matches '#^/start\\s+#i'

The example matches /start at the beginning of the message, followed by whitespace; the i flag makes the match case-insensitive. Without ^ or $, a match can occur anywhere in the string. Escape backslashes in the expression string, as shown with \\s above. An invalid pattern causes an expression error.

Builder Variables

Store runtime data and reusable configuration for automation funnels.

Bulk Operations

Run scheduled or manual actions for filtered client groups.

On this page

Where Expressions Are UsedBasic SyntaxAvailable VariablesMessage TemplatesBuilder BlocksSystem VariablesClientChatOperatorMessageExecutionCurrent Date and TimeClient Custom FieldsFunnel VariablesEnvironment VariablesFunctionsLowercaseUppercaseLengthReplaceRegex ReplaceBase64NumbersRandomFloorArray FunctionsJoinCountFirst and LastSlicePluckUniqueContainsDate FunctionsFormat DateAdd to a DateJSON DecodeOperatorsConditionsRegular Expressions in Conditions