Platform Adapters

Relevant source files

Platform adapters provide a unified interface for integrating Hermes Agent with messaging platforms (Telegram, Discord, WhatsApp, Slack, Signal, Email, Home Assistant, DingTalk, Matrix, Mattermost, SMS, Webhook, API Server, Feishu, Weixin, Bluebubbles, QQBot, Yuanbao, WeCom, Teams, Google Chat, IRC, LINE, SimplexChat, Photon/iMessage). Each adapter normalizes platform-specific message formats, handles media attachments, manages authentication, and translates between standard markdown and platform-specific formatting conventions.

For information about the gateway service that orchestrates these adapters, see 7.1 Gateway Architecture For session management and routing logic, see 7.3 Session and Media Management

Architecture Overview

Platform adapters follow a common inheritance pattern where all concrete implementations extend BasePlatformAdapter gateway/platforms/base.py333-350 This abstract base class defines the contract for connecting to platforms, sending/receiving messages, and handling media.

Platform Class Hierarchy

Sources: gateway/platforms/base.py333-350 plugins/platforms/telegram/adapter.py156-168 plugins/platforms/slack/adapter.py43-60 gateway/platforms/api_server.py84-91 gateway/platforms/webhook.py147-157 gateway/platforms/weixin.py58-68 gateway/platforms/signal.py200-210 plugins/platforms/photon/adapter.py100-110 plugins/platforms/teams/adapter.py100-110 plugins/platforms/google_chat/adapter.py100-110 gateway/relay/adapter.py100-110

BasePlatformAdapter Interface

The BasePlatformAdapter class gateway/platforms/base.py333-904 defines the core interface that all platform adapters must implement.

Abstract Methods

Method	Purpose	Returns
`connect()`	Establish connection to platform, start receiving messages gateway/platforms/base.py352-358	`bool` (success)
`disconnect()`	Close connection and cleanup resources gateway/platforms/base.py360-366	`None`
`send(chat_id, content, ...)`	Send a text message to a chat gateway/platforms/base.py368-386	`SendResult`
`get_chat_info(chat_id)`	Retrieve chat metadata (name, type) gateway/platforms/base.py461-467	`Dict[str, Any]`

Optional Override Methods

Method	Default Behavior	Override Purpose
`edit_message()`	Returns `success=False`	Platform-specific message editing gateway/platforms/base.py400-415
`send_typing()`	No-op	Show typing indicator gateway/platforms/base.py388-398
`send_image()`	Fallback to text URL	Native image attachments gateway/platforms/base.py420-435
`format_message()`	Return content as-is	Platform-specific markdown conversion gateway/platforms/base.py440-450

Sources: gateway/platforms/base.py352-467

Message Flow and Normalization

Platform adapters normalize diverse message formats into a common MessageEvent structure gateway/platforms/base.py272-318

Inbound Message Pipeline

Sources: gateway/platforms/base.py272-318 plugins/platforms/telegram/adapter.py156-168 plugins/platforms/discord/adapter.py121-137 plugins/platforms/slack/adapter.py45-60

MessageEvent Structure

The MessageEvent dataclass gateway/platforms/base.py272-318 provides a unified representation:

Text extraction: Adapters extract text from platform-specific fields (e.g., Telegram message.text vs message.caption).
Media caching: Attachments are downloaded to local cache directories to preserve them beyond platform URL expiration gateway/platforms/base.py58-175
Normalization: Inbound text is cleaned of platform-specific artifacts (like mentions or slash command prefixes) before reaching the agent.

Media Handling and Caching

Platform adapters download media to local cache directories to avoid ephemeral URL expiration.

Cache Utility Functions

Function	Purpose	Returns
`cache_image_from_bytes`	Save image bytes to cache gateway/platforms/base.py58-73	`str` (absolute path)
`cache_audio_from_bytes`	Save audio bytes to cache gateway/platforms/base.py160-175	`str`
`cache_video_from_bytes`	Save video bytes to cache gateway/platforms/base.py220-235	`str`
`cache_document_from_bytes`	Save document bytes to cache gateway/platforms/base.py240-255	`str`

Sources: gateway/platforms/base.py58-255

Platform-Specific Implementations

Telegram Adapter

The TelegramAdapter uses python-telegram-bot plugins/platforms/telegram/adapter.py4-8

Deadline Timer: Implements _await_with_thread_deadline to handle initialization timeouts independently of the event loop plugins/platforms/telegram/adapter.py80-97
Blocked Loop Diagnostics: Includes a watchdog thread _dump_loop_blocked_diagnostics to identify synchronous blocking calls plugins/platforms/telegram/adapter.py59-79
Error Redaction: Uses _redact_telegram_error_text to mask secrets in transport errors plugins/platforms/telegram/adapter.py28-39
Audio/Voice Handling: Differentiates between sendAudio (MP3/M4A) and sendVoice (Opus/OGG) based on file extension and is_voice flag gateway/platforms/base.py147-150

Sources: plugins/platforms/telegram/adapter.py1-151 gateway/platforms/base.py147-150

Discord Adapter

The DiscordAdapter uses discord.py plugins/platforms/discord/adapter.py6-10

Slash Commands: Supports registration and synchronization of global application commands with a hard cap of 100 plugins/platforms/discord/adapter.py58-63
Websocket Transport Abort: Implements _abort_discord_websocket_transport to force-close hung aiohttp transports plugins/platforms/discord/adapter.py183-200
Non-Conversational Filtering: Uses _DISCORD_NONCONVERSATIONAL_HISTORY_MESSAGE_PATTERNS regexes to recognize status bumps from older versions plugins/platforms/discord/adapter.py79-99
Image Redirect Guard: _read_url_image_with_redirect_guard prevents SSRF by re-checking every redirect target for image URLs plugins/platforms/discord/adapter.py141-176

Sources: plugins/platforms/discord/adapter.py1-200 plugins/platforms/discord/adapter.py141-176

Slack Adapter

The SlackAdapter uses slack-bolt with Socket Mode plugins/platforms/slack/adapter.py4-9

Block Kit Rendering: Uses render_blocks and sanitize_blocks for rich UI components plugins/platforms/slack/adapter.py62-65
GFM Table Preprocessing: Implements _wrap_markdown_tables and _align_table to render CJK-aware monospace tables in Slack's mrkdwn plugins/platforms/slack/adapter.py142-208
Thread Context Hydration: Downloads up to 4 images from the thread root when mentioned mid-thread (_THREAD_ROOT_IMAGE_MAX) plugins/platforms/slack/adapter.py114-119
Ignored Channels: Prevents sending messages to configured ignored_channels tests/gateway/test_slack.py116-154

Sources: plugins/platforms/slack/adapter.py1-208 tests/gateway/test_slack.py116-154

API Server Adapter

The APIServerAdapter gateway/platforms/api_server.py2-23 provides an OpenAI-compatible interface.

Response Store: Uses ResponseStore (SQLite-backed LRU) to maintain conversation state across stateless HTTP requests gateway/platforms/api_server.py91-132
Profile Multiplexing: Supports /p/<profile>/ URL prefixes for reaching secondary profiles gateway/platforms/api_server.py30-37
Reasoning Configuration: Normalizes reasoning_effort for compatible models gateway/platforms/api_server.py193-194
Error Redaction: _redact_api_error_text ensures sensitive information is removed from API error responses tests/gateway/test_api_server.py64-85

Sources: gateway/platforms/api_server.py1-194 tests/gateway/test_api_server.py91-164 tests/gateway/test_api_server.py64-85

Webhook Adapter

The WebhookAdapter gateway/platforms/webhook.py1-31 receives POSTs from external services.

Dual-Stack Binding: Defaults to None for DEFAULT_HOST to bind both IPv4 and IPv6 families gateway/platforms/webhook.py81-99
HMAC Signature V2: Supports X-Webhook-Signature-V2 which binds a timestamp into the signed data for replay protection gateway/platforms/webhook.py26-31
Loopback Protection: Identifies loopback hosts via _is_loopback_host for safety-rail purposes gateway/platforms/webhook.py115-125
Dynamic Routes: Supports dynamically adding and removing webhook routes via webhook_subscriptions.json gateway/platforms/webhook.py166-167

Sources: gateway/platforms/webhook.py1-125 gateway/platforms/webhook.py166-167

Weixin Adapter

The WeixinAdapter gateway/platforms/weixin.py2-11 connects to WeChat personal accounts via Tencent's iLink Bot API.

Encrypted CDN: Implements _aes128_ecb_encrypt and _pkcs7_pad for the media delivery protocol gateway/platforms/weixin.py175-183
SSL Verification: Uses _make_ssl_connector with certifi to verify Tencent's iLink servers on platforms with outdated system CA stores gateway/platforms/weixin.py119-136
UIN Randomization: Generates random WeChat UINs via _random_wechat_uin for protocol compliance gateway/platforms/weixin.py202-205

Sources: gateway/platforms/weixin.py1-205

Signal Adapter

The SignalAdapter gateway/platforms/signal.py1-12 connects to a signal-cli daemon.

AAC Remuxing: Implements _remux_aac_to_m4a using ffmpeg to losslessly convert Android voice notes into compatible M4A containers for STT gateway/platforms/signal.py141-194
Rate Limit Scheduling: Uses get_scheduler and _extract_retry_after_seconds to handle Signal's backoff requirements gateway/platforms/signal.py47-57
Magic Byte Extension Guessing: Disambiguates between ADTS AAC and MP3 frames in _guess_extension gateway/platforms/signal.py83-116

Sources: gateway/platforms/signal.py1-194

WhatsApp Adapter

The WhatsAppAdapter plugins/platforms/whatsapp/adapter.py integrates with WhatsApp via a local whatsapp-bridge instance.

Bridge Communication: Interacts with the whatsapp-bridge via HTTP requests to send and receive messages.
Media Handling: Supports sending and receiving images, videos, and documents, relying on the bridge for media processing.
JID Parsing: Recognizes various WhatsApp JID formats (e.g., phone@s.whatsapp.net, group@g.us) for direct targeting tools/send_message_tool.py48-52

Sources: plugins/platforms/whatsapp/adapter.py tools/send_message_tool.py48-52

Feishu Adapter

The FeishuAdapter plugins/platforms/feishu/adapter.py connects to Feishu (Lark) via its Open Platform APIs.

Message Types: Supports various message types including text, rich text, and cards.
Thread Handling: Routes replies within existing Feishu threads using reply_to_message_id gateway/platforms/base.py126-127
Signature Verification: Validates incoming webhook requests using HMAC-SHA256 signatures.

Sources: plugins/platforms/feishu/adapter.py gateway/platforms/base.py126-127

QQBot Adapter

The QQBotAdapter gateway/platforms/qqbot/adapter.py integrates with QQBot.

WebSocket Connection: Establishes a WebSocket connection to the QQBot API for real-time message exchange.
Message Formatting: Handles QQBot-specific message formatting, including mentions and rich content.

Sources: gateway/platforms/qqbot/adapter.py

Photon/iMessage Adapter

The PhotonAdapter plugins/platforms/photon/adapter.py provides integration with Photon, which can bridge to iMessage.

Sidecar Process: Communicates with a local Photon sidecar process (written in Node.js) plugins/platforms/photon/sidecar/index.mjs to interact with iMessage.
E.164 Phone Numbers: Targets recipients using E.164 formatted phone numbers tools/send_message_tool.py45-47

Sources: plugins/platforms/photon/adapter.py plugins/platforms/photon/sidecar/index.mjs tools/send_message_tool.py45-47

Teams Adapter

The TeamsAdapter plugins/platforms/teams/adapter.py integrates with Microsoft Teams.

Bot Framework: Leverages the Microsoft Bot Framework for message handling.
Adaptive Cards: Supports rich interactions using Adaptive Cards.

Sources: plugins/platforms/teams/adapter.py

Google Chat Adapter

The GoogleChatAdapter plugins/platforms/google_chat/adapter.py integrates with Google Chat.

Webhook Endpoints: Uses Google Chat webhook endpoints for sending messages.
Card Messages: Supports sending structured card messages.

Sources: plugins/platforms/google_chat/adapter.py

Relay Connector

The RelayAdapter gateway/relay/adapter.py and RelayConnector provide a mechanism for bridging remote gateway instances. This allows a Hermes instance in one network to act as a gateway for a remote instance, facilitating multi-hop communication or remote management. It utilizes WebSocket transports for bidirectional message passing gateway/relay/ws_transport.py

Sources: gateway/relay/adapter.py gateway/relay/ws_transport.py