Подстановки и формулы
Как вставить имя клиента, ответ на вопрос или сумму заказа в сообщение. Где хранить данные и чем отличаются param и ctx.
На этой странице
Чтобы бот обращался к человеку по имени, напишите Здравствуйте, {{first_name}}!. При отправке GetMyBot заменит {{first_name}} именем отправителя. Такие вставки называются подстановками. Они работают в сообщениях, настройках действий и текстах кнопок. Кнопка «Подстановки» в редакторе помогает выбрать нужную.
| Какие данные нужны | Пример | Сколько хранятся |
|---|---|---|
| Данные входящего сообщения | {{text}}, {{first_name}} | Относятся к полученному событию |
| Сохранённые сведения о клиенте | {{param.email}} | Сохраняются между запусками реакций |
| Результат запроса или выбор кнопки | {{ctx.product_id}} | Временные данные текущего запуска |
Например, ответ на вопрос «Ваш email?» сохраните в параметр email. В следующем сообщении напишите Отправим подтверждение на {{param.email}}. Нераспознанная подстановка останется в тексте как есть. Для расчётов, например стоимости заказа, используйте формулы.
Данные отправителя
{{first_name}},{{last_name}}: имя и фамилия.{{username}}:@usernameпользователя.{{user_id}}: числовой Telegram-ID.
Данные события и чата
{{text}}(он же{{received_message}}): текст входящего сообщения.{{message_id}}(он же{{received_message_id}}): ID входящего сообщения.{{chat_id}},{{chat_title}}(он же{{chat_name}}): чат, где произошло событие.{{topic_id}},{{topic_url}}: топик (для форумов).
Системные события Telegram
В событиях вступления, выхода, изменения статуса и заявок на вступление доступны подстановки {{system.*}}. {{user_id}} обозначает инициатора события, например администратора, а {{system.subject_id}} – это затронутый участник, чьё членство изменилось.
{{system.kind}},{{system.subject_id}},{{system.member_status}}: вид события, ID участника и его новый статус.{{system.invite_link}},{{system.invite_link_name}},{{system.creates_join_request}}: ссылка-приглашение, её название и признак создания заявки.{{system.via_join_request}},{{system.via_folder_link}}: вступление через одобренную заявку или ссылку на папку.{{system.is_premium}},{{system.is_bot}},{{system.is_member}}: признаки участника со значениямиtrueилиfalse.is_memberпоказывает, состоит ли участник в чате после события.{{system.bio}},{{system.user_chat_id}}: описание профиля и временный личный чат заявителя, если Telegram передал их вместе с заявкой.{{system.date}}: время события Telegram в Unix-секундах, а не время его обработки ботом.
Если данные отсутствуют, известные подстановки дают пустую строку или false; неизвестное имя остаётся в тексте. Биография и название ссылки – внешние данные: не подставляйте их как команды или необработанную разметку. Ссылку-приглашение не публикуйте без необходимости. {{system.user_chat_id}} предназначен для оперативного ответа заявителю: Telegram разрешает использовать его не дольше пяти минут, пока заявка не обработана и другой администратор не связался с заявителем; не сохраняйте его как постоянный адрес пользователя и не используйте вместо ID участника для модерации.
Источник и рефералы
{{utm_source}},{{utm_medium}},{{utm_campaign}},{{utm_content}},{{utm_term}}: метки, по которым можно узнать источник перехода, например рекламную кампанию. Они передаются в ссылке запуска бота. Такие ссылки также называют deep-link. Дополнительная часть ссылки послеstart=называется payload, или меткой запуска.{{referrals.count}}: число текущих не объединённых подписчиков, приглашённых этим человеком по его реферальной ссылке (https://t.me/<bot>?start=ref_{{user_id}}). Если приглашённых нет, значение равно0. Считаются только новые подписчики: повторный/startпо чужой ссылке ничего не меняет.{{referrer_id}}: ID пригласившего; пусто, если человек пришёл сам.{{ctx.referrer_id}}: доступен именно в реакции на самый первый/startновичка, пришедшего по реферальной ссылке. Это контекст первого старта, а не свойство событияreferral.joined.
UTM принимаются в двух форматах: utm_source=vk&utm_medium=cpc и Telegram-формате utm_source-vk__utm_medium-cpc. Для каждого ключа берётся первое непустое значение. Пригласивший пользователь из ref=<ID> или ref_<ID> разбирается отдельно.
Источник фиксируется по первой ссылке запуска с непустой меткой. Этот принцип называется first-touch, или «первое касание». Повторный /start не меняет источник и не добавляет UTM из новой ссылки. Если в первой ссылке не было UTM, эти поля останутся пустыми. Произвольная метка сохраняется как источник без UTM; ссылка без метки не фиксирует источник. Подробный пример: Источник подписчика.
Пример реферальной механики: реакция на /start отправляет «Ваша ссылка: https://t.me/<bot>?start=ref_{{user_id}} – приглашено: {{referrals.count}}», а реакция с триггером Событие клиента referral.joined обрабатывает новое приглашение от лица новичка. У события есть свойства referrer_tg_user_id, referrals_count, start_payload; адресат действия и ограничения подстановок описаны в разделе Событие клиента / сайта.
Дата и время
{{date}}: дата (ГГГГ-ММ-ДД),{{time}}: время (ЧЧ:ММ),{{datetime}}: дата и время.- Форматирование:
{{date:DD.MM.YYYY HH:mm}}: токеныYYYY,YY,MM,DD,HH,mm,ss.
Параметры пользователя
{{param.ключ}}(он же{{params.ключ}}или{{recipient.ключ}}): значение параметра подписчика. Параметры наполняются действиями «Изменить параметры», «Сохранить сообщение» и ответами в диалоге.{{label.имя}}:1, если у подписчика есть метка с таким именем (регистр не важен; вместо имени можно указать id метки), иначе пусто. Удобно в условном тексте и для скрытия кнопок.{{label.имя.expires_at}}: срок действия временной метки в форматеГГГГ-ММ-ДД ЧЧ:ММ; пусто для бессрочной метки или если метки нет.{{label.имя.days_left}}: сколько полных дней осталось до снятия метки (округление вверх,0– срок уже вышел); пусто для бессрочной метки.
Контекст выполнения (ctx)
Контекст можно представить как рабочие заметки бота на время выполнения реакции. Одно действие запросило товары и положило результат в ctx.products, следующее берёт оттуда список для кнопок. Чтобы помнить значение при следующем разговоре, сохраните его в параметр пользователя.
{{ctx.ключ}}(он же{{context.ключ}}): временные значения текущего запуска: данные входящего вебхука, результаты действий (веб-запрос, запрос к источнику, ИИ), значения, переданные при нажатии кнопки (Carry), и элементы цикла.- В цикле по списку элемент доступен по своему псевдониму, например
{{item.name}}.
Формулы
Конструкция {{= выражение}} вычисляет короткую формулу прямо в тексте. Тот же язык работает в режиме «Формула» действия «Вычисление» и в условиях таблицы решений. Можно ссылаться на параметры и временные значения ctx по имени, складывать и сравнивать числа, проверять условия и использовать выбор по условию ? :. Доступные функции: len, upper, lower, trim, concat, round, floor, ceil, abs, min, max.
Примеры: {{= price * qty}}, {{= round(total / 3)}}.
Функции расширенной формулы (ОКРУГЛ, ЕСЛИ, СЦЕПИТЬ, FILTER, HASH и др.) внутри {{= }} не работают. Посчитайте значение действием «Вычисление» в режиме «Расширенная формула» и подставьте результат через {{ctx.ключ}}.
Оба языка подробно: в разделе Формулы.
HTML в подстановках
Сообщения отправляются с разметкой HTML. Чтобы значение подстановки не сломало вёрстку (например, если имя пользователя содержит <), подставляемые значения по умолчанию экранируются: HTML-символы превращаются в безопасный текст. Собственные теги, которые вы написали прямо в тексте реакции (<b>, <a> и т.п.), не трогаются.
Если значение само содержит готовую разметку (например, сохранённый в параметре анонс с <b>...</b>) и вы хотите вставить её как есть, пометьте подстановку префиксом &:
{{& ключ}}: сырая вставка для{{...}}-подстановок.{&user:ключ},{&recipient:ключ},{&global:ключ}: сырая вставка для namespace-подстановок.
Префикс & отключает экранирование только для конкретной подстановки: вы берёте на себя доверие к источнику значения. Подписчик-контролируемые токены ({{first_name}} и т.п.) лучше оставлять экранированными.
При импорте ботов из других конструкторов namespace-подстановки {user:…}/{recipient:…}/{global:…} автоматически переносятся в сырую форму {&…}: там часто лежат значения с готовой разметкой, как это и работало в исходном конструкторе.
Важно про формат
Подстановки {{...}} работают в текстах, подписях, телах запросов и шаблонах кнопок. Имена параметров и ключей ctx давайте короткими и латиницей (email, total, order_id): так их удобнее подставлять.
Что дальше
- Формулы: синтаксис DSL и полный список функций.
- Сообщения и кнопки: где применяются подстановки.
- Действия: действия, которые наполняют параметры и
ctx. - Коллекции и данные: хранение данных между запусками.