Начало работы
TGBot позволяет создать Telegram-бота без написания кода. Вы собираете простые «кирпичики» на визуальном холсте, соединяете их между собой, и платформа запускает бота через вебхук. Весь процесс занимает несколько минут.
- Создайте бота в Telegram через @BotFather и скопируйте его токен.
- Откройте Кабинет, нажмите Новый бот, вставьте токен и сохраните бота.
- Нажмите Set Webhook на странице бота — это подключит бота к платформе, и Telegram начнёт пересылать сюда все обновления.
- Создайте первый сценарий: добавьте сообщение /start, затем прикрепите к нему сообщения, условия и действия.
Панель инструментов и холст сценария появляются только после нажатия Set Webhook. До этого на странице отображаются карточки Set Webhook и Настройки бота.
Холст сценария
На странице каждого бота есть визуальный холст с вкладками сценариев сверху. Сценарий — это группа
узлов, которая начинается с корневого элемента (обычно команды вроде /start или /help).
Элементы добавляются с панели инструментов над холстом:
- Добавить сообщение — сообщение, которое бот отправляет пользователю.
- Добавить условие — точка ветвления диалога.
- Добавить ожидание ввода — приостанавливает сценарий и ждёт определённого типа ввода.
- Добавить сохранение данных — молча сохраняет данные пользователя в базу.
- Новый сценарий — создаёт новую вкладку сценария (новую корневую команду).
- Добавить сценарий — шаг, который переводит пользователя из одного сценария в другой.
Кнопка + под любым выходом открывает тот же выбор с дополнительными типами шагов, включая Действие в чате, Получить данные события и Публикация в канал.
Каждый элемент — это узел на холсте. Дочерний элемент выполняется после родительского: например, сообщение с инлайн-кнопкой ведёт к сообщению, привязанному к этой кнопке; условие ведёт к ветке истина или ложь; ожидание ввода ведёт к следующему шагу, как только ожидаемый ввод получен.
Сообщение
Сообщение — это текст, который отправляет бот. Это самый частый элемент на холсте. С его помощью можно поприветствовать пользователя, показать меню, что-то объяснить или задать вопрос.
Плейсхолдеры
Подставляйте сохранённые значения в сообщение с помощью фигурных скобок. Значения берутся из источника, который вы выбираете в Настройки бота → Плейсхолдеры сообщений — укажите базу данных и включите нужные столбцы. Плейсхолдеры всегда используются с префиксом:
{ $user->city }— значение из сохранённых пользователей этого бота.{ $event->description }— значение из последнего события отправителя.
В редакторе сообщения откройте выпадающий список Вставить плейсхолдер, чтобы добавить его — он подставит правильную форму для выбранного источника, например:
Здравствуйте, { $user->first_name }! Ваш город: { $user->city }.
У каждого плейсхолдера можно указать запасное значение, которое подставится, когда
сохранённого значения нет. Оно отделяется вертикальной чертой |; кавычки вокруг него необязательны:
Город события: { $event->city | 'н/д' }
Ваш возраст: { $user->age_category | 'не указан' }Запасное значение работает везде, где подставляются плейсхолдеры: в тексте сообщений, в подписях и URL инлайн-кнопок и в URL картинки ответа «Отправить картинку» (вместо того чтобы скрыть кнопку или картинку, бот использует запасное значение).
Инлайн-кнопки
Сообщение может нести клавиатуру. Инлайн-кнопки отображаются сразу под сообщением. У каждой кнопки
есть значение callback_data (внутренний идентификатор) или URL:
[ Каталог ] [ Корзина ] [ Контакты ]
Чтобы связать кнопку со следующим шагом, создайте дочернее сообщение, у которого ключ кнопки равен
значению callback_data. Когда пользователь нажимает кнопку, бот выполняет это дочернее сообщение.
К каждой кнопке одного сообщения можно привязать отдельную ветку.
Обычная клавиатура
Обычная (reply) клавиатура заменяет поле ввода пользователя кнопками. Нажатие кнопки отправляет её
текст как обычное сообщение. Следующим шагом становится сообщение, у которого keyboard_key совпадает с
этим текстом. Клавиатура поддерживает кнопку Поделиться геопозицией. Чтобы скрыть клавиатуру после выбора,
включите флаг убрать клавиатуру у сообщения.
Условие
Условие — это точка ветвления. Оно смотрит на сохранённые данные о пользователе и направляет диалог в одну из двух веток: истина или ложь. На холсте условие изображается ромбом.
Доступные типы условий:
- Пользователь зарегистрирован — истина, если для этого бота сохранён профиль пользователя.
- Геопозиция пользователя обязательна — истина, если геопозиция была отправлена.
- Обязательные поля пользователя заполнены — выберите один или несколько столбцов; истина, когда в каждом столбце есть значение.
- Пользователь выбрал значение — выберите столбец и значение (например возрастную категорию
25-30); истина, когда сохранённое значение совпадает. Удобно после нажатия кнопки в вопросе.
Каждая ветка либо переходит в существующий сценарий, либо хранит свои шаги инлайн внутри текущего сценария. Выбор делается переключателями в диалоге условия. Условие можно привязать к конкретной инлайн-кнопке — тогда каждая кнопка сообщения ветвит диалог независимо.
Ожидание ввода
Элемент Ожидание ввода приостанавливает сценарий и ждёт конкретный тип ввода пользователя. Когда ожидаемый ввод получен, сценарий продолжается и выполняется следующий элемент. На холсте он изображается шестиугольником.
Поддерживаемые типы ввода:
- Текст — любое текстовое сообщение. Можно задать максимум букв (по умолчанию 255).
- URL — текст, который должен быть корректной
http(s)-ссылкой. - Геопозиция — отправленная геопозиция.
- Кнопка — нажатие на инлайн- или обычную кнопку клавиатуры.
- Файл — любой медиафайл: фото, документ, видео, аудио, голосовое, стикер и другие.
- Дата — текст, интерпретируемый как дата.
- Число — текст, интерпретируемый как число.
Ожидание ввода всегда продолжается со следующим элементом, прикреплённым к нему. Если пользователь отправил что-то, не соответствующее ожидаемому типу, бот продолжает ждать.
Для шага Ожидание ввода, который сохраняет ввод в столбец, можно также задать
значение по умолчанию. Если в выбранном столбце ещё нет сохранённого значения, бот запишет
значение по умолчанию молча и продолжит без вопроса; иначе он ждёт ввод как обычно. Удобно для автоматического
заполнения поля (например, страна = Eesti).
Сохранение данных
Сохранение данных молча записывает информацию о пользователе, не показывая сообщения. В одном диалоге объединены два режима:
- Сохранить данные пользователя — записывает профиль Telegram (имя, username, язык) и любую отправленную геопозицию в сохранённых пользователей бота. При желании можно записать в таблицу событий.
- Сохранить значение — когда пользователь нажимает настроенную инлайн-кнопку, её значение записывается в выбранный столбец сохранённых пользователей (или событий). Можно сопоставить целую клавиатуру, чтобы значение каждой кнопки попадало в свой столбец.
Выбираемые столбцы — это те, что включены в Настройки бота → Плейсхолдеры сообщений
(например first_name, city, country, gender,
age_category). Значения, сохранённые таким образом, становятся доступны как плейсхолдеры,
например { $user->city }, в любых ваших сообщениях, а также как источник для условий.
Сценарий
Сценарий — это законченный, переиспользуемый поток узлов, начинающийся с корневого элемента. Сценарии
показаны вкладками вверху холста и называются по своей корневой команде (например /start, /help).
- Новый сценарий — создаёт новую вкладку из имени команды или кнопки.
- Добавить сценарий — размещает шаг, который переводит пользователя в другой сценарий. На холсте он изображается пунктирной янтарной «пилюлей». Так можно переиспользовать логику между сценариями (например общий сценарий регистрации, доступный из любой команды).
Команды — классические точки входа: сообщение с ключом кнопки /start выполняется, когда пользователь
нажимает Start в Telegram. Команды должны выглядеть как /команда (буквы, цифры и подчёркивания).
Нажмите на пилюлю перехода в сценарий на холсте, чтобы открыть сценарий, на который она указывает, — нужная вкладка выберется автоматически, и не придётся искать её среди остальных вкладок.
Публикация в канал
Шаг Публикация в канал отправляет сообщение — с необязательным фото и инлайн-кнопками — в один из Telegram-каналов бота. После публикации сценарий продолжается со следующего шага, привязанного к этому шагу, — уже в исходном чате.
Добавление канала
Откройте Настройки бота → Каналы → Управление и введите @username канала или его
числовой chat ID. Бот должен уже быть администратором канала — платформа проверяет это в
Telegram перед сохранением, поэтому сначала назначьте бота администратором канала.
Добавление шага
Нажмите + под любым выходом и выберите Публикация в канал в открывшемся списке, укажите один из сохранённых каналов и напишите сообщение для публикации. На холсте шаг изображается узлом с розовой рамкой и значком канала.
Частый приём: разместите инлайн-кнопку Опубликовать на сообщении с превью или сводкой и прикрепите к ней шаг «Публикация в канал» — нажатие кнопки опубликует готовый контент в канале.
Вебхук и запуск
Платформа получает обновления Telegram через вебхук. Нажмите Set Webhook, чтобы зарегистрировать URL вашего бота в Telegram. После этого каждое обновление доставляется на адрес:
POST /telegram/webhook/{botId}Когда приходит обновление, платформа читает сообщение или нажатие кнопки, проходит по сценарию от соответствующего корневого элемента, вычисляет условия, подставляет плейсхолдеры и отправляет ответы. Панель Входящие сообщения (открывается с панели инструментов) показывает последние запросы, позволяет посмотреть, какой сценарий они запустили, и повторить запрос для отладки бота.
Сохранённые пользователи
Каждый, кто взаимодействует с вашим ботом и был записан шагом Сохранение данных, становится сохранённым пользователем этого бота. Сохранённые пользователи привязаны к конкретному боту, поэтому один и тот же аккаунт Telegram может иметь разные данные в разных ботах. Их можно посмотреть в карточке Настройки бота и при необходимости удалить всех разом.
Вопросы и ответы
Бот ничего не отвечает на сообщение.
Убедитесь, что вы нажали Set Webhook, бот Активен и к сценарию /start
прикреплено хотя бы одно сообщение.
Как запомнить ответ пользователя?
Используйте Сообщение с кнопками, затем Ожидание ввода (Кнопка), затем Сохранение данных, чтобы записать нажатое значение в столбец, и Условие, чтобы ветвить диалог по нему.
Как работают плейсхолдеры?
Выберите источник и включите столбцы в Настройки бота → Плейсхолдеры сообщений, сохраните
данные пользователя, а затем вставьте плейсхолдер из выпадающего списка редактора сообщения (например
{ $user->city }). Платформа заменит его сохранённым значением. Когда значения нет, укажите запасное
после вертикальной черты: { $user->city | 'неизвестно' } покажет неизвестно.
Можно ли переиспользовать одни и те же шаги в разных командах?
Да. Вынесите общие шаги в отдельный сценарий и используйте шаг Добавить сценарий, чтобы переходить в него из любой команды.
Может ли бот публиковать сообщения в Telegram-канал?
Да. Назначьте бота администратором канала, добавьте канал в Настройки бота → Каналы, а затем прикрепите шаг Публикация в канал там, где нужна публикация (например, за кнопкой «Опубликовать»).