Telegram — самая популярная платформа для ботов

Если вы хоть раз пользовались Telegram, вы уже знаете, почему он так хорош для ботов. Он быстрый, работает на любом устройстве и имеет огромную пользовательскую базу. Но вот в чём дело: Telegram — это не просто место, где существуют боты, — это место, где ваш Hermes Agent может по-настоящему раскрыться.

Как только вы подключите Hermes к Telegram, вы получите полнофункционального разговорного бота, с которым можно общаться откуда угодно. Отправьте голосовое сообщение — оно автоматически расшифруется. Попросите отчёт по расписанию — и он приземлится прямо в ваш чат. Вы даже можете добавить бота в групповые чаты, и он будет участвовать в беседе. Он работает с текстом, голосом, изображениями и файлами — всё это на базе надёжной библиотеки python-telegram-bot.

Давайте разберём настройку шаг за шагом.

Шаг 1: Создайте бота с помощью BotFather

Каждый бот в Telegram начинается с API-токена от @BotFather — официального менеджера ботов Telegram. Вот как получить свой:

Откройте Telegram и найдите @BotFather или перейдите по ссылке t.me/BotFather
Отправьте команду /newbot
Выберите отображаемое имя — любое, какое нравится, например «Hermes Agent»
Выберите username — он должен быть уникальным и заканчиваться на bot (например, my_hermes_bot)
BotFather ответит вашим API-токеном, который выглядит так:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Держите токен в секрете! Любой, у кого есть этот токен, может управлять вашим ботом. Если он утёк, немедленно отзовите его командой /revoke в BotFather.

Шаг 2: Настройте бота (необязательно, но стоит того)

Пара быстрых команд BotFather сделают вашего бота аккуратным и профессиональным:

Команда	Назначение
`/setdescription`	Текст «Что умеет этот бот?», который показывается до начала общения
`/setabouttext`	Короткий текст на странице профиля бота
`/setuserpic`	Загрузка аватара для бота
`/setcommands`	Настройка меню команд (кнопка `/` в чате)
`/setprivacy`	Управление доступом бота ко всем сообщениям в группе (см. Шаг 3)

Для /setcommands хороший стартовый набор:

help - Показать справочную информацию
new - Начать новый разговор
sethome - Установить этот чат как домашний канал

Индикатор онлайн/офлайн статуса (необязательно)

У ботов Telegram нет зелёной точки «в сети», как у пользовательских аккаунтов. Ближайший аналог — краткое описание бота — строка под его именем на странице профиля.

Включите status_indicator, и Hermes будет устанавливать это описание в Online при подключении шлюза и в Offline при корректном завершении работы:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Пара замечаний: это описание глобальное (видно всем пользователям), и только корректное завершение работы запишет «Offline» — при жёстком сбое останется последний статус. По умолчанию функция отключена, так как она меняет профиль бота.

Приоритет и лимит меню команд (необязательно)

Hermes автоматически регистрирует своё меню команд при запуске Telegram-шлюза. По умолчанию лимит — 60 команд: этого достаточно для всех встроенных функций и типовых навыков. Если у вас есть команды плагинов, которые должны оставаться видимыми в меню /, вы можете задать для них приоритет:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

prepend: сначала ваши команды, затем стандартные команды Hermes
append: сначала стандартные команды Hermes, затем ваши
replace: использовать только ваш список для определения порядка

Telegram допускает до 100 команд, но большие объёмы данных могут не пройти. Hermes по умолчанию использует 60 для надёжности и ограничивает значения диапазоном 1..100.

Шаг 3: Режим конфиденциальности — критически важен для групп

Вот источник №1 путаницы при использовании ботов в группах: режим конфиденциальности включён по умолчанию.

При включённом режиме конфиденциальности ваш бот видит только:

Сообщения, начинающиеся с /
Ответы на собственные сообщения бота
Служебные сообщения (вход, выход, закрепление)
Сообщения в каналах, где бот является администратором

При выключенном режиме конфиденциальности бот видит каждое сообщение в группе.

Чтобы отключить его:

Напишите @BotFather
Отправьте /mybots
Выберите своего бота
Перейдите в Bot Settings → Group Privacy → Turn off

Важно: После изменения этой настройки необходимо удалить и заново добавить бота в любую группу. Telegram кэширует состояние конфиденциальности при добавлении бота, и оно не обновится, пока бот не будет добавлен заново.

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

Наблюдение за групповыми чатами без автоматических ответов

Хотите, чтобы бот видел сообщения в группе, но отвечал только когда его упоминают? Настройте его так:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

Сообщения без упоминания из разрешённых чатов добавляются в транскрипт сессии как наблюдаемый контекст — но они не запускают агента. Только последующее упоминание @botname фактически вызывает ответ.

Вот и всё! С помощью этих трёх шагов у вас есть полнофункциональный Telegram-бот на базе Hermes Agent. Вперёд — отправьте ему голосовое сообщение, добавьте в группу и посмотрите, как он творит свою магию.