GetMyBot नॉलेज बेस

Substitutions and Formulas

Add a customer's name, answer, or order total to a message. Learn where values are stored and how param differs from ctx.

इस पृष्ठ पर

To address someone by name, write Hello, {{first_name}}!. GetMyBot replaces {{first_name}} with the sender's name when it sends the message. These inserts are called substitutions. They work in messages, action settings, and button text. The editor's Substitutions button helps you choose one.

Data you needExampleHow long it lasts
Incoming message data{{text}}, {{first_name}}Belongs to the received event
Saved customer details{{param.email}}Persists between reaction runs
A request result or button choice{{ctx.product_id}}Temporary data for the current run

For example, save the answer to “What is your email?” in the email parameter. In the next message, write We will send confirmation to {{param.email}}. An unknown substitution stays in the text unchanged. Use formulas for calculations such as an order total.

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).

Telegram system events

For join, leave, status-change and join-request events, use {{system.*}} substitutions. {{user_id}} identifies the actor, such as an administrator, while {{system.subject_id}} identifies the member whose membership changed.

  • {{system.kind}}, {{system.subject_id}}, {{system.member_status}}: event type, member ID and new status.
  • {{system.invite_link}}, {{system.invite_link_name}}, {{system.creates_join_request}}: invite link, its name and whether it creates join requests.
  • {{system.via_join_request}}, {{system.via_folder_link}}: whether the person joined through an approved request or a folder link.
  • {{system.is_premium}}, {{system.is_bot}}, {{system.is_member}}: member flags, true or false; is_member indicates membership after the event.
  • {{system.bio}}, {{system.user_chat_id}}: profile biography and the applicant's temporary private chat, when supplied by Telegram.
  • {{system.date}}: Telegram event time in Unix seconds, not processing time.

If data is missing, known substitutions yield an empty string or false; unknown names remain in the text. The biography and invite-link name are external input: do not insert them as commands or raw markup. Do not publish invite links unnecessarily. Telegram permits use of {{system.user_chat_id}} for no more than five minutes, while the request is unprocessed and no other administrator has contacted the applicant. Do not store it as a permanent address or use it in place of the member ID for moderation.

Source and referrals

  • {{utm_source}}, {{utm_medium}}, {{utm_campaign}}, {{utm_content}}, {{utm_term}}: tags that identify where a person came from, such as an ad campaign. They arrive in the bot's start link. Such a link is also called a deep link; the extra part after start= is its payload or start tag.
  • {{referrals.count}}: the number of current, unmerged subscribers this person invited with a referral link (https://t.me/<bot>?start=ref_{{user_id}}). It is 0 if there are none. Only new subscribers count; another /start through someone else's link changes nothing.
  • {{referrer_id}}: the referrer's ID, empty if the person joined on their own.
  • {{ctx.referrer_id}}: available in the new subscriber's very first /start reaction after using a referral link. It belongs to that first start, not to the referral.joined event.

UTM tags accept both utm_source=vk&utm_medium=cpc and the Telegram format utm_source-vk__utm_medium-cpc. The first nonempty value is used for each key. A referrer in ref=<ID> or ref_<ID> is parsed separately.

The source is saved from the first start link with a nonempty tag. A later /start does not change the source or add UTM tags from a new link. If the first link had no UTM tags, those fields stay empty. An arbitrary tag is saved as a source without UTM values; a link without a tag does not set a source. See Subscriber source.

For example, a /start reaction can send Your link: https://t.me/<bot>?start=ref_{{user_id}} – invited: {{referrals.count}}. A reaction triggered by the Client event referral.joined handles a new invitation as the new subscriber. The event has referrer_tg_user_id, referrals_count, and start_payload; see Client or website event for recipient and substitution rules.

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.
  • {{label.name}}: 1 if the subscriber has a label with that name (case-insensitive; a label ID also works), otherwise empty. Useful in conditional text and for hiding buttons.
  • {{label.name.expires_at}}: when a temporary label expires, in YYYY-MM-DD HH:MM format. Empty for a permanent or missing label.
  • {{label.name.days_left}}: full days until a temporary label is removed, rounded up (0 when it has expired). Empty for a permanent label.

Execution context (ctx)

Think of the context as the bot's notes for one reaction run. One action finds products and stores them in ctx.products; the next action uses that list to create buttons. To remember a value for a later conversation, save it in a user parameter.

  • {{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