Telegram-бот
Платформа позволяет подключить Telegram-бота к вашим AI-сценариям. Пользователи смогут общаться с ботом в Telegram, а платформа будет обрабатывать сообщения через заданные воркфлоу.
Обзор
Раздел Интеграции > вкладка Telegram отображает все созданные боты в виде карточек. Каждая карточка содержит:
- Название бота и его юзернейм в Telegram
- Текущий статус (активен / остановлен)
- Режим авторизации и контекста
- Список привязанных команд
- Список разрешённых пользователей (для режима Whitelist)
Создание бота
- Нажмите карточку Добавить Telegram Bot.
- Заполните форму:
| Поле | Описание |
|---|---|
| Bot Name | Отображаемое имя бота в платформе |
| Bot Token | Токен бота, полученный у @BotFather в Telegram |
| Project | Проект, к которому привязан бот |
| Default Workflow | Сценарий по умолчанию (необязательно) |
- Нажмите Create.
Откройте Telegram, найдите @BotFather, отправьте команду /newbot, следуйте инструкциям. BotFather выдаст токен вида 123456789:AAxxxx....
Настройки бота
Режим авторизации (Auth Mode)
Определяет, кто может пользоваться ботом:
- Public — бот доступен всем пользователям Telegram.
- Whitelist — бот доступен только пользователям из списка разрешённых Telegram ID.
При выборе режима Whitelist необходимо указать Telegram User ID разрешённых пользователей. Их можно добавить при создании бота (через запятую или по одному на строку) или позже через кнопку + User на карточке бота.
Режим контекста (Context Mode)
Управляет сохранением истории диалога:
- Per workflow — для каждого привязанного сценария хранится отдельная история разговора.
- Shared — единая история для всех сценариев бота.
- Per workflow + summary — отдельная история для каждого сценария с периодическим суммированием.
Голосовые сообщения (Voice)
- Voice In — принимать голосовые сообщения (распознавание речи STT).
- Voice Out — отвечать голосовыми сообщениями (синтез речи TTS).
- Max Voice (sec) — максимальная длительность голосового сообщения (от 5 до 300 секунд).
Дополнительные настройки
| Настройка | Описание |
|---|---|
| Ask for Phone | Запрашивать номер телефона перед началом работы |
| Auto Greeting | LLM автоматически генерирует приветствие при команде /start |
| Debounce Delay (sec) | Задержка перед обработкой сообщения (0 = отключено). Позволяет объединять несколько последовательных сообщений в одно |
| Max Wait (sec) | Максимальное время ожидания после первого сообщения в серии (5-60 сек). Отображается только при Debounce Delay > 0 |
Функция Debounce полезна, если пользователи отправляют сообщения по частям. Бот подождёт заданное время и обработает все сообщения как одно.
Работа в группах
Telegram-бот можно добавить в групповые чаты (group, supergroup, в т.ч. форумные топики). Поведение в группах настраивается секцией Groups в форме редактирования бота.
Group Mode
Определяет, на что бот реагирует в групповом чате:
| Режим | Поведение |
|---|---|
| Disabled | Бот игнорирует все сообщения из групп. В личных чатах работает как обычно. |
| Mentions only | Бот отвечает только когда к нему обращаются явно: упоминание @botname или ответ (reply) на сообщение бота. Дефолт. |
| All messages | Бот обрабатывает каждое сообщение в группе. Требует выключенного privacy mode у BotFather. |
В режиме Mentions only @botname автоматически вырезается из текста перед передачей в LLM — модель не «отвечает сама себе».
Thread Scope
Доступен при Group Mode ≠ Disabled. Определяет, как изолируются разговоры внутри одной группы:
- Per user — у каждого участника группы свой собственный контекст разговора с ботом. Алиса и Боб в одном чате не пересекаются — рекомендуется для большинства сценариев.
- Per chat — единый общий контекст на всю группу. Бот видит групповой разговор как один монолог. Подходит для сценариев типа «бот-секретарь, ведущий протокол встречи».
Debounce в группах
По умолчанию debounce в группах выключен — иначе сообщения от Алисы и Боба, отправленные подряд, склеились бы в один input для воркфлоу. Если в вашем сценарии это допустимо (например, при Thread Scope = Per chat), включите переключатель Enable debounce in groups.
Inline-кнопки
В режиме Per user к callback_data каждой inline-кнопки автоматически добавляется префикс с ID адресата. Если другой участник нажмёт кнопку, предназначенную для Алисы, бот ответит «This button isn't for you» и не выполнит действие. В режиме Per chat кнопки публичные — нажать может любой.
Запрос телефона в группах
Если включена настройка Ask for Phone, в групповом чате бот не показывает request_contact-клавиатуру (она бы открыла номер всем участникам). Вместо этого бот отвечает коротким сообщением со ссылкой https://t.me/<botname>?start=phone и переводит пользователя в личный чат для безопасного обмена номером.
Whitelist в группах
В режиме Auth Mode = Whitelist неавторизованные пользователи в группе получают тихий отказ — бот не отправляет «Access denied» на каждое сообщение (иначе он быстро упрётся в rate-limit Telegram или будет кикнут). В личных чатах поведение прежнее — пользователь получает явное сообщение.
Auto Greeting в группах
Auto Greeting срабатывает один раз на каждого участника (в Per user-режиме) или один раз на чат (в Per chat-режиме) — повторные /start не вызывают LLM ещё раз. Это исключает накручивание стоимости и спам приветствиями в больших чатах.
Форумы (supergroup с топиками)
Если бот добавлен в супергруппу с включёнными топиками, он автоматически отвечает в тот же топик, откуда пришло сообщение. Ответы не «уходят в General» — message_thread_id пробрасывается во все исходящие методы.
Добавление и удаление бота
- Бот добавлен в группу — отправляет короткое welcome-сообщение с текущим режимом работы. Видно в логах как
bot_added_to_group. - Бот удалён из группы (kick / leave) — все сессии и треды для
(bot, chat)чистятся из БД. В личных чатах блокировка пользователем сессию не удаляет — она восстановится при разблокировке.
Privacy mode у BotFather
По умолчанию Telegram отдаёт боту в группе только:
- команды
/cmdи/cmd@botname; - сообщения с упоминанием
@botname; - ответы (reply) на сообщения бота.
Этого достаточно для режима Mentions only. Для режима All messages нужно отключить privacy mode:
- Откройте @BotFather в Telegram.
/mybots→ выберите бота →Bot Settings→Group Privacy→Turn off.- Заново добавьте бота в группу (или удалите и добавьте), чтобы изменения применились.
В режиме All messages с отключённым privacy mode бот видит каждое сообщение в чате. Каждое сообщение проходит через LLM-вызов — учитывайте это при оценке стоимости работы бота в активных группах.
Если бот должен реагировать только на конкретные команды (/help, /order) и не вмешиваться в обычный разговор — оставьте Group Mode = Mentions only. Команды с явным @botname (например, /help@mybot) всё равно будут обработаны, а команды, адресованные другим ботам (/help@otherbot), будут проигнорированы.
Привязка сценариев
Каждый бот может быть связан с несколькими воркфлоу через команды Telegram.
- Нажмите + Command на карточке бота.
- Выберите проект и воркфлоу.
- Укажите команду — текст, по которому пользователь активирует сценарий (например,
help,start). - Добавьте описание (необязательно).
Привязанные команды отображаются на карточке бота в виде тегов с префиксом /.
Если задан Default Workflow, он будет использоваться для всех сообщений, которые не соответствуют ни одной привязанной команде.
Управление пользователями
В режиме Whitelist можно управлять списком разрешённых пользователей:
- Добавить — нажмите + User и укажите Telegram User ID и отображаемое имя (необязательно).
- Удалить — нажмите крестик рядом с тегом пользователя на карточке.
Запуск и остановка
Переключатель в правом верхнем углу карточки позволяет:
- Включить — бот начинает принимать и обрабатывать сообщения.
- Выключить — бот перестаёт реагировать на сообщения.
Редактирование и удаление
- Редактировать — кликните на карточку бота, откроется модальное окно с настройками.
- Удалить — нажмите кнопку удаления на карточке и подтвердите действие.
Удаление бота отвяжет все привязанные сценарии и удалит список разрешённых пользователей. Это действие нельзя отменить.
Для использования голосовых сообщений в Telegram-боте необходимо подключить аудио-провайдеры (STT и TTS).