Multi-Platform Messaging Gateway
Relevant source files
The following files were used as context for generating this wiki page:
The Multi-Platform Messaging Gateway enables the Hermes Agent to communicate across various messaging services like Telegram, Discord, WhatsApp, Slack, and Signal. It provides a unified interface for handling inbound messages, sending responses, and managing media attachments regardless of the underlying platform protocol. Sources: gateway/platforms/ADDING_A_PLATFORM.md:1, gateway/AGENTS.md
The gateway uses a plugin-based architecture where each messaging service is implemented as an adapter. This allows the system to extend support to new platforms without modifying the core gateway logic. Sources: gateway/platforms/ADDING_A_PLATFORM.md:3-8
System Architecture
The gateway architecture relies on a GatewayRunner that manages multiple PlatformAdapter instances. Each adapter translates platform-specific events into a common MessageEvent format for the agent to process.
A diagram showing the flow of communication from a user through a platform-specific adapter to the Hermes Agent and back. Sources: gateway/platforms/ADDING_A_PLATFORM.md:128-144, gateway/platforms/base.py
Components and Responsibilities
| Component | Responsibility |
|---|---|
GatewayRunner | Orchestrates adapter lifecycles, handles reconnection, and manages profile routing. |
BasePlatformAdapter | Defines the standard interface for all messaging platforms including send, connect, and handle_message. |
PlatformAdapter | Concrete implementations (e.g., TelegramAdapter) that handle transport, authentication, and platform-specific UX like buttons. |
MessageEvent | A standardized data structure representing an inbound message, sender info, and chat context. |
SessionSource | Tracks the provenance of a conversation, including the platform name and specific chat ID. |
Sources: gateway/platforms/base.py, gateway/platforms/ADDING_A_PLATFORM.md:118-124, gateway/run.py
Integration and Core Logic
The gateway manages platform connectivity through environment variables and a centralized factory pattern.
Platform Initialization
The system uses _instantiate_adapter() to create platform-specific instances based on the Platform enum. Before an adapter starts, the gateway checks if required dependencies and credentials (e.g., API tokens) are available. Sources: gateway/run.py, gateway/platforms/ADDING_A_PLATFORM.md:204-210
A sequence diagram illustrating the initialization and connection process for a messaging platform adapter. Sources: gateway/platforms/ADDING_A_PLATFORM.md:118-126, gateway/run.py
Message Handling Flow
- Inbound Event: A platform adapter receives a raw message from the service API.
- Deduplication: The
MessageDeduplicatordrops redelivered inbound IDs to prevent duplicate processing. - Standardization: The adapter builds a
SessionSourceusingself.build_source(...)and aMessageEvent. - Dispatch: The adapter calls
self.handle_message(event)to pass the data to the runner. - Response: The agent generates a response, which the runner passes back to the adapter's
send()orsend_image()methods.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:162-171, gateway/platforms/base.py
Core Interface: BasePlatformAdapter
All platform integrations must inherit from BasePlatformAdapter and implement its required methods to ensure compatibility. Sources: gateway/platforms/base.py, gateway/platforms/ADDING_A_PLATFORM.md:118
Required Methods
connect(): Starts listeners and establishes the service connection.disconnect(): Safely closes connections and cancels pending tasks.send(chat_id, text): Sends a plain text message to a specific recipient.send_typing(chat_id): Triggers the "typing..." indicator on the platform.send_image(chat_id, image_url, caption): Sends media to the user.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:120-126
Interactive UX Elements
Platforms that support buttons or menus can implement specialized methods for a richer experience:
send_clarify(): Renders multi-choice questions as tappable buttons.send_exec_approval_prompt(): Displays dangerous command approvals (e.g., shell execution) with "Allow" or "Deny" buttons.send_model_picker(): Allows users to interactively select the AI model.
Sources: gateway/platforms/ADDING_A_PLATFORM.md:143-156
Configuration and Security
The gateway utilizes environment variables for platform enablement and user authorization.
Environment Variable Scoping
Every credential read goes through get_scoped_secret or extra_or_secret. This ensures that in multiplexed environments, the gateway uses the correct credentials for the specific profile being accessed. Sources: gateway/platforms/ADDING_A_PLATFORM.md:214-222
Authorization Gates
The system controls access via allowlists. Each platform has a corresponding environment variable (e.g., TELEGRAM_ALLOWED_USERS) that specifies which user IDs are authorized to interact with the agent. Sources: gateway/platforms/ADDING_A_PLATFORM.md:231-238
| Feature | Environment Variable Pattern |
|---|---|
| Credentials | [PLATFORM]_TOKEN |
| Home Channel | [PLATFORM]_HOME_CHANNEL |
| Authorization | [PLATFORM]_ALLOWED_USERS |
| Global Access | [PLATFORM]_ALLOW_ALL_USERS |
Sources: gateway/platforms/ADDING_A_PLATFORM.md:212-238, gateway/AGENTS.md
Summary
The Multi-Platform Messaging Gateway acts as the primary sensory and communication layer for the Hermes Agent. By abstracting service-specific protocols into a unified adapter interface, it allows for consistent agent behavior across Telegram, Discord, WhatsApp, and other messaging platforms. It handles the complexities of connection management, message deduplication, and secure credential handling, ensuring that developers can focus on agent logic while users enjoy a seamless interactive experience. Sources: gateway/platforms/base.py, gateway/platforms/ADDING_A_PLATFORM.md:1-15