Discord

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

Создание Discord-приложения

Для работы Hermes Agent с Discord необходимо создать приложение в Discord Developer Portal. Перейдите на https://discord.com/developers/applications и нажмите New Application. Укажите имя бота и примите условия использования.

Далее перейдите в раздел Bot и создайте бота. На этом этапе важно включить три привилегированных Gateway Intent:

  • Message Content Intent — обязательно для работы бота в каналах. Без этого intent бот не получает текст сообщений из каналов сервера и не может на них отвечать. Discord скрывает содержимое всех сообщений, кроме DM, если intent не включён
  • Server Members Intent — нужен для проверки ролей пользователей
  • Presence Intent — отслеживание статусов участников

⚠️ Важно: Message Content Intent — это привилегированный intent. Для ботов на 100+ серверах требуется верификация приложения в Discord. Для ботов на менее чем 100 серверах intent включается мгновенно в разделе Bot → Privileged Gateway Intents.

Получение токена

В разделе Bot Developer Portal нажмите Reset Token и скопируйте полученный токен. Этот токен используется в переменной окружения DISCORD_BOT_TOKEN. Токен необходимо хранить в секрете — никогда не публикуйте его в открытых репозиториях.

Добавьте токен в файл ~/.hermes/.env:

DISCORD_BOT_TOKEN=your_token_here

Настройка Gateway

Hermes Agent подключается к Discord через Discord Gateway — WebSocket-соединение для получения событий в реальном времени. Для запуска шлюза выполните:

hermes gateway

При первом запуске можно использовать интерактивную настройку:

hermes setup discord

Эта команда проведёт через все шаги: ввод токена, выбор сервера, настройку каналов и прав доступа. Альтернативно настройте вручную, добавив переменные в ~/.hermes/.env:

  • DISCORD_BOT_TOKEN — токен бота
  • DISCORD_ALLOWED_USERS — список ID пользователей через запятую, которым разрешено взаимодействие с ботом
  • DISCORD_HOME_CHANNEL — ID канала для proactive-сообщений (напоминания, cron-задачи)

Event Subscriptions (события)

Discord Gateway использует подписки на события для получения обновлений. Hermes Agent автоматически подписывается на необходимые события, но важно понимать их назначение:

  • MESSAGE_CREATE — получение новых сообщений в каналах и DM
  • MESSAGE_UPDATE — редактирование сообщений (для контекста)
  • INTERACTION_CREATE — обработка slash-команд
  • VOICE_STATE_UPDATE — подключение/отключение от голосовых каналов
  • GUILD_MEMBER_ADD — присоединение новых участников (требует Server Members Intent)

Аналогия со Slack: В Slack бот должен подписаться на событие message.channels для получения сообщений из публичных каналов (без этого бот работает только в DM). В Discord аналогичная задача решается через Message Content Intent — без него бот не получает содержимое сообщений из каналов сервера.

Приглашение бота на сервер

Для генерации ссылки-приглашения перейдите в раздел Installation вашего приложения или используйте URL вручную. Боту необходимы следующие разрешения:

  • Send Messages и Read Message History — для обмена сообщениями
  • Attach Files и Embed Links — для отправки медиа и ссылок
  • Use Slash Commands — для регистрации команд
  • Connect и Speak — для голосовых каналов
  • Mention Everyone (опционально) — для упоминаний

Скопируйте ссылку и откройте в браузере, чтобы добавить бота на нужный сервер.

Работа с каналами

Hermes Agent автоматически обнаруживает каналы сервера, в которых у бота есть доступ. Для текстовых каналов бот может отправлять и получать сообщения, для форум-каналов (тип 15) автоматически создаются треды при отправке.

Домашний канал — это канал, куда бот отправляет proactive-уведомления. Установите его командой /sethome в нужном канале или вручную через переменную DISCORD_HOME_CHANNEL.

Для управления доступом по ролям используйте DISCORD_ALLOWED_ROLES — список ID ролей через запятую. Любой участник с одной из указанных ролей получит доступ к боту.

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

Для программной отправки сообщений в каналы используется инструмент send_message. Это основной способ публикации контента из cron-задач, вебхуков и автоматизаций:

send_message(channel_id="1234567890", text="Текст сообщения")

Инструмент поддерживает отправку:

  • Текстовых сообщений (до 2000 символов — лимит Discord)
  • Файлов и вложений (до 25 МБ на файл, до 10 файлов за сообщение)
  • Embed-сообщений (для форматированного контента)
  • Сообщений в треды и форум-каналы

⚠️ Важно: send_message работает только через запущенный gateway. Убедитесь, что hermes gateway запущен и бот имеет доступ к целевому каналу.

DM Pairing (приватные сообщения)

Hermes Agent поддерживает работу через личные сообщения (DM) в Discord. Для управления DM-доступом используйте:

  • hermes pairing list — список авторизованных пользователей
  • hermes pairing approve USER_ID — одобрить DM-доступ
  • hermes pairing revoke USER_ID — отозвать DM-доступ

По умолчанию бот отвечает в DM всем пользователям из DISCORD_ALLOWED_USERS. Для канальных взаимодействий бот должен быть явно добавлен на сервер с нужными правами.

Slash-команды

При работе через Discord доступны следующие slash-команды (вводятся через / в чате):

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

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

Hermes Agent поддерживает работу с голосовыми сообщениями в Discord:

  • Входящие голосовые сообщения автоматически транскрибируются через STT-провайдер: локальный faster-whisper, Groq Whisper или OpenAI Whisper
  • Text-to-Speech — команда /voice tts позволяет боту отправлять голосовые ответы
  • Голосовые каналы — бот может подключаться к голосовому каналу, слушать речь и отвечать голосом

Лимиты вложений

Discord накладывает ограничения на отправку файлов:

  • Максимальный размер файла: 25 МБ (без Nitro), 50 МБ (с Nitro Basic), 500 МБ (с Nitro)
  • Количество файлов: до 10 файлов за одно сообщение
  • Длина сообщения: до 2000 символов. Сообщения длиннее автоматически разбиваются или отправляются как файл
  • Embed-лимиты: до 10 embed за сообщение, до 25 полей в embed, до 6000 символов суммарно

Деплой на Heroku / Render

При деплое Hermes Agent на Heroku или Render с Discord gateway учтите:

  • Heroku не поддерживает длинные WebSocket-соединения — Heroku dyno автоматически перезапускается каждые 24 часа и при бездействии (free/hobby tier). Discord Gateway требует постоянного соединения. Используйте worker dyno (не web) и настройте пинг для поддержания активности
  • Render Free Tier — сервис «засыпает» через 15 минут бездействия. Для Discord-бота выбирайте Background Worker (не Web Service) с платным тарифом или настройте UptimeRobot для пинга
  • Переменные окружения — задайте DISCORD_BOT_TOKEN, DISCORD_ALLOWED_USERS и DISCORD_HOME_CHANNEL через панель управления платформы (Settings → Environment Variables)
  • Healthcheck — Discord Gateway не имеет HTTP-endpoint. Heroku/Render ожидают HTTP healthcheck для web-сервисов. Используйте worker тип сервиса, а не web
  • Лимиты памяти: Heroku Eco/Basic — 512 МБ. Hermes с gateway и инструментами может потребовать до 1 ГБ. Мониторьте через hermes status
  • Persistent storage: Heroku и Render не имеют постоянного хранилища. Сессии, навыки и логи теряются при перезапуске. Используйте внешнее хранилище (S3, PostgreSQL) или монтируйте persistent disk на Render