Константы в сценарии бота: полное руководство

Сценарий — это цепочка шагов: отправить текст, прочитать строку таблицы, проверить условие, перейти к другой ветке. Чтобы следующий шаг опирался не на «воздух», а на факты предыдущих, все промежуточные значения складываются в общий набор данных.

Константа здесь — не «неизменяемая величина из учебника по C++», а именованный слот в этом наборе: строка, число, да/нет, список или структура с полями. В шаблоне вы ссылаетесь на неё по имени в фигурных скобках и подставляете в сообщение имя клиента, найденную строку, флаг из условия и т.д.

Старт и событие Update

Набор констант обычно формируется на событии Update: пользователь написал боту, нажал кнопку, пришло системное событие и т.п. В «стартовый» пакет попадают, как минимум, сведения о боте и о пользователе, текущие дата и время в часовом поясе бота. Если дальше по цепочке подключены внешние сервисы, туда же могут попасть поля, которые вы явно запрашиваете или пробрасываете сценарием.

Каждый блок в цепочке

Логика простая и предсказуемая:

1. блок получает актуальный набор констант;
2. выполняет свою работу;
3. часто дописывает или перезаписывает значения;
4. передаёт набор следующему блоку.

Если имя уже было, а вы записали его снова, побеждает последняя запись: вы всегда смотрите на свежий результат последнего шага, который успел изменить этот ключ.

Не в каждом поле редактора разрешены шаблоны. Если у параметра включена поддержка выражений (в интерфейсе это часто подписано как «выражение» или «шаблон», в технических материалах — isExp), то внутри строки работают подстановки вроде {ПРЕФИКС.ТИП.ИМЯ} и специальные блоки вроде {#IF}.

Выключено — текст чаще всего уходит на выполнение «как есть», без подстановок. Перед тем как вставить длинное {MAIN.STRING…} или условие {#IF}, имеет смысл глянуть на переключатель режима поля: иначе фигурные скобки могут уехать к пользователю буквально.

Общий вид ключа — три части через две точки (ровно две, не больше и не меньше в типичной схеме):

{ПрефиксКомпонента.Тип.Имя}

Средняя часть — тип данных. Чаще всего встречаются:

• STRING — обычный текст;
• ARRAY — список или объект с полями (удобно для строк таблицы, каталогов);
• BOOL — да/нет, в том числе результат пункта условия.

Иллюстративные примеры (имена могут отличаться в вашем продукте):

# STRING — строка
{MAIN.STRING.USER_TELEGRAM_ID}

# ARRAY — строка таблицы, список или объект
{DATA.ARRAY.CURRENT_ROW}

# BOOL — результат условия (идентификатор пункта в имени)
{MAIN.BOOL.CONDITION_12_RESULT}

Подсказки редактора, которые подставляют готовый ключ в поле, обычно строятся по тому же принципу: префикс, тип, имя.

Вывести значение целиком

Если написать только имя без индексов и путей, в текст попадёт «сырое» представление — нередко это одна длинная строка в формате JSON. Удобно для отладки; для клиентского сообщения так делают реже.

Допустим, в {DATA.ARRAY.USER} лежит:

[
  {
    "name": "Анна",
    "id": 10
  },
  {
    "name": "Борис",
    "id": 20
  }
]

Шаблон целиком без индексов:

Данные: {DATA.ARRAY.USER}

В сообщение попадёт длинная строка с JSON всего массива — удобно сверить структуру при отладке.

Доступ к полю или элементу

После имени константы указывают шаги в квадратных скобках: индекс элемента или имя поля.

# индекс 0, поле name (в кавычках)
{DATA.ARRAY.USER}[0]['name']
→ Анна

# индекс 1, поле NAME (регистр имени поля часто не важен)
{DATA.ARRAY.USER}[1][NAME]
→ Борис

Если путь неверный (нет индекса или ключа), фрагмент может остаться в тексте в том виде, как вы его набрали — это сигнал проверить и данные, и запись пути.

Вложенность

Для вложенных объектов и списков скобки чередуются по уровню, например:

{DATA.ARRAY.ORDER}['items'][0]['title']

Смысл: заказ → список позиций → первая позиция → заголовок.

Если выражения включены, разбор идёт в фиксированном порядке:

1. Циклы — повтор фрагмента по элементам массива.
2. Условия — ветвление «если / иначе».
3. Дата и время — сдвиг от заданной точки на шкале времени.
4. Математика — вычисление формулы.
5. Обычные подстановки всех {…} и путей к полям массива.

Отсюда следует практическое следствие: нельзя рассчитывать, что сначала «везде подставятся константы», а уже потом сработает условие. Сначала раскрываются циклы и условия (с учётом вложенности), и только после этого — «простые» фигурные скобки.

1. {#EACH} … {/EACH}          — циклы по массиву
2. {#IF} … {#ELSE} … {/IF}   — условия
3. {#DATETIME; … ; …}        — дата и время
4. {#MATH} … {/MATH}         — формулы
5. {ПРЕФИКС.ТИП.ИМЯ} и пути  — обычные подстановки и [...]

7.1. Цикл {#EACH} … {/EACH}

В {DEMO.ARRAY.PRODUCTS} лежит, например:

[
  {
    "title": "Яблоко",
    "price": 50
  },
  {
    "title": "Груша",
    "price": 70
  }
]

Шаблон с циклом (разбит на строки для читаемости; в поле можно писать и в одну линию):

Каталог:
{#EACH {DEMO.ARRAY.PRODUCTS} @N as P}
  {P}['title'] — {P}['price'] руб.;
{/EACH}

Каталог: Яблоко — 50 руб.; Груша — 70 руб.;

На выходе по смыслу строка выше. В заголовке цикла задают массив, имя для номера строки (@N) и имя текущего элемента (P); внутри тела используют {@N}, {P}['поле'] и при необходимости другие константы.

Если по ключу не массив или разметка цикла с ошибкой, текст может не измениться или цикл просто не выполнится.

7.2. Условие {#IF} … {#ELSE} … {/IF}

Тот же массив из двух товаров. Шаблон:

{#IF LEN({DEMO.ARRAY.PRODUCTS}) > 0}
  В каталоге есть позиции
{#ELSE}
  Каталог пуст
{/IF}

В каталоге есть позиции

Каталог пуст

Что допустимо в выражении {#IF}

Текст условия — от ключевого слова {#IF} до границы ветки ({#ELSE} или {/IF}) — разбирается как отдельное выражение. Ниже перечислены типичные элементы грамматики; точный набор может зависеть от версии редактора, но перечисленное совпадает с тем, как парсер обычно ожидает лексемы «в лоб», без скрытых синонимов.

Практический вывод: пишите AND/OR заглавными и отделяйте их пробелами от имён полей и констант; проверяйте кавычки в строках и экранирование. Для отладки сложного условия временно выведите промежуточные куски в отдельное поле или упростите выражение скобками, пока не убедитесь, что литералы и ссылки подставляются так, как вы ожидаете.

7.3. Дата и время {#DATETIME}

Блок ожидает корректно заполненную структуру момента времени: дата, время, зона, метка — в том виде, в каком её отдаёт константа. Смысл шаблона: взять момент, например из {MAIN.ARRAY.EVENT}['start'], прибавить смещение (например, два дня) и получить одну строку результата.

Нет данных или неверный формат — вместо даты вы часто увидите служебное сообщение в квадратных скобках: так проще отловить ошибку в черновике или при отладке.

{#DATETIME;
  …параметры источника (константа с моментом времени)… ;
  …смещение и формат вывода…
}

Модификатор сдвига: знак + или -, затем целое число, затем одна из единиц (латиницей, как в парсере):

Пример смысла: + 2 days — вперёд на два дня, - 1 weeks — назад на одну неделю (точный вид записи в третьей части {#DATETIME;…;…} задаёт ваш редактор). Остальной синтаксис блока и формат строки результата могут отличаться между версиями; главное — корректный момент в константе-источнике и согласованная запись модификатора.

7.4. Математика {#MATH} … {/MATH}

В {DATA.ARRAY.LINE} лежит объект:

{
  "qty": 3,
  "price": 100
}

Шаблон:

К оплате:
{#MATH}
  {DATA.ARRAY.LINE}['qty'] * {DATA.ARRAY.LINE}['price']
{/MATH}
руб.

К оплате: 300 руб.

Типичный набор операций внутри формулы:

Ссылки {…}['поле'] внутри MATH должны давать число или строку, которую можно прочитать как число. Иначе вместо результата вы увидите блок с пометкой ошибки внутри {#MATH}…{/MATH} — например, при делении на ноль или при «пустом» значении.

Спецблоки разбираются до обычных подстановок; при ошибке разметки или данных вы чаще всего получаете либо «немой» текст как в редакторе, либо явное сообщение в квадратных скобках, либо внутри {#MATH} — префикс #ERROR с пояснением. Ниже сведены типичные случаи по каждой конструкции.

Таблица ошибок спецконструкций

{#EACH}

{#IF} / {#ELSE} / {/IF}

{#DATETIME;…}

{#MATH}…{/MATH}

Константы и данные вне спецблоков

• Сначала убедитесь, что предыдущий блок действительно пишет нужную константу — по названию блока и подсказкам поля.
• Шаблоны с подстановками вставляйте только туда, где включены выражения.
• Для массивов сверяйте реальную форму: список или объект, точные имена полей; для проверки временно выведите константу целиком.
• Сложную разметку дробите на шаги: отдельно условие или цикл, отдельно «чистый» текст с простыми STRING.
• Квадратные скобки с текстом ошибки в сообщении чаще всего указывают на условие или дату/время, а не на «полный отказ» бота.