Гайд - Флоу

Флоу: собираем воронку бота визуально

Кликают все - депозитят после диалога. Флоу - визуальный конструктор диалога бота, который запускается сразу после клика по вашей рекламе: поприветствовать, квалифицировать, довести до оффера и отправить события конверсий в рекламные площадки и трекер, пока пользователь ещё печатает. Именно флоу превращает Telegram-бота в настоящую воронку, а не в статичный лендинг.

Из чего строится флоу

  • START - вход в любой флоу. Всегда есть, не удаляется, входящих связей не принимает.
  • «Сообщение» - отправляет текст (работает Telegram-HTML вроде <b>), опционально медиа (фото, видео, GIF или документ), инлайн-кнопки и вариант с текстовым вводом. Узел с callback-кнопками или текстовым вводом ставит флоу на паузу и ждёт пользователя; кнопки могут быть и просто URL-ссылками.
  • «Условие» - ветвление true/false по полю контекста; операторы: равно, не равно, содержит, не содержит, больше, меньше, regex, существует.
  • «S2S-запрос» - отправляет POST-ом JSON с контекстом клика и собранными ответами на ваш сервер; ответ сохраняется под идентификатором узла и доступен в следующих условиях и сообщениях.
  • «Триггер события» - фиксирует настоящую конверсию (старт бота, лид, регистрация, депозит, FTD, покупка, custom 1-8 и другие), опционально с value и currency - события идут в Meta CAPI. Это же событие запускает постбэки и пуши по событию.

Сборка и активация

  1. На странице «Флоу» нажмите «Новая цепочка»; бота можно привязать сразу или позже в редакторе.
  2. Добавляйте узлы на канвас и соединяйте их связями. Вставляйте данные пользователя где угодно переменными {{ }} - пикер контекста подскажет, что доступно. Редактор сохраняет изменения автоматически по ходу работы (следите за индикатором статуса в шапке), а Cmd/Ctrl+Z отменяет последнее действие - кнопка повтора стоит рядом.
  3. Держите панель «Проверка» чистой: ошибки вроде «В сообщении нет текста», «У условия нет исходящей ветки», «Для S2S-запроса нужен корректный http(s)-URL» или «В потоке есть цикл» блокируют активацию.
  4. Назначьте активного бота в шапке редактора.
  5. Жмите «Активировать». Активный флоу - только для чтения: «Деактивировать», отредактировать, активировать снова.
Канвас редактора флоу со связанными узламиКанвас редактора флоу со связанными узлами

Тест в симуляторе

Кнопка «Тест» открывает Симулятор - песочницу: реальные сообщения не отправляются, списаний нет. Задайте стартовый контекст (имя, username, гео, sub1/sub2, статус - или вставьте raw JSON), запустите флоу, прокликайте кнопки в превью чата, отвечайте текстом, подставляйте мок-ответы S2S и следите за панелью переменных и таймлайном шагов. Ломаные ветки ловятся здесь, а не на платном трафике.

И симулятор, и рабочий рантайм ограничивают прогон 100 шагами. До прода цикл не доходит: флоу со связью, которая замыкается сама на себя, не сохранится и не активируется - панель «Проверка» покажет «В потоке есть цикл». Потолок в 100 шагов - страховка: он всё ещё может сработать в симуляторе на несохранённом циклическом графе или на цепочке длиннее 100 узлов.

Как это работает в проде

Пользователь пишет боту - активный флоу стартует выполнение. /start всегда перезапускает диалог с начала, даже посреди разговора. Шаги обрабатываются фоновыми воркерами; узел «Сообщение» с кнопками или текстовым вводом переводит выполнение в состояние «Ожидание ответа», пока пользователь не отреагирует, - дальше флоу идёт по подходящей ветке. Узлы «Триггер события» срабатывают в момент, когда пользователь до них дошёл. Прогон, который выходит за лимит в 100 шагов, останавливается и попадает в историю ниже со статусом «Ошибка».

История выполнений

«История выполнений» показывает каждый прогон: флоу, Telegram-пользователь, статус («Выполняется», «Ожидание ответа», «Завершено», «Ошибка»), число шагов, длительность, текст ошибки и время старта - с фильтрами по статусу и пагинацией. Первое место, куда смотреть, когда «бот не отвечает».

Частые грабли

  • Флоу-черновик никому не отвечает. Для активации нужны привязанный бот, хотя бы один узел после START и ноль ошибок валидации.
  • Активным на бота может быть только один флоу. Попытка активировать второй блокируется сразу же с ошибкой, которая просит сначала деактивировать первый - это не тихая гонка, где лишний флоу просто игнорируется.
  • С медиа текст становится подписью с лимитом Telegram в 1024 символа - лишнее молча обрезается. Обычное текстовое сообщение - до 4096.
  • Кнопки-ссылки (URL) не ставят флоу на паузу: тап уходит в браузер, бот его не видит - флоу сразу идёт дальше.
  • Удаление или отвязка бота у активного флоу не оставляет его работать вслепую: флоу автоматически откатывается в черновик и перестаёт отвечать, пока вы заново не привяжете бота и не активируете флоу.
  • Удаление флоу безвозвратно стирает узлы, связи и историю выполнений.