База знаний GetMyBot

Подстановки и формулы

Как вставить имя клиента, ответ на вопрос или сумму заказа в сообщение. Где хранить данные и чем отличаются 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): так их удобнее подставлять.

Что дальше