Telegram

· 4 мин чтения · admin

Создание бота через BotFather

Для подключения Telegram к Hermes Agent создайте бота через @BotFather:

  • Откройте @BotFather и отправьте /newbot
  • Задайте имя и уникальный username, заканчивающийся на bot
  • BotFather выдаст токен вида 123456789:ABCdefGhIJKlmNoPQRsTUVwxyz
  • Сохраните токен — он понадобится для настройки Hermes

Настройка приватности для групп

По умолчанию бот не видит сообщения в группах. Для работы в группах:

  • Отправьте /mybots в BotFather, выберите бота
  • Перейдите в Bot Settings → Group Privacy и отключите приватность
  • Важно: после смены настройки удалите бота из группы и добавьте заново

Настройка Gateway

Интерактивная настройка

Запустите hermes setup и выберите Telegram. Система запросит токен и ваш User ID (узнать можно через @userinfobot).

Ручная конфигурация

Добавьте переменные в ~/.hermes/.env:

  • TELEGRAM_BOT_TOKEN=ваш_токен — токен от BotFather
  • TELEGRAM_ALLOWED_USERS=ваш_id — числовой Telegram ID

Или в ~/.hermes/config.yaml:

  • platforms.telegram.bot_token
  • platforms.telegram.allowed_users — список ID через запятую

Запуск Gateway

Запустите hermes gateway для активации long-polling соединения. Бот начнёт принимать и обрабатывать сообщения.

Групповые чаты и триггеры

В группах Hermes отвечает только при упоминании. Настройка:

  • @botname — стандартное упоминание
  • mention_patterns в конфиге — кастомные шаблоны триггеров
  • telegram.allowed_groups — allowlist групп

Форум-темы (Topics)

Hermes поддерживает форум-темы в супергруппах. Каждая тема — отдельный диалог:

  • Привязка скиллов к темам через telegram.topic_skills
  • Кастомные промпты через telegram.channel_prompts
  • Мульти-сессии в ЛС: команда /topic создаёт изолированные беседы

Голосовые сообщения

Hermes обрабатывает голос в обоих направлениях:

  • Входящие (STT): транскрипция через faster-whisper или Groq API
  • Исходящие (TTS): ответ голосом через Edge TTS. Требуется ffmpeg

Реакции и вебхуки

Включите telegram.reactions: true для реакций: 👁 при обработке, ✅ при успехе, ❌ при ошибке. Для продакшена можно переключиться на webhook-режим через TELEGRAM_WEBHOOK_URL и TELEGRAM_WEBHOOK_PORT.

Slash-команды в Gateway

Доступны в любом чате с ботом:

  • /approve — одобрить ожидающую команду (gateway approval mode)
  • /deny — отклонить ожидающую команду
  • /sethome — установить текущий чат как домашний канал
  • /platforms (/gateway) — показать статус подключения всех платформ
  • /restart — перезапустить gateway
  • /update — обновить Hermes до последней версии

DM Pairing

Управление авторизацией DM (личных сообщений):

# Посмотреть текущие привязки
hermes pairing list

# Одобрить пользователя (разрешить DM)
hermes pairing approve USER_ID

# Отозвать доступ
hermes pairing revoke USER_ID

При включённом pairing-mode только одобренные пользователи могут писать боту в ЛС. Это дополнительный уровень безопасности поверх TELEGRAM_ALLOWED_USERS.

Отправка сообщений и каналы

Для публикации в Telegram-каналах используйте только send_message — это единственный поддерживаемый способ. Не используйте fallback-цепочки с curl/bot token — они приводят к ошибкам при ротации токенов.

Форматирование: MarkdownV2 используется по умолчанию. При отправке через send_message текст форматируется автоматически.

Медиа и вложения

Отправка медиафайлов в ответах агента: используйте MEDIA:/path/to/file в тексте ответа — Hermes автоматически отправит файл.

  • Максимум текста: 4096 символов на сообщение
  • Размер вложения: до 100 МБ (ограничение Telegram Bot API)
  • Форматы: фото, видео, документы, голосовые, стикеры, анимации

Telegram Business API (Chat Automation)

⚠️ Не поддерживается.

Telegram (май 2026) ввёл «Chat Automation» — функцию, позволяющую боту отвечать от имени пользователя в ЛС. Для работы требуется параметр business_connection_id во всех API-вызовах.

В Hermes нет обработки business_connection_id — ни на входе (получение сообщений), ни на выходе (отправка ответов). Ответы всегда отправляются как сообщения бота, а не от имени пользователя.

Затронутые области:

  • Входящие бизнес-сообщения могут не доходить до агента
  • Исходящие ответы не содержат business_connection_id
  • Фильтр _should_process_message() не имеет бизнес-логики

Решение потребует изменений кода в gateway/platforms/telegram.py.

Безопасность

  • Всегда указывайте TELEGRAM_ALLOWED_USERS — без него бот отклоняет всех
  • Не публикуйте токен. При компрометации — /revoke в BotFather
  • Используйте DM pairing для динамического управления доступом