Сценарии действий
Сценарий действий — это фоновая логика, которая выполняется до или после показа блока клиенту. Здесь происходят все «невидимые» вещи: расчёты, обращения к 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. Отладка сценария действий
Полезные приёмы:
- Добавьте блок-«дебагер» после сценария: покажите подписчику (или себе через тестовый бот) значения ключевых переменных через
[Name] | #{var1} | #{var2}. - Используйте глобальную переменную
g_debug=1— и проверяйте её в условиях, чтобы временно включать диагностические сообщения. - Сохраняйте логи в список «Лог» — каждое выполнение сценария = новая строка. Сможете найти, что пошло не так.
- Проверяйте через чат с клиентами — там видно историю сообщений и ответы бота.
Частые ошибки
- Сценарий действий не сохранён — изменения не применятся. Каждый сценарий сохраняется отдельно от блока.
#{var}в блоке пустое — переменная присваивается в сценарии «После отправки», а используется в этом же блоке. Перенесите присвоение в «До отправки» предыдущего блока.- Действия идут «не в том порядке» — пересмотрите последовательность. Операции выполняются строго сверху вниз.
- Один сценарий правится в нескольких местах — учтите, что он используется ещё где-то. Изменения подействуют везде.
- Тяжёлый HTTP-запрос блокирует диалог — клиент видит «бот думает» долго. Выносите долгие запросы в «После отправки» и используйте отложенный показ результата следующим шагом цепочки.
Что дальше
Подробные статьи по каждому действию: