Telegram-бот

Платформа позволяет подключить Telegram-бота к вашим AI-сценариям. Пользователи смогут общаться с ботом в Telegram, а платформа будет обрабатывать сообщения через заданные воркфлоу.

Обзор

Раздел Интеграции > вкладка Telegram отображает все созданные боты в виде карточек. Каждая карточка содержит:

• Название бота и его юзернейм в Telegram
• Текущий статус (активен / остановлен)
• Режим авторизации и контекста
• Список привязанных команд
• Список разрешённых пользователей (для режима Whitelist)

Создание бота

1. Нажмите карточку Добавить Telegram Bot.
2. Заполните форму:

Поле	Описание
Bot Name	Отображаемое имя бота в платформе
Bot Token	Токен бота, полученный у @BotFather в Telegram
Project	Проект, к которому привязан бот
Default Workflow	Сценарий по умолчанию (необязательно)

3. Нажмите 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 — см. Auto Greeting
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 бот на команду /start не отправляет статичный текст, а запускает Default Workflow со служебным сообщением «пользователь начал разговор — поприветствуй его согласно инструкциям». Текст приветствия генерирует LLM, поэтому задаётся он в системном промпте агента внутри воркфлоу: опишите там тон, язык и что бот должен предложить пользователю.

Чтобы приветствие сработало, нужны три условия: включённый переключатель, заданный Default Workflow (без него бот ответит «No workflow configured») и команда именно /start — на первое обычное сообщение приветствие не генерируется, оно уходит в воркфлоу как обычный ввод. При выключенной настройке бот отвечает на /start статичной подсказкой.

Приветствие отправляется один раз на сессию: на каждого участника в режиме Per user, один раз на чат в режиме Per chat, в личных чатах — один раз на пользователя. Повторные /start не вызывают LLM снова и остаются без ответа — это исключает накручивание стоимости и спам приветствиями в больших чатах. Отметка «уже поприветствован» не сбрасывается ни сменой сценария, ни выключением и повторным включением настройки, поэтому для проверки приветствия отправьте /start с другого Telegram-аккаунта.

Приветствие не приходит?

Проверьте по порядку: включён ли переключатель, задан ли Default Workflow и опубликован ли он, не отправлял ли этот аккаунт /start раньше. Учтите также, что до приветствия срабатывают остальные проверки — в режиме Whitelist пользователь должен быть в списке разрешённых, а при включённом Ask for Phone сначала нужно поделиться номером телефона.

Форумы (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:

1. Откройте @BotFather в Telegram.
2. /mybots → выберите бота → Bot Settings → Group Privacy → Turn off.
3. Заново добавьте бота в группу (или удалите и добавьте), чтобы изменения применились.

Внимание

В режиме All messages с отключённым privacy mode бот видит каждое сообщение в чате. Каждое сообщение проходит через LLM-вызов — учитывайте это при оценке стоимости работы бота в активных группах.

Совет

Если бот должен реагировать только на конкретные команды (/help, /order) и не вмешиваться в обычный разговор — оставьте Group Mode = Mentions only. Команды с явным @botname (например, /help@mybot) всё равно будут обработаны, а команды, адресованные другим ботам (/help@otherbot), будут проигнорированы.

Привязка сценариев

Каждый бот может быть связан с несколькими воркфлоу через команды Telegram.

1. Нажмите + Command на карточке бота.
2. Выберите проект и воркфлоу.
3. Укажите команду — текст, по которому пользователь активирует сценарий (например, help, start).
4. Добавьте описание (необязательно).

Привязанные команды отображаются на карточке бота в виде тегов с префиксом /.

Совет

Если задан Default Workflow, он будет использоваться для всех сообщений, которые не соответствуют ни одной привязанной команде.

Управление пользователями

В режиме Whitelist можно управлять списком разрешённых пользователей:

• Добавить — нажмите + User и укажите Telegram User ID и отображаемое имя (необязательно).
• Удалить — нажмите крестик рядом с тегом пользователя на карточке.

Отправка сообщений из процессов

Бот умеет не только принимать сообщения, но и отправлять их по команде из процесса: нода «Сообщение в Telegram» (категория «Интеграции» в палитре редактора) шлёт текст и изображения в указанный чат от имени одного из ботов проекта. Типичные сценарии — уведомление менеджера о новой заявке, отчёт по расписанию, ответ пользователю в чат, из которого пришла заявка.

Для отправки боту интеграции не нужно быть включённой: нужен только токен. Выключенная интеграция в списке помечена как «остановлен», но выбрать её можно.

Настройки ноды

Поле	Что указать
Бот	Один из ботов проекта. Если список пуст, сначала создайте бота.
Chat ID	Куда отправлять: числовой идентификатор чата (у групп и каналов он отрицательный) или @username публичного канала. Поддерживает переменные, например {{input.chat_id}}.
Текст	Текст сообщения, по умолчанию {{lastOutput}} — результат предыдущей ноды. Поддерживает переменные. Текст длиннее 4096 символов уходит несколькими сообщениями, разрез по переносу строки.
Форматирование	Без форматирования, Markdown, MarkdownV2 или HTML — так же, как parse_mode в Bot API.
Изображения	До 10 публичных http(s)-ссылок, каждая поддерживает переменные. Одна ссылка уходит как фото, несколько — одним альбомом. Изображения отправляются после текста.

Нужны текст или хотя бы одно изображение; пустая нода не сохранит сценарий без предупреждения на канвасе.

Как узнать Chat ID

• Личный чат — это Telegram User ID пользователя. Его покажет любой бот вроде @userinfobot, или возьмите его из списка пользователей бота в режиме Whitelist. Пользователь должен хотя бы раз написать боту, иначе Telegram ответит, что бот не может писать в этот чат.
• Группа или канал — добавьте бота в группу, напишите в ней любое сообщение и посмотрите chat.id через https://api.telegram.org/bot<токен>/getUpdates. Для каналов бот должен быть администратором.
• Чат, из которого пришло сообщение — если процесс запущен этим же ботом, идентификатор чата лежит во входных данных процесса; подставьте его в поле Chat ID через переменные.

Форматирование

Выбирайте Markdown или HTML только когда текст действительно написан в этом формате. Любой неэкранированный *, _, < в тексте — например, в ответе языковой модели, которую не просили писать HTML — приведёт к ошибке ParseModeError, и сообщение не уйдёт. Если текст приходит от агента, безопаснее оставить «Без форматирования» или явно попросить модель отвечать в нужной разметке.

Форматированный текст длиннее 4096 символов нода не режет, а отклоняет целиком: разрез мог бы пройти внутри тега. Обычный текст режется без ограничений.

Результат и ошибки

У ноды один выход. В результате доступны success, messageIds (идентификаторы отправленных сообщений), chatId и botId; дальше по процессу их можно использовать как {{<id ноды>.success}}.

При сбое нода не останавливает процесс: она возвращает success: false, errorType и текст ошибки, а процесс идёт дальше. Если после неудачной отправки нужно свернуть на другую ветку, поставьте следом ноду Если/Иначе с условием по success.

errorType	Причина
ConfigurationError	Не выбран бот или Chat ID пуст после подстановки переменных.
ValidationError	Нет ни текста, ни изображений; больше 10 изображений; форматированный текст длиннее 4096 символов.
NotFoundError	Бот удалён или принадлежит другому проекту.
ForbiddenError	Пользователь заблокировал бота, бота удалили из группы или он не администратор канала.
BadRequestError	Telegram отклонил запрос: чата с таким ID нет, изображение не скачивается по ссылке. В тексте ошибки — ответ Telegram.
ParseModeError	Разметка не разобрана, см. Форматирование.
RateLimitError	Превышен лимит Telegram на отправку; повторите позже.
SendInProgress	Платформа не дождалась ответа, но отправка продолжается; сообщение, скорее всего, дойдёт. Повторный запуск того же шага не создаст дубликат.
UpstreamUnavailableError	Telegram недоступен.

Если текст ушёл, а изображение нет, в messageIds будут идентификаторы уже отправленных сообщений.

Запуск и остановка

Переключатель в правом верхнем углу карточки позволяет:

• Включить — бот начинает принимать и обрабатывать сообщения.
• Выключить — бот перестаёт реагировать на сообщения.

Выключенный бот по-прежнему отправляет сообщения из процессов через ноду «Сообщение в Telegram»: переключатель управляет только приёмом входящих.

Редактирование и удаление

• Редактировать — кликните на карточку бота, откроется модальное окно с настройками.
• Удалить — нажмите кнопку удаления на карточке и подтвердите действие.

Внимание

Удаление бота отвяжет все привязанные сценарии и удалит список разрешённых пользователей. Это действие нельзя отменить.

Подробнее

Для использования голосовых сообщений в Telegram-боте необходимо подключить аудио-провайдеры (STT и TTS).