Hermes Agent platform message integration

The Messaging Gateway enablesSame Agent—The same memories, skills, and tools—running seamlessly across 20+ platforms.

This chapter will introduce Gateway configuration and deployment, session lifecycle, multi-user isolation policies, and security access control.

Message Gateway Overview

The message gateway is a resident background process that centrally manages connections, sessions, scheduled tasks, and media delivery for all messaging platforms.

Everything you teach the Agent in the CLI—memory, skills, preferences—is fully consistent across all platforms.

Supported platforms

Hermes Supported 20+ MessagePlatform：CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、Feishu/Lark、WeChat Work、micro信、QQ、元宝、BlueBubbles（iMessage）、Home Assistant、Microsoft Teams、Google Chat etc.

Platform Capability Comparison

Cross-platform session continuity: the same Agent can maintain context across different platforms. For example, if you are mid-conversation with the Agent on Telegram and switch to Discord, the Agent still remembers the previous conversation.

Gateway startup and configuration

Desktop version configuration

Open the Messaging Platforms item in the left menu to see the supported platforms. Click the corresponding platform to configure it:

Configuration in Interactive Mode

Use the interactive wizard to complete the initial configuration for all platforms:

hermes gateway setup

The wizard will guide you through configuring each platform: selecting the platform, filling in the Bot Token, setting the allowed user list, etc.

For example, after selecting Feishu, you can choose to create a bot by scanning a QR code or by using the APP ID:

Gateway Management Commands

Telegram Bot integration hands-on

Take Telegram as an example to complete a full Bot integration process.

Step 1: Create a Telegram Bot.

In Telegram, search for @BotFather, send the /newbot command, and set the Bot name and username as prompted.

BotFather will return a Bot API Token, formatted similar to:1234567890:ABCdefGHIjklMNOpqrsTUVwxyz。

Step 2: Configure the Hermes Gateway.

Step 3: Start and test.

For the initial integration, it is recommended to use whitelist mode (allowed_users), allowing only your own account to interact with the Agent, and then open it to others after verifying everything works properly.

Slash commands available within the platform

The following commands are available on any messaging platform:

Session Lifecycle

Session is the core concept in Hermes Gateway for managing conversations.

Understanding how Session works helps you configure appropriate session isolation policies and reset rules.

SessionSource: message source descriptor

Every message entering the Gateway carries a SessionSource, which records "where this message came from."

Session Key generation rules

Session Key is a deterministic string composed of fields from the SessionSource.

It determines which messages belong to the same session. The format is as follows:

agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id}

Examples of Session Keys in different scenarios:

The Session Key generation rule is one of the most important Gateway configurations. If misconfigured, it may cause cross-talk between different users' sessions—two different people seeing each other's conversation content.

SessionEntry: active session record

Each Session Key corresponds to a SessionEntry, which records the session's metadata and state.

Multi-User Isolation Policy

Multi-user isolation determines whether multiple users in the same group or channel share a single session or have their own independent sessions.

This configuration directly affects the user experience—a shared session means user A can see user B's conversation context.

Isolation Policy Configuration

Behavior in Different Scenarios

System prompt changes for shared sessions

When the session is in shared mode (shared_multi_user_session = true), the system prompt will change:

• Instead of a fixed username, it prompts "Multi-user session—message prefix includes sender name"
• Each user message is prefixed with the sender's display name so the Agent knows who is speaking
• This design maintains the effectiveness of prompt caching (the system prompt does not change with the sender)

The default isolation policy (per-user for groups, shared for threads) is a best practice verified through extensive real-world use. Unless you have special requirements, it is not recommended to change it.

Gateway Security Configuration

User Access Control

By default, the gateway rejects all users not on the whitelist—This is the secure default setting for a Bot with terminal access privileges.

Configure allowed users (in the .env file):

DM pairing (alternative to whitelist)

No need to manually configure user IDs. When a new user DMs the Bot, they will receive a one-time pairing code:

The pairing code expires after 1 hour, has rate limiting, and is generated using cryptographic random numbers.

Silent token

Used in group chats, Hooks, and automated workflows to make the Agent send no messages under specific conditions:

# Agent 回复中仅包含以下内容之一时，网关不会向平台发送任何消息：
[SILENT]
SILENT
NO_REPLY
NO REPLY

silence isDelivery decision, without affecting the session record—the reply is still stored in the session history, ensuring the conversation turn-taking logic works normally.

Session Reset Policy

Configure when the session automatically resets to prevent unlimited context growth:

Quick Reference for Common Commands