Multi-platform gateway: Discord, Slack, WhatsApp and more

Multi-platform gateway: Discord, Slack, WhatsApp and more

One AI agent, all your messaging platforms. That is the promise of the Hermes Agent gateway: a single backend process that connects Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant and Microsoft Teams — with a single agent, a single memory, a single identity.

In this advanced guide, we explore the gateway architecture, the configuration of each platform, cross-platform formatting, media management, per-channel profiles, and best practices for deploying an agent accessible everywhere.

What is the Hermes Agent gateway?

The gateway is a single background process that connects Hermes to your messaging platforms. It manages sessions, executes scheduled tasks (cron), transcribes voice messages, and distributes responses — all from a single central point.

🏗️ Hub-and-spoke architecture: the GatewayRunner orchestrates the platform adapters, routes messages to the agent, and persists session state. Each platform has a dedicated adapter implementing BasePlatformAdapter.

In practice, this means you can:
- Start a conversation on Telegram from your smartphone
- Continue it on Slack from your desk
- Receive a voice response on Discord — with the context preserved

To understand how the agent maintains this context across platforms, check out our guide on sessions and conversation context.

Supported platforms

Hermes Agent natively integrates about fifteen platforms, including the main ones:

• Telegram — webhook or polling, voice messages, topic groups
• Discord — server bot, channels, private messages
• Slack — workspace, channels, threads, bot-type app
• WhatsApp — via WhatsApp Business API (Cloud API or Baileys)
• Signal — end-to-end encrypted messages
• Email — receiving and sending via SMTP/IMAP
• Home Assistant — notifications and home automation commands
• Microsoft Teams — via plugin (extended adapter)
• Matrix, Mattermost, IRC — communities and self-hosting
• DingTalk, Feishu, WeChat — Chinese ecosystem (some via plugins)

Each adapter implements the same interfaces: message reception, response sending, media management, slash commands — with platform-specific optimizations.

hermes gateway setup: interactive configuration

Everything starts with the configuration assistant:

hermes gateway setup

This command launches an interactive wizard that guides you step by step:

1. Platform selection — select the platforms to enable
2. Token configuration — enter the API/bot keys for each platform
3. Allowlist — define who can interact with the agent
4. Default channels — configure the welcome and log channels
5. Advanced settings — retry, timeout, session reset policy

💡 Tip: to reconfigure a single platform without restarting the entire wizard, use hermes setup gateway which offers incremental configuration.

Tokens and secrets are stored in the .env file (never in the config YAML), which guarantees the separation between functional configuration and sensitive secrets.

To master all the available commands, check out our article to maîtriser le CLI d'Hermes Agent.

hermes gateway status : real-time diagnostics

Once the gateway is configured, diagnostics are essential:

hermes gateway status

This command displays the status of each connected platform:
- ✅ Connected — the adapter is working
- ⚠️ Degraded — working with limitations
- ❌ Disconnected — unable to reach the platform
- 🔄 Reconnecting — reconnection attempt in progress

For a complete diagnostic including the AI provider, cron tasks, and overall health:

hermes status

Configuration by platform

Configuration file

The gateway configuration is located in ~/.hermes/config.yaml under the gateway: key. This YAML file is structured around three levels: the root key gateway, which contains platforms (the activators and tokens for each service), allowed_users (the allowlists), and platform_profiles (the specific behaviors). Each platform has its own subkey — telegram, discord, slack, whatsapp, signal, email — with adapted parameters: the authentication token, home channels (home_channel), allowed guilds (allowed_guilds), or even SMTP/IMAP hosts for email. Sensitive values (tokens, passwords) are never written in plain text: they are referenced via environment variables such as ${TELEGRAM_BOT_TOKEN}.

To go further in organizing your configuration, discover context files: CLAUDE.md, AGENTS.md and beyond.

Allowlists: who can talk to your agent?

Security relies on platform-specific allowlists:

• Telegram: allowlist by user_id or chat_id
• Discord: allowlist by server (guild_id) and/or role
• Slack: allowlist by workspace and channel
• WhatsApp: allowlist by phone number
• Signal: allowlist by phone number
• Email: whitelist by domain or address

Each platform has its own security options. For Telegram and Signal, restriction is done by numeric identifier (user_id or phone number). Discord combines guild (server) filtering with role filtering, allowing granular control — for example, only allowing members with the "admin" or "hermes-user" role. Slack restricts access channel by channel via their identifiers (like C01ABCDEF). For email, the system accepts glob patterns like *@mycompany.com to authorize an entire domain, or individual addresses. This structure allows you to define precise access perimeters without compromising multi-platform flexibility.

🔒 Security: without a configured allowlist, the agent could respond to anyone. Always configure an allowlist in production.

Cross-platform formatting: automatic adaptation

Each platform has its own formatting rules. Hermes handles this automatically:

• Markdown → adapted according to the platform (Telegram takes a subset, Discord its own markdown, Slack its own)
• Mentions → @user translated into each platform's native format
• Code blocks → adapted syntax highlighting (some clients do not support colored code blocks)
• Links → previews managed according to client capabilities
• Long messages → automatic chunking to respect each platform's limits

For example, a response with Markdown code will be rendered differently:
- Telegram: <pre><code class="language-python"> in HTML
- Discord: `python` with Discord syntax highlighting - **Slack**: `python ` in Markdown mode
- WhatsApp: plain text with indentation (no native markdown)

Media and file management across platforms

Hermes uses the MEDIA: system for files:

• Images: sent/received on all platforms that support media
• Documents: PDFs, text files — transferred across platforms
• Voice messages: automatic transcription via Whisper (local, Groq or OpenAI)
• Generated files: scripts, reports — delivered as attachments

Images are validated before caching (cross-platform), and downloads are size-limited to prevent abuse.

Platform profiles: different tools per channel

A powerful feature: configuring different tools and behaviors depending on the platform. Hermes offers several predefined profiles, each pairing a toolset (set of tools) and a personality (tone and response style). The work-productivity profile enables document search and productivity tools with a professional tone. The personal-assistant profile favors smart home tools, reminders, and daily summaries, with a friendly tone. The community-bot profile focuses on moderation, FAQs, and server integration, with a utilitarian tone. You can assign these profiles to each platform independently — for example, Slack in work mode, Telegram in personal mode, Discord in community mode.

To dive deeper into profile management, check out our guide on multiple profiles and configurations.

Webhook vs Polling

Hermes supports both connection modes:

Webhook (recommended when possible):
- The platform pushes messages to your server
- Minimal latency
- Requires a publicly accessible server (HTTPS)
- Used by Telegram, Discord, Slack, Teams

Polling (fallback or when webhook is not possible):
- Hermes regularly polls the platform
- Slight latency (a few seconds)
- Works behind NAT/firewall
- Used by WhatsApp, Signal, Email

💡 Recommended VPS: for webhooks, a VPS with a public IP is ideal. Hostinger offers VPS starting from a few euros per month, perfect for hosting the Hermes gateway 24/7.

Deploying the gateway as a system service takes place in four steps: first, the hermes gateway setup command allows you to interactively configure platforms and tokens. Next, hermes gateway status verifies that the configuration is valid and that connections are active. The hermes gateway install command then registers the gateway as a systemd service, ensuring automatic startup at boot and restart in case of a crash. Finally, hermes gateway start launches the service — or hermes gateway stop to stop it gracefully.

Gateway logs and monitoring

Structured logs

The gateway generates detailed logs in ~/.hermes/logs/:
- Messages received and sent per platform
- Connection errors and retry attempts
- AI model response times
- Token usage per session

Monitoring commands

hermes gateway status    # Connection status
hermes status            # Overall health (provider, cron, gateway)
hermes doctor            # Complete diagnostics

Monitoring webhook

Hermes exposes a webhook endpoint for external alerts — useful for integrating with monitoring systems like Uptime Kuma or Grafana.

Complete example: multi-platform configuration

Here is a realistic scenario for an advanced user: a developer configures Hermes to respond simultaneously on three platforms with distinct behaviors. On Telegram, the agent acts as a personal assistant (tool personal-assistant, friendly tone), with an allowlist limited to two user_ids and a defined welcome channel. On Discord, it serves as a community bot (tool community-bot, utility tone), restricted to a specific guild. On Slack, it operates in professional mode (tool work-tools, professional tone), accessible only from two workspace channels. The session is configured in cross_platform: true mode to unify the context between the three channels, with an automatic reset after 24h of inactivity (after_idle_24h). Authentication tokens are injected via environment variables from the .env file, never written in plain text in the YAML.

Once this configuration is in place, deployment follows the classic cycle: launching the setup wizard, checking the status, installing as a systemd service, then starting. Your agent then responds simultaneously on the three platforms — with personalities and tools adapted to each context.

Best practices

1. Start with a single platform — add others one by one after validation
2. Always configure an allowlist — never expose an agent without access control
3. Use .env for secrets — never plain text tokens in the YAML config
4. Install as a systemd service — for 24/7 operation with auto-restart
5. Monitor the logs — connection errors are the #1 cause of problems
6. Test with hermes gateway status — after every configuration change
7. Separate profiles by context — pro on Slack, personal on Telegram, community on Discord

Common pitfalls

• Expired token → platforms revoke tokens. Check with hermes gateway setup
• Forgotten allowlist → the agent won't respond to anyone if the allowlist is empty and the mode is restrictive
• Unreachable webhook → ensure your server is reachable over HTTPS
• Message too long → Hermes chunks automatically, but some platforms have strict limits
• Media too heavy → images >20MB are rejected, as are PDFs >50MB
• Session conflict → the same user on two platforms creates two sessions unless cross_platform: true

Common errors

• Missing environment variable → if a token ${VAR} is not defined in .env, the gateway fails silently on startup. Check with hermes doctor.
• Port already in use → two instances of the gateway cannot listen on the same port. The error message is often cryptic — use lsof -i :PORT to identify the blocking process.
• Malformed YAML indentation → an indentation error in config.yaml is interpreted as a different key. Use a YAML validator before restarting.
• Incorrect webhook URL → Telegram and Slack require an exact URL with the correct path. A missing trailing slash can be enough to break the connection.

Security by platform

Each platform implements specific security mechanisms. Telegram relies on a secure bot token combined with an allowlist by user_id, with private mode recommended for sensitive groups. Discord applies guild and role restrictions, and requires limiting intents to the strict minimum to adhere to the principle of least privilege. Slack requires a verification token, app-level restrictions, and minimal OAuth scopes. WhatsApp secures its webhooks via an HMAC signature and verifies the authenticity of phone numbers. Signal benefits from the protocol's native E2E encryption with a verified number. Finally, Email requires the configuration of SPF/DKIM/DMARC for deliverability and enforces TLS for all exchanges.

Recommended tools

• Hostinger — Affordable VPS with a public IP, ideal for hosting the gateway 24/7 and receiving webhooks in HTTPS
• Uptime Kuma — Open-source monitoring tool to monitor your gateway's availability and receive alerts
• Groq — API provider for speech transcription via Whisper, with latencies under a second in 2025

The Essentials

Hermes Agent's multi-platform gateway centralizes all your messaging apps into a single backend process. It supports around fifteen platforms (Telegram, Discord, Slack, WhatsApp, Signal, Email, etc.) with dedicated adapters implementing a common interface. Configuration is managed via hermes gateway setup and a structured YAML file under ~/.hermes/config.yaml, with secrets isolated in .env. The profile system allows you to adapt tools and personality per channel, while formatting and chunking are handled automatically based on each platform's capabilities. Security relies on per-platform allowlists and native mechanisms (HMAC, limited intents, OAuth scopes). Deployment as a systemd service ensures continuous operation with auto-restart. The key to success: start with a single platform, configure allowlists immediately, and monitor with hermes gateway status.

Conclusion

Hermes Agent's multi-platform gateway transforms a terminal agent into an omnipresent assistant. A single process, a single memory, a single identity — available on Telegram, Discord, Slack, WhatsApp, Signal, Email and more.

For a complete introduction to Hermes Agent, check out our presentation and installation article. To master advanced configuration, the models and providers guide is essential. And to unleash the agent's full potential, discover the skills system that enables Hermes to learn and continuously improve. Finally, to understand how the agent retains its memories from one conversation to the next, read our article on persistent memory: how Hermes remembers.

The power of Hermes lies in its ability to adapt to every context — every platform, every user, every conversation. The gateway is the bridge that makes this possible.