Hermes Agent Messaging Platform Setup: Complete Guide for 17 Platforms

Introduction

Hermes Agent supports 17 messaging platforms, and you can run multiple platforms simultaneously on a single Gateway instance. This guide provides complete configuration steps for each platform, helping you quickly connect your AI assistant to your preferred communication tools.

For managed deployment services, see View Plans; for technical support, Contact Us.

Recommended Reading: WeChat VS Feishu VS Telegram Comparison — Learn the pros and cons of three major platforms to choose the best one for you.

---

General Information

Configuration Methods

Hermes provides two configuration methods:

1. Interactive Wizard: Run hermes gateway setup, follow prompts to select platforms and enter credentials
2. Manual Editing: Directly edit the ~/.hermes/.env file

Startup Methods

• Foreground: hermes gateway run
• Install as System Service: hermes gateway install (supports systemd/launchd)

Common Environment Variables

• GATEWAY_ALLOW_ALL_USERS=true: Allow all users (not recommended for production)

---

1. Telegram

Telegram has moderate configuration complexity—you need to create a Bot and obtain a Token.

Required Environment Variables

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_ALLOWED_USERS=123456789,987654321

Configuration Steps

1. Create a Bot

   • Search for @BotFather in Telegram
   • Send /newbot command
   • Follow prompts to set Bot name and username
   • Save the returned Bot Token

2. Disable Privacy Mode (if using in groups)

   • Send /mybots to BotFather
   • Select your Bot → Bot Settings → Group Privacy → Turn off
   • Otherwise the Bot can only see /commands and @ replies in groups

3. Get User ID

   • Search for @userinfobot or @getmyid_bot
   • Send any message to get your User ID
   • Add ID to TELEGRAM_ALLOWED_USERS

4. Save Configuration and Start

   # Edit ~/.hermes/.env
   hermes gateway
   

Optional Configuration

TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook/telegram
TELEGRAM_HOME_CHANNEL=@your_channel

---

2. Feishu / Lark

Feishu configuration is more complex, requiring application creation on the open platform. Our platform provides a Feishu configuration assistant that automates most of the process.

Required Environment Variables

FEISHU_APP_ID=cli_xxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_DOMAIN=feishu  # Use 'feishu' for China, 'lark' for international

Configuration Steps

1. Create Application

   • Visit Feishu Open Platform or Lark Developer
   • Create an enterprise custom application
   • Record App ID and App Secret

2. Enable Bot Capability

   • Enable "Bot" in application features
   • Configure bot name and avatar

3. Configure Permissions

   • Permissions Management → Add permissions
   • Required: receive messages, send messages, get user info, etc.

4. Choose Connection Mode

   • WebSocket Mode (recommended): No public network address needed
   • Webhook Mode: Requires callback URL configuration

5. Publish Application

   • Set availability scope
   • Submit for version review
   • Publish

6. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Using Hermes Agent Feishu Config Helper

We provide a free Hermes Agent Feishu Config Helper that automates most of the configuration process:

1. Download the helper: Visit Hermes Agent Feishu Config Helper Download Page
2. Follow the guide to create an app on Feishu Open Platform
3. Enter App ID and Secret, the helper auto-configures permissions
4. Copy configuration to your Hermes Agent server

This tool is permanently free, whether you subscribe to our service or not.

---

3. WeChat (Personal WeChat)

WeChat has the simplest configuration—just scan a QR code to bind.

Required Environment Variables

WEIXIN_ACCOUNT_ID=auto-obtained
WEIXIN_TOKEN=auto-saved

Configuration Steps

1. Start Configuration Wizard

   hermes gateway setup
   # Select Weixin
   

2. Scan QR Code

   • Terminal displays QR code

   • Scan with WeChat to confirm login

   • Credentials auto-saved to ~/.hermes/weixin/accounts/

   Tip: If the terminal cannot display the QR code properly (misaligned or garbled characters), the terminal usually also shows a URL link. Copy that link and open it in a browser to see the QR code image, then scan with WeChat.

3. Start Gateway

   hermes gateway
   

Important Notes

• Uses iLink Bot API, not Enterprise WeChat
• Risk of account suspension—use a secondary account
• Group chat disabled by default

---

4. WeCom (Enterprise WeChat)

Required Environment Variables

WECOM_BOT_ID=your_bot_id
WECOM_SECRET=your_secret

Configuration Steps

1. Create AI Bot

   • Log into WeCom admin console
   • Application Management → Create App → AI Bot

2. Get Credentials

   • Record Bot ID and Secret

3. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Features

• Uses WebSocket transport, no public network needed
• DM and group chat enabled by default

---

5. Discord

Required Environment Variables

DISCORD_BOT_TOKEN=your_bot_token
DISCORD_ALLOWED_USERS=user_id_1,user_id_2

Configuration Steps

1. Create Application

   • Visit Discord Developer Portal
   • Create new application

2. Create Bot

   • Go to Bot settings
   • Click Add Bot
   • Enable Public Bot

3. Configure Permissions (Important!)

   • Enable Privileged Gateway Intents:
     • Server Members Intent ✓
     • Message Content Intent ✓ (most common gotcha!)

4. Get Token and Invite Link

   • Copy Bot Token
   • OAuth2 → URL Generator
   • Permission integer: 274878286912
   • Generate invite link

5. Invite Bot to Server

   • Use invite link to add Bot

6. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

---

6. Slack

Required Environment Variables

SLACK_BOT_TOKEN=xoxb-xxxxx
SLACK_APP_TOKEN=xapp-xxxxx
SLACK_ALLOWED_USERS=U12345,U67890

Configuration Steps

1. Create Slack App

   • Visit Slack API
   • Create From scratch

2. Configure Bot Token Scopes

   • OAuth & Permissions → Scopes
   • Add: chat:write, app_mentions:read, channels:history, im:history, etc.

3. Enable Socket Mode

   • Socket Mode → Enable
   • Create App-Level Token (needs connections:write scope)

4. Subscribe to Events

   • Event Subscriptions → Enable
   • Subscribe: message.im, message.channels, message.groups, app_mention

5. Enable Messages Tab

   • App Home → Show Tabs → Messages Tab ✓

6. Install to Workspace

   • Install App → Install to Workspace
   • Save Bot Token

7. Invite Bot to Channel

   /invite @Hermes Agent
   

---

7. WhatsApp

Required Environment Variables

WHATSAPP_ENABLED=true
WHATSAPP_ALLOWED_USERS=8613800138000,8613900139000

Configuration Steps

1. Start Configuration Wizard

   hermes whatsapp
   # Displays QR code
   

2. Scan to Bind

   • WhatsApp → Settings → Linked Devices → Scan QR code

3. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Important Notes

• Uses Baileys unofficial bridge
• Small risk of account suspension—use dedicated number
• Phone number format: country code + number, no + sign

---

8. DingTalk

Required Environment Variables

DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

Configuration Steps

1. Create Application

   • Visit DingTalk Open Platform
   • Create internal enterprise application

2. Enable Bot Capability

   • Select Stream Mode (WebSocket)

3. Install Dependencies

   pip install dingtalk-stream httpx
   

4. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Features

• Stream Mode uses WebSocket, no public network needed

---

9. Signal

Required Environment Variables

SIGNAL_HTTP_URL=http://127.0.0.1:8080
SIGNAL_ACCOUNT=+8613800138000

Configuration Steps

1. Install signal-cli

   • Requires Java 17+
   • Download and install signal-cli

2. Link Device

   signal-cli link -n "HermesAgent"
   # Scan QR code with Signal app
   

3. Start Daemon

   signal-cli --account +number daemon --http 127.0.0.1:8080
   

4. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

---

10. Email

Required Environment Variables

EMAIL_ADDRESS=[email protected]
EMAIL_PASSWORD=app_password
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

Configuration Steps

1. Prepare Email Account

   • Create dedicated email account
   • Enable IMAP access

2. Get App Password (Gmail example)

   • Enable 2-Step Verification
   • Google Account → Security → App passwords
   • Generate dedicated password

3. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

---

11. Matrix

Required Environment Variables

MATRIX_HOMESERVER=https://matrix.org
MATRIX_ACCESS_TOKEN=syt_xxxxx
MATRIX_ALLOWED_USERS=@user:matrix.org

Configuration Steps

1. Register Bot Account

   • Register a new account on homeserver

2. Get Access Token

   • Element → Settings → Help & About → Advanced → Access Token

3. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

E2EE Support

For end-to-end encryption support:

pip install mautrix[encryption]
# Requires libolm installation

---

12. Mattermost

Required Environment Variables

MATTERMOST_URL=https://your-mattermost.com
MATTERMOST_TOKEN=your_bot_token
MATTERMOST_ALLOWED_USERS=user_id_1,user_id_2

Configuration Steps

1. Enable Bot Accounts

   • System Console → Integrations → Bot Accounts → Enable

2. Create Bot

   • Integrations → Bot Accounts → Add Bot Account
   • Save Token

3. Invite Bot to Channel

4. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

---

13. Home Assistant

Required Environment Variables

HASS_TOKEN=your_long_lived_access_token

Configuration Steps

1. Create Long-Lived Access Token

   • Home Assistant → Profile → Long-Lived Access Tokens → Create

2. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Features

• Dual integration: Gateway platform (events) + Smart home tools (4 LLM-callable tools)

---

14. SMS (Twilio)

Required Environment Variables

TWILIO_ACCOUNT_SID=ACxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_PHONE_NUMBER=+1234567890

Configuration Steps

1. Register Twilio Account

   • Get Account SID and Auth Token
   • Purchase phone number

2. Configure Webhook

   • Set message webhook: https://your-server:8080/webhooks/twilio

3. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Important Notes

• Requires publicly accessible server
• Plain text transmission, no encryption

---

15. BlueBubbles (iMessage)

Required Environment Variables

BLUEBUBBLES_SERVER_URL=http://your-mac:1234
BLUEBUBBLES_PASSWORD=your_password

Configuration Steps

1. Install BlueBubbles Server on Mac

   • Download and install BlueBubbles
   • Sign in with Apple ID

2. Get Server URL and Password

3. Save Configuration

   # Edit ~/.hermes/.env
   hermes gateway
   

Important Notes

• Requires an always-on Mac

---

16. Webhooks

Required Environment Variables

WEBHOOK_ENABLED=true
WEBHOOK_SECRET=your_hmac_secret

Configuration Steps

1. Enable Webhook in .env

2. Define Routes

   • Define in config.yaml
   • Or use hermes webhook subscribe for dynamic creation

3. External Service Calls

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

---

17. Open WebUI / API Server

Required Environment Variables

API_SERVER_ENABLED=true
API_SERVER_KEY=your_bearer_token

Configuration Steps

1. Enable API Server

   # Edit ~/.hermes/.env
   hermes gateway
   

2. Start Open WebUI

   docker run -d -p 3000:8080 \
     -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
     -e OPENAI_API_KEY=your_bearer_token \
     ghcr.io/open-webui/open-webui:main
   

Important Notes

• URL must include /v1 suffix

---

Troubleshooting

Callback Verification Failed

• Check public certificates and TLS chain
• Check if reverse proxy rewrites paths
• Review Hermes logs for signature/timestamp errors

Bot Not Responding

• Check event subscriptions are complete
• Verify Hermes service health (hermes status)
• Check for platform rate limiting

Permission Errors

• Check ALLOWED_USERS configuration
• Verify platform permissions are complete

---

Important: Restart Gateway After Configuration

After completing any messaging platform configuration, you need to restart Hermes Gateway for the changes to take effect:

hermes gateway restart

If using systemd to manage the service:

sudo systemctl restart hermes-gateway

---

Conclusion

Hermes Agent supports 17 messaging platforms, and you can choose one or more based on your team's needs. For users in China, Feishu is recommended; for international users, Telegram is recommended.

For detailed platform comparisons, read WeChat VS Feishu VS Telegram Comparison.

For managed deployment services, see View Plans; for technical support, Contact Us.