Hermes Agent gateway setup: Telegram, Discord, WhatsApp, Email and 11 more

How the gateway works

A single hermes gateway process handles all connected platforms simultaneously. You run it once and it listens on all configured channels, delivering messages to the agent, running the inference loop, and sending responses back to the originating platform.

Security is opt-in per platform. Every platform has an ALLOWED_USERS environment variable that acts as an allowlist. Without it, the gateway accepts messages from anyone who finds your bot. That is a serious problem for an agent with shell access. Set allowlists before exposing any gateway publicly.

The alternative to manual allowlists is DM pairing codes: unknown users message your bot and receive a one-time pairing code that expires after one hour. You approve it with hermes pairing approve <platform> <code>. More scalable than maintaining a static list if you have multiple users.

Telegram

Telegram is the most commonly used Hermes gateway. Setup:

1. Message @BotFather in Telegram → send /newbot → follow prompts → copy the token
2. Message @userinfobot to get your numeric user ID
3. Add to ~/.hermes/.env:

4. Test it: hermes gateway
5. Install as service: hermes gateway install

Or use the interactive wizard:

For webhook mode instead of long-polling (more reliable, lower latency):

Webhook mode requires a public HTTPS endpoint. Long-polling works fine for personal use without a domain.

Group chat access is disabled by default. To enable it: add TELEGRAM_ALLOW_GROUPS=true and be aware that everyone in the group who is in your allowlist can issue commands.

Discord

Discord support includes slash commands, thread responses, and voice channel transcription. Setup:

1. Go to discord.com/developers/applications → New Application → name it
2. Bot tab → Add Bot → copy the token
3. OAuth2 tab → URL Generator → select bot and applications.commands scopes, Send Messages + Read Message History + Use Slash Commands permissions → copy the generated URL and visit it to add the bot to your server
4. Enable Message Content Intent in the Bot tab (required for reading messages)
5. Add to .env:

Discord voice channel integration uses voice recognition to transcribe speech and pass it to the agent. Install the voice dependencies first:

For slash commands to appear, the bot registers them automatically on first connection. If they do not appear, kick and re-add the bot to the server to force command re-registration.

WhatsApp

WhatsApp integration uses the Baileys library, an unofficial bridge that emulates the WhatsApp Web session protocol. No Meta developer account required.

Setup:

The wizard installs the Baileys bridge dependencies (requires Node.js v18+), displays a QR code, and you scan it: WhatsApp → Settings → Linked Devices → Link a Device. Session saves automatically.

Two modes: a separate bot number (dedicate a phone number to the bot for lower ban risk and a cleaner experience for multiple users) or personal self-chat (use your own WhatsApp number and message yourself to talk to the agent, which is easier to set up but carries more account risk).

The main risk: WhatsApp's terms prohibit unofficial automation. For personal use, ban risk is low. For anything resembling bulk messaging or outreach to people who have not opted in, the risk is significant. The official WhatsApp Business API (which Hermes does not use) is the compliant path for business use.

Email

The email gateway uses standard IMAP (inbound) and SMTP (outbound). No external libraries.

For Gmail:

For Outlook/Microsoft 365:

Ports default to IMAP 993 (TLS) and SMTP 587 (STARTTLS). Override with EMAIL_IMAP_PORT and EMAIL_SMTP_PORT if needed.

Use a dedicated email account, not your personal inbox. The gateway reads and processes all incoming email to that address.

Webhooks

The webhook gateway runs an HTTP server on port 8644 and accepts POST requests, connecting Hermes to any service that sends webhooks: GitHub, GitLab, JIRA, Stripe, or custom triggers.

Create a named route:

Endpoint format: http://your-server:8644/webhooks/<route-name>

Health check: curl http://localhost:8644/health

Common uses: receive GitHub PR review requests for the agent to summarize, process JIRA ticket updates, handle Stripe payment events and trigger follow-up tasks. The agent receives the webhook payload, interprets it, and can use any of its tools in response.

The full list: all 15 platforms

The complete gateway list confirmed in the official documentation (15 total, not 12 as the README states):

1. Telegram: most popular, long-polling or webhook mode
2. Discord: slash commands, voice channel, thread support
3. Slack: Slack app with OAuth, works in DMs and channels
4. WhatsApp: Baileys bridge, unofficial
5. Signal: requires Signal CLI installed and linked phone number
6. SMS: Twilio integration, sends/receives SMS
7. Email: IMAP/SMTP, any provider
8. Home Assistant: integrates directly as a conversation agent
9. Mattermost: self-hosted Slack alternative
10. Matrix: decentralized messaging protocol (Element, etc.)
11. DingTalk: Alibaba's enterprise messaging platform
12. Feishu/Lark: ByteDance enterprise messenger
13. WeCom: Tencent's enterprise WeChat variant
14. Open WebUI / API Server: HTTP API endpoint for custom frontends
15. Webhooks: generic HTTP webhook receiver

All gateways share the same security model: ALLOWED_USERS allowlist or DM pairing code approval. GATEWAY_ALLOWED_USERS applies across all connected platforms as a global setting. Per-platform variables override it. GATEWAY_ALLOW_ALL_USERS=true accepts messages from anyone. Do not set this on a gateway with shell access.

Running multiple gateways simultaneously

One hermes gateway process handles all configured platforms. Set credentials for Telegram and Discord both, and the same agent responds on both channels with shared memory and context. A message from Telegram and a message from Discord reach the same agent: your task history and preferences persist regardless of which platform you are messaging from.

The built-in cron scheduler runs inside the gateway process and can deliver to any connected platform. A morning briefing goes to Telegram, a work-hours alert to Slack, an end-of-day summary to Email, all from the same scheduled task configuration.

Token usage is higher through messaging gateways than CLI. Telegram adds roughly 15,000-20,000 tokens of overhead per message (versus 6,000-8,000 in CLI) due to AGENTS.md workspace files and additional context. At Sonnet 4.6 pricing, that is approximately $0.03-0.06 per message in overhead alone. Disable unused tool categories with hermes tools to reduce the baseline cost.

Hivra gateway setup

On Hivra, gateway configuration is handled through the dashboard: paste your Telegram bot token and user ID, click connect. The gateway service is managed, monitored, and restarted automatically. You do not need the hermes gateway install → systemctl → loginctl enable-linger sequence.

The dashboard's channel list includes Telegram, Discord, Slack, WhatsApp, Signal, SMS and Email. Multi-gateway setup (Telegram + Discord + Email simultaneously) works by adding credentials for each platform in the dashboard.