The Messaging Gateway: Telegram, Discord, Slack, and 20 More

Why a "Gateway" and Not Just a Bot Per Platform

Hermes does not make you stand up a separate integration for each messaging platform you want to use. The gateway is a single background process that connects to every platform you configure, handles session management, runs your scheduled cron jobs from Lesson 1, and delivers voice messages -- all unified under one process rather than a tangle of separate bots.

What It Connects To

The gateway supports 20+ platforms across several categories:

• Popular: Telegram, Discord, Slack
• Enterprise: Microsoft Teams, Mattermost, Matrix
• Mobile/Chat: WhatsApp, Signal, SMS
• Chinese platforms: DingTalk, Feishu/Lark, WeCom, Weixin, QQ
• Specialized: Email, Home Assistant, BlueBubbles (iMessage), ntfy

What You Need Before Running Setup

The gateway wizard configures a platform; it does not create your presence on that platform. For every platform you want to connect, you first need to register your own bot or app directly with that platform and obtain its credentials -- the wizard has nothing to connect to without them. Two concrete examples: for Telegram, you message Telegram's own @BotFather to create a bot and receive a bot token; for Discord, you create an application and bot user in Discord's own developer portal and copy its token. Each platform's exact process differs and is documented on that platform's own developer site, not inside Hermes -- the wizard will prompt you for whatever token or credential that platform requires once you reach it.

Setting It Up

Once you have at least one platform's bot credentials in hand, the primary path is an interactive wizard:

hermes gateway setup

It walks you through platform configuration with arrow-key selection, shows you what is already configured, and manages starting the relevant services -- you do not need to hand-edit configuration files for a standard setup, but you do need to have already created the bot/app on the platform itself before the wizard reaches that step.

Access Control Defaults to Deny

This is the most important fact in this lesson: the gateway denies all users by default unless they are explicitly allowlisted or have paired via direct message. An unconfigured gateway connected to a public platform does not mean "anyone can talk to your agent" -- it means almost the opposite, nobody can, until you explicitly grant access.

The simplest allowlist mechanism is a platform-specific environment variable:

TELEGRAM_ALLOWED_USERS=123456789,987654321

For teams, DM pairing is the more scalable alternative to hardcoding user IDs one at a time -- a teammate pairs in via a one-time code that you, as the bot owner, approve.

Session Behavior

Sessions on a messaging platform maintain conversation context across multiple messages until something resets them. Reset policies support either a daily reset at a specific time, or an idle-timeout trigger -- the default idle timeout is 1,440 minutes (24 hours).

Access is also tiered: admin and regular user roles get different command access, and this is configurable per-platform and per-scope -- a Discord server might have different admins than your Telegram allowlist.

Running It as a Real Service

For a gateway you actually want running continuously rather than just while a terminal is open:

hermes gateway install     # systemd user service on Linux, launchd agent on macOS
hermes gateway start
hermes gateway stop
hermes gateway status

Both platforms support the same start/stop/status pattern once installed as a service.

Common Failure Modes

Three issues account for most gateway problems, drawn directly from Hermes' own troubleshooting documentation:

• Bot completely unresponsive. Almost always either the gateway process is not actually running, or an authorization problem is silently dropping the message -- check hermes gateway status first, then your allowlist configuration.
• WSL disconnections. If you are running the gateway inside WSL on Windows, prefer running it in the foreground (hermes gateway run) over installing it as a systemd service -- WSL's systemd support is less reliable for long-running background services than running it directly.
• macOS launchd inherits a minimal PATH. If you install something via Homebrew or a similar package manager after already setting up the gateway as a launchd service, the service will not see the new PATH entry. Rerun hermes gateway install after installing new command-line tools so the service picks up the updated environment.

Two Practical Habits

Use /sethome to designate which channel scheduled job output should land in by default -- without this, you may not be sure where a cron job's summary is supposed to show up.

If you have a lot of skills installed and are running on Telegram specifically, be aware of the platform's 100 slash-command limit. Disable skills you do not need on that platform under platform_disabled.telegram in config.yaml rather than running into the cap unexpectedly.

With your agent now reachable from outside a terminal, the next lesson covers extending what it can actually do once someone reaches it: connecting external tools via MCP servers.