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

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

Дані відправника

  • {{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>) і ви хочете вставити її як є, позначте підстановку префіксом &:

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

Префікс & вимикає екранування лише для конкретної підстановки — ви берете на себе довіру до джерела значення. Підписник-контрольовані токени ({{first_name}} тощо) краще залишати екранованими.

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

Важливо про формат

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

Що далі