Base de connaissances GetMyBot

Substitutions and Formulas

Variables in texts and actions, execution context, formulas, and functions.

Sur cette page

Substitutions are variables in the form {{...}} that are inserted into message texts, action fields, and button templates when a reaction fires. Unrecognized substitutions are left as-is. In addition to variables there are formulas for computations. The "Substitutions" button in the message editor helps you insert variables.

Sender data

  • {{first_name}}, {{last_name}}: first and last name.
  • {{username}}: the user's @username.
  • {{user_id}}: numeric Telegram ID.

Event and chat data

  • {{text}} (also {{received_message}}): the text of the incoming message.
  • {{message_id}} (also {{received_message_id}}): the ID of the incoming message.
  • {{chat_id}}, {{chat_title}} (also {{chat_name}}): the chat where the event occurred.
  • {{topic_id}}, {{topic_url}}: topic (for forums).

Date and time

  • {{date}}: date (YYYY-MM-DD), {{time}}: time (HH:MM), {{datetime}}: date and time.
  • Formatting: {{date:DD.MM.YYYY HH:mm}}: tokens YYYY, YY, MM, DD, HH, mm, ss.

User parameters

  • {{param.key}} (also {{params.key}} or {{recipient.key}}): the value of a subscriber parameter. Parameters are populated by the "Edit parameters", "Save message", and dialog-reply actions.

Execution context (ctx)

  • {{ctx.key}} (also {{context.key}}): temporary values of the current run: incoming webhook data, action results (web request, source query, AI), restored button data (Carry), loop elements.
  • In a list loop, the element is available under its alias, e.g. {{item.name}}.

Formulas

The {{= expression}} construct evaluates a short expression directly in text. The same expression language works in the "Formula" mode of the "Compute" action and in decision-table conditions. Expressions can reference parameters and ctx values by name and use arithmetic, comparisons, logic, the ternary ? : operator, and a few functions: len, upper, lower, trim, concat, round, floor, ceil, abs, min, max.

Examples: {{= price * qty}}, {{= round(total / 3)}}.

Advanced-formula functions (ROUND, IF, CONCAT, FILTER, HASH, etc.) do not work inside {{= }}. Compute the value with the "Compute" action in "Advanced formula" mode and insert the result with {{ctx.key}}.

Both languages in detail: Formulas.

HTML in substitutions

Messages are sent with HTML markup. To keep a substituted value from breaking the layout (e.g. when a user name contains <), substituted values are escaped by default: HTML characters become safe text. Tags you write directly in the reaction text (<b>, <a>, …) are left untouched.

If a value itself contains ready-made markup (e.g. an announcement stored in a parameter with <b>...</b>) and you want to insert it as-is, prefix the substitution with &:

  • {{& key}}: raw insertion for {{...}} substitutions.
  • {&user:key}, {&recipient:key}, {&global:key}: raw insertion for namespace substitutions.

The & prefix disables escaping for that one substitution only: you vouch for the trust of the value's source. Subscriber-controlled tokens ({{first_name}}, …) are best left escaped.

When importing bots from other builders, namespace substitutions {user:…}/{recipient:…}/{global:…} are automatically migrated to the raw form {&…}: they typically hold values with ready-made markup, matching how the source builder worked.

A note on format

Substitutions {{...}} work in texts, captions, request bodies, and button templates. Keep parameter and ctx key names short and in Latin characters (email, total, order_id): they are easier to embed in templates.

What's next