Gateway Adapters (Discord, Slack, Telegram)
Relevant source files
The following files were used as context for generating this wiki page:
Gateway Adapters are specialized modules that bridge external messaging platforms with the Hermes Agent core. These adapters translate platform-specific events—such as Discord messages, Slack actions, or Telegram commands—into a unified MessageEvent format that the GatewayRunner can process. This abstraction allows the agent to maintain consistent behavior, tool access, and session persistence across diverse communication environments.
The system uses a pluggable architecture where each platform (Discord, Slack, Telegram) implements a subclass of a base adapter. These adapters manage connection lifecycles, handle inbound event dispatching, and provide standardized methods for the agent to send text, images, and interactive UI elements back to the user.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:1-20, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md:104-118
Core Architecture and Data Flow
All messaging platform adapters reside in the gateway/platforms/ directory and inherit from a common base class. The GatewayRunner orchestrates these adapters, handling message distribution and user authorization.
Inbound Message Flow
When an external platform sends a message, the following sequence occurs:
- The specific Platform Adapter (e.g.,
TelegramAdapter) receives the raw API event. - The adapter constructs a
SessionSourceand converts the payload into aMessageEvent. - The adapter calls
self.handle_message(event)to pass the data to the central gateway logic. - The gateway authorizes the user, resolves session keys, and initializes an
AIAgentinstance to process the conversation.
Adapter Implementation Requirements
Each built-in adapter must implement a set of required methods to ensure compatibility with the Hermes Gateway. These methods handle the lifecycle of the connection and basic communication capabilities.
Lifecycle and Standard Messaging
| Method | Purpose |
|---|---|
connect() | Establishes the connection to the platform API (e.g., WebSocket or Polling). |
disconnect() | Safely closes connections and cancels pending tasks. |
send(chat_id, text) | Delivers a text message to a specific chat identifier. |
send_typing(chat_id) | Triggers the platform's "typing" indicator. |
send_image(chat_id, url) | Sends an image with an optional caption. |
Sources: gateway/platforms/ADDING_A_PLATFORM.md:112-126
Interactive Features
Adapters for Discord, Slack, and Telegram often support interactive UI elements to enhance the user experience. If the platform supports it, adapters implement specific handlers for buttons and menus.
- send_clarify: Renders multi-choice questions as tappable buttons for the
clarifytool. - send_exec_approval: Displays dangerous-command approval prompts (Once/Always/Deny).
- send_model_picker: Provides an interactive interface for the
/modelcommand.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:132-148
Platform Specifics
Discord Adapter
The Discord adapter handles specific Discord-flavored markdown and media types. It utilizes the discord.py library (or similar) to maintain a persistent connection. It must manage specific Discord requirements such as bot tokens and gateway intents.
Sources: gateway/platforms/discord/__init__.py, gateway/platforms/ADDING_A_PLATFORM.md:150
Slack Adapter
The Slack adapter supports diverse interaction modes, including Socket Mode for real-time updates without public endpoints. It handles Slack's unique "Block Kit" for UI elements and manages action handlers for interactive components.
Sources: gateway/platforms/slack/__init__.py, gateway/platforms/ADDING_A_PLATFORM.md:100-103
Telegram Adapter
The Telegram adapter typically uses long polling or webhooks to receive updates. It implements inline keyboards for choice pickers and supports specific Telegram features like voice messages and document attachments.
Sources: gateway/platforms/telegram/__init__.py, gateway/platforms/ADDING_A_PLATFORM.md:148
Integration and Configuration
Adapters are integrated into the core through a centralized factory and configuration system.
Platform Registration Sequence
- Enum Definition: The platform is added to the
Platformenum ingateway/config.py. - Environment Mapping: Credentials (e.g.,
DISCORD_TOKEN,TELEGRAM_TOKEN) are mapped ingateway/config_env.pyusing_Credand_Home. - Instantiation: The
_instantiate_adapterfunction ingateway/run.pyimports the adapter and verifies dependencies before creation. - Authorization: The platform name is added to
_PLATFORM_ALLOWLIST_ENVingateway/pairing.pyto gate access.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:180-210, gateway/platforms/ADDING_A_PLATFORM.md:218-230
Out-of-Process Delivery
For cron jobs or the send_message tool, the system provides a way to deliver messages without a running gateway adapter. This is implemented via a standalone sender function (e.g., _send_to_platform in tools/send_message_tool.py) that uses the platform's API directly for fire-and-forget delivery.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:255-270
Summary
Gateway Adapters for Discord, Slack, and Telegram provide the necessary interface for Hermes Agent to function as a cross-platform messaging bot. By inheriting from a standardized base and following specific implementation patterns—such as session key derivation and message deduplication—these adapters ensure that the agent remains secure, responsive, and platform-aware.