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

Подстановки — это переменные вида {{...}}, которые подставляются в тексты сообщений, поля действий и шаблоны кнопок при срабатывании реакции. Нераспознанные подстановки остаются как есть. Помимо переменных есть формулы для вычислений. Вставить переменную помогает кнопка «Подстановки» в редакторе сообщения.

Данные отправителя

  • {{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}} — топик (для форумов).

Дата и время

  • {{date}} — дата (ГГГГ-ММ-ДД), {{time}} — время (ЧЧ:ММ), {{datetime}} — дата и время.
  • Форматирование: {{date:DD.MM.YYYY HH:mm}} — токены YYYY, YY, MM, DD, HH, mm, ss.

Параметры пользователя

  • {{param.ключ}} (он же {{params.ключ}} или {{recipient.ключ}}) — значение параметра подписчика. Параметры наполняются действиями «Изменить параметры», «Сохранить сообщение» и ответами в диалоге.

Контекст выполнения (ctx)

  • {{ctx.ключ}} (он же {{context.ключ}}) — временные значения текущего запуска: данные входящего вебхука, результаты действий (веб-запрос, запрос к источнику, ИИ), восстановленные данные кнопки (Carry), элементы цикла.
  • В цикле по списку элемент доступен по своему псевдониму, например {{item.name}}.

Формулы

Конструкция {{= выражение}} вычисляет выражение прямо в тексте. Тот же движок работает в действии «Вычисление» и в условиях таблицы решений. В выражениях можно ссылаться на параметры и значения ctx по имени, использовать арифметику, сравнения, логику и десятки функций с русскими алиасами (ОКРУГЛ, ЕСЛИ, СЦЕПИТЬ и др.).

Пример: {{= ОКРУГЛ(param.total * 0.9) }} — скидка 10% от суммы из параметра.

Полный синтаксис и список функций — в разделе Формулы.

HTML в подстановках

Сообщения отправляются с разметкой HTML. Чтобы значение подстановки не сломало вёрстку (например, если имя пользователя содержит <), подставляемые значения по умолчанию экранируются: HTML-символы превращаются в безопасный текст. Собственные теги, которые вы написали прямо в тексте реакции (<b>, <a> и т.п.), не трогаются.

Если значение само содержит готовую разметку (например, сохранённый в параметре анонс с <b>...</b>) и вы хотите вставить её как есть, пометьте подстановку префиксом &:

  • {{& ключ}} — сырая вставка для {{...}}-подстановок.
  • {&user:ключ}, {&recipient:ключ}, {&global:ключ} — сырая вставка для namespace-подстановок.

Префикс & отключает экранирование только для конкретной подстановки — вы берёте на себя доверие к источнику значения. Подписчик-контролируемые токены ({{first_name}} и т.п.) лучше оставлять экранированными.

При импорте ботов из других конструкторов namespace-подстановки {user:…}/{recipient:…}/{global:…} автоматически переносятся в сырую форму {&…} — там часто лежат значения с готовой разметкой, как это и работало в исходном конструкторе.

Важно про формат

Подстановки {{...}} работают в текстах, подписях, телах запросов и шаблонах кнопок. Имена параметров и ключей ctx давайте короткими и латиницей (email, total, order_id) — так их удобнее подставлять.

Что дальше