Сценарии действий
Сценарий действий — это фоновая логика, которая выполняется до или после показа блока клиенту. Здесь происходят все «невидимые» вещи: расчёты, обращения к API, чтение/запись списков и переменных, оплаты, интеграции с внешними сервисами.
Сообщение — это то, что видит клиент. Сценарий действий — это то, что бот делает.
Когда использовать
| Задача | Решение |
|---|---|
| Сохранить ответ клиента в базу | Сценарий действий → Списки |
| Посчитать сумму со скидкой | Сценарий действий → переменная + выражение |
| Получить курс валюты с внешнего API | Сценарий действий → HTTP-запрос |
| Принять оплату от клиента | Сценарий действий → Платежи |
| Подтянуть товар из Google Таблиц | Сценарий действий → Google Таблицы |
| Использовать нейросеть для ответа | Сценарий действий → Нейросеть |
| Завести лид в CRM | Сценарий действий → CRM |
Часть 1. Подключение к блоку
В каждом блоке — две точки для сценария действий:
- До отправки — выполняется перед показом сообщения. Используйте для подготовки данных.
- После отправки — выполняется после показа. Используйте для логирования, тегов, уведомлений.
Кнопка «Создать» создаёт новый сценарий или подключает существующий.
Скриншот 1. Кнопки «Создать» — сценарий действий до и после блока.
Один сценарий действий можно подключить к разным блокам — это удобно для общей логики (например, «логировать ответ»).
Часть 2. Структура сценария
Сценарий — это последовательность действий. Каждое действие — отдельный тип операции (HTTP, оплата, операции с данными и т.д.).
Скриншот 2. Список действий внутри сценария.
Действия выполняются с первого, переход к следующему действию задается явно «После действия» или по условию. Внутри одного действия могут быть свои операции (например, в «Операциях с данными» — несколько переменных и списков).
Часть 3. Доступные действия
В Квесче доступно 18 типов действий. Сгруппируем их по назначению.
3.1. Данные и логика
| Действие | Что делает | Подробно |
|---|---|---|
| Операции с данными (Переменные, Списки) | Создание переменных, чтение/запись/изменение списков, перебор массивов | Операции с данными |
| Обмен данными (HTTP-запросы) | GET/POST/PUT/DELETE к любому API. Заголовки, авторизация, тело, парсинг ответа | HTTP-запросы |
| JS код | Произвольный JavaScript с доступом к переменным сценария | JS код |
| Проверка тегов | Проверить наличие тегов у подписчика для ветвления | Проверка тегов |
3.2. Платежи и заявки
| Действие | Что делает | Подробно |
|---|---|---|
| Платежи | Сформировать платёжную ссылку, принять платёж, генерировать ID заказа | Платежи |
| Ссылки | Сократить URL, сгенерировать UTM, передать параметры | Ссылки |
3.3. AI и WebApp
| Действие | Что делает | Подробно |
|---|---|---|
| Нейросеть | ChatGPT / другие LLM: генерация ответа, обработка текста, классификация | Нейросеть |
| WebApp / MiniApp | Открыть мини-приложение Telegram/MAX (магазин, корзина, форма) | WebApp |
| Реферальная система | Реферальные ссылки и счётчики приглашений | Реферальная система |
3.4. Медиа и документы
| Действие | Что делает | Подробно |
|---|---|---|
| Приём и пересылка медиа | Получить медиа от клиента, переслать в чат менеджера, сохранить ID | Приём медиа |
| Генерация документа из шаблона | Подставить переменные в DOCX/PDF-шаблон и отправить клиенту | Генерация документа |
3.5. Google-сервисы
| Действие | Что делает | Подробно |
|---|---|---|
| Google Таблицы | Чтение/запись строк, фильтрация, обновление ячеек | Google Таблицы |
| Google Календарь | Создать/обновить/удалить событие, прислать напоминание | Google Календарь |
| Google Диск | Загрузить файл, получить публичную ссылку | Google Диск |
3.6. CRM и каналы
| Действие | Что делает | Подробно |
|---|---|---|
| CRM | Создать сделку, контакт, отправить заявку в AmoCRM/Bitrix24 | CRM |
| Яндекс Диск | Загрузить файл, выдать публичную ссылку | Яндекс Диск |
| Группы и каналы Telegram | Отправить пост в канал, добавить/удалить пользователя, проверить подписку | Группы и каналы Telegram |
| Группы и каналы МАКС | То же для MAX | Группы и каналы МАКС |
Часть 4. Жизненный цикл значения внутри сценария
Внутри одного сценария действия видят результаты друг друга:
- HTTP-запрос получает ответ → сохраняет в переменные.
- Действие «Операции с данными» и «JS Код», разбирает JSON и сохраняет нужные переменные в список.
- Действие «Платежи» использует переменную с суммой и формирует ссылку.
- Сохраняется в глобальную переменную порядковый номер счета.
- Все данные доступны в блоке через переменные
#{имя_переменной}.
Скриншот 3. Цепочка действий внутри сценария.
Часть 5. Принципы построения сценариев действий
Принцип 1. Один сценарий — одна задача
Как правило задача сценария действия определяется блоком, который его вызывает.
Принцип 2. Сложные расчёты — заранее, в «До отправки»
К моменту, когда блок должен показать клиенту цифру, она уже должна быть в переменной. Расчёты в «После» — клиент уже увидел сообщение, поздно.
Принцип 3. Имена переменных — осмысленные
#{x1}, #{tmp} — через неделю вы забудете, что они значат. Используйте #{order_total}, #{client_age}.
Принцип 4. Логи — в «После отправки»
Запись в список «История», уведомление в Telegram, постановка тега — это всё после того, как клиент увидел сообщение.
Принцип 5. Не дублируйте действия
Один сценарий действий можно подключить к нескольким блокам. Не создавайте 10 одинаковых.
Принцип 6. Обрабатывайте ошибки внешних сервисов
HTTP-запрос может вернуть 500. CRM может быть недоступна. Используйте проверку результата (через переменную статуса) и запасной путь — например, сохранить в список «Ошибки» и уведомить менеджера.
Часть 6. После действия
У каждого действия есть раздел «После действия» (в редакторе на отдельной странице он называется «Сделать»). Там задаётся то, что происходит помимо перехода к следующему действию: добавить теги, снять теги, отправить цели в метрику — и завершить сценарий.
Завершить сценарий
Пока выполняется сценарий шага цепочки, следующий шаг не запускается — он ждёт. Опция «Завершить сценарий» закрывает шаг, и цепочка идёт дальше.
Это не то же самое, что выход из сценария действий: выход возвращает подписчика в диалог, а шаг цепочки при этом остаётся открытым.
| Настройка | Что делает |
|---|---|
| Номер шага цепочки | Какой шаг запустить, считая с 1. Пусто — следующий по порядку. Можно подставить переменную: #{номер_урока} |
| Запустить шаг сразу | Не ждать интервал шага. Без галки шаг уйдёт по своему расписанию |
| Указать адресатов | Завершить сценарий не у себя, а у названных подписчиков (ClientID, Мессенджер, BotID) |
Пустое поле адресатов означает «у самого подписчика, который выполняет сценарий».
С адресатами шаг закрывается у других подписчиков. Так куратор из своего сценария отправляет ученику следующий урок, а тот ничего не нажимает. Формат адресатов тот же, что у отправки сообщения другому подписчику.
Номер шага, которого в цепочке нет (опечатка, пустая переменная, слишком большое число), цепочку не обрывает — запустится следующий шаг по порядку.
Номер можно указать и меньше текущего: так шаг повторяется или цепочка возвращается назад.
«Завершить сценарий» есть в двух местах: здесь, в «После действия», и среди вариантов «Выхода». Делают они одно и то же — закрывают шаг цепочки. Ставьте только одну. Вместе они закроют шаг дважды и перескочат через следующий, а на последнем шаге закроют цепочку целиком.
Разница между ними в том, уйдёт ли блок:
- «Выход» → «Завершить сценарий» — блок не отправляется. Сценарий выполняется до отправки, и закрытие шага отменяет её;
- «После действия» → «Завершить сценарий» — блок отправляется, а следом закрывается шаг. Здесь же можно назвать шаг перехода и закрыть шаг другим подписчикам.
Порядок: сначала сообщение, потом теги
Если в одной ветке стоят «Выход — возврат сообщения» и теги, бот сначала отправит блок и только потом навесит теги.
Это важно, когда тег запускает другую цепочку. Раньше цепочка стартовала внутри сценария — до отправки, — и её сообщения приходили раньше того, ради которого сценарий и вызывался. С задержкой в блоке новой цепочки сообщение ждало ещё и эту задержку.
Сам тег при этом навешивается сразу: проверки «есть ли у подписчика тег» дальше по сценарию видят новое состояние. Откладывается только запуск и остановка цепочек по этому тегу.
Часть 7. Отладка сценария действий
Журнал запусков
Кнопка «Отладка» у сценария открывает окно с переключателем «Записывать запуски». Пока он включён, каждый запуск сценария сохраняется: какое действие сработало, что изменилось в переменных и где случилась ошибка.
- Хранятся последние 20 запусков.
- Через сутки запись выключается сама — забытая галка не будет копить записи.
- Поле «Только для подписчика (ClientID)» оставляет в журнале запуски одного человека. На работающем боте чужой трафик за секунды вытеснит ваш собственный тест.
- Галка «Показывать все переменные, а не только изменения» разворачивает снимок целиком. По умолчанию видно то, что поменялось, — так журнал читается, а не листается.
Включить отладку сразу у всех сценариев цепочки можно из карточки «Проверить цепочку на себе» на странице цепочки.
Почему сценарий пошёл этой веткой
Под каждым шагом журнал показывает ветвление целиком:
Действие 3: Работа с данными +12 мс
стало: статус = оплачен
условие 1: 'оплачен' == 'новый' — нет
условие 2: 'оплачен' == 'оплачен' — сработало
→ дальше действие 5
Условия показываются с подставленными значениями, а не шаблонами: видно не #{статус} == 'оплачен', а 'оплачен' == 'оплачен'. Именно подстановка обычно и объясняет, почему условие не сработало: переменная оказалась пустой или не той. Если не совпало ни одно, так и написано — «переход по ветке „иначе“».
Последняя строка — итог: чем запуск обернулся для бота. «Запуск блока 7 с отсрочкой: 2 часа», «запуск блока 7 сразу», «отправка сообщения из условия, бот ждёт ответа», «выход в родительский сценарий», «сценарий завершён». По журналу видно всю цепочку: что проверилось, что сработало и куда бот уйдёт дальше.
Тестовый прогон
В том же окне — «Тестовый прогон». Он запускает сценарий прямо из конструктора, без мессенджера: подписчика и канала нет, есть только переменные, которые вы зададите (по одной в строке, имя=значение).
Тест не умеет делать «понарошку»: запрос уйдёт, строка в списке создастся, оплата спишется, письмо отправится. Конструктор предупреждает об этом списком действий, которые выходят наружу.
Если указать ClientID подписчика, прогон пойдёт от его имени по-настоящему: теги, баллы и сообщения достанутся именно ему.
Приёмы без отладчика
- Блок-«дебагер» после сценария: покажите себе значения ключевых переменных через
[Name] | #{var1} | #{var2}. - Глобальная переменная
g_debug=1— проверяйте её в условиях, чтобы временно включать диагностические сообщения. - Список «Лог» — каждое выполнение сценария новой строкой в списке.
- Чат с клиентами — там видно историю сообщений и ответы бота.
Частые ошибки
- Сценарий действий не сохранён — изменения не применятся. Каждый сценарий сохраняется отдельно от блока.
#{var}в блоке пустое — переменная присваивается в сценарии «После отправки», а используется в этом же блоке. Перенесите присвоение в «До отправки» предыдущего блока.- Действия идут «не в том порядке» — пересмотрите последовательность. Операции выполняются строго сверху вниз.
- Один сценарий правится в нескольких местах — учтите, что он используется ещё где-то. Изменения подействуют везде.
- Тяжёлый HTTP-запрос блокирует диалог — клиент видит «бот думает» долго. Выносите долгие запросы в «После отправки» и используйте отложенный показ результата следующим шагом цепочки.
Что дальше
Подробные статьи по каждому действию: