Chapter 4: Chat Platform Integration

Hermes is installed — now for the most exciting part: moving the cuttlefish into your chat apps. From now on, open Feishu/Telegram/Discord, and the cuttlefish is always on call.

What is Gateway?

Gateway is Hermes Agent's messaging hub. It's a background process that connects to all your configured chat platforms simultaneously:

Feishu ──┐
Telegram ──┤
Discord ──┼──→ Gateway ──→ Hermes AI Agent
Slack ──┤
WhatsApp ──┘

One Gateway process handles all platforms — no need to run a separate service for each.

Platform Overview

Hermes supports 15+ chat platforms:

Platform	Recommendation	Voice	Images	Files	Group Chat	Difficulty
Feishu/Lark	⭐⭐⭐⭐⭐	✅	✅	✅	✅	Medium
Telegram	⭐⭐⭐⭐⭐	✅	✅	✅	✅	Low
Discord	⭐⭐⭐⭐	✅	✅	✅	✅	Low
Slack	⭐⭐⭐⭐	✅	✅	✅	✅	Low
WhatsApp	⭐⭐⭐	✅	✅	✅	❌	Medium
Signal	⭐⭐⭐	✅	✅	✅	❌	Medium
Email	⭐⭐⭐	❌	❌	✅	❌	Low
Matrix	⭐⭐⭐	✅	✅	✅	✅	Medium
DingTalk	⭐⭐⭐	✅	✅	✅	✅	Medium
WeCom (Enterprise WeChat)	⭐⭐⭐	✅	✅	✅	✅	Medium
WeChat	⭐⭐	❌	✅	❌	❌	High
SMS (Twilio)	⭐⭐	❌	❌	❌	❌	Medium
iMessage	⭐⭐⭐	✅	✅	✅	❌	Medium

Recommended Combinations

Users in China: Feishu + Telegram (with VPN) International users: Telegram + Discord

Interactive Configuration Wizard

The easiest way is to use the hermes gateway wizard:

hermes gateway

The wizard guides you through selecting a platform, entering tokens, and automatically saving the configuration. After configuration, Gateway restarts automatically.

Manual Configuration

You can also directly edit the ~/.hermes/.env file, which is suitable for batch deployment or scripted scenarios.

---

Feishu / Lark Configuration (Recommended for Users in China)

Feishu is the mainstream enterprise collaboration platform in China. Hermes receives messages via the Feishu Open Platform's WebSocket long connection — no need to expose a public webhook URL. It works in both direct message and group chat scenarios.

Create a Feishu Application

1. Open the Feishu Open Platform, log in, and click "Create Enterprise Custom App"
2. Fill in the application name (e.g., "My AI Cuttlefish"), description, and choose an app icon
3. Go to the app details page → "Credentials & Basic Info", and copy and securely store the App ID (format cli_xxx) and App Secret

Security Reminder

Keep your App Secret confidential. Do not commit it to code repositories or share it publicly. If it is accidentally leaked, reset it immediately on the Open Platform.

Lark (International Version) Users: Visit open.larksuite.com/app, and set FEISHU_DOMAIN to lark in subsequent configuration.

Configure Application Permissions

Go to the app's "Permission Management" page, click "Batch Import", and paste the following JSON:

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg:readonly",
      "im:resource",
      "im:chat",
      "im:chat:readonly",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.base:readonly",
      "contact:user.employee_id:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write"
    ],
    "user": [
      "im:message",
      "im:message:readonly",
      "im:chat",
      "im:chat:readonly",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

These permissions cover core functionality including message sending and receiving, group chat management, contact access, and card messages. Some permissions may fail to import due to Feishu version differences — skip them; they won't affect core messaging functionality.

Enable the Bot Capability & Configure Event Subscription

1. Go to "App Capabilities" → "Bot", enable the Bot capability, and set the Bot name and description
2. Go to the "Event Subscription" page:
   • Select "Use long connection to receive events" (WebSocket mode)
   • Add the event: im.message.receive_v1

Note

Make sure you've completed the Hermes-side configuration and started the Gateway, otherwise the long connection settings may not save.

Publish the Application

Go to "Version Management & Release" → Create an app version → Submit for review and publish. Enterprise Custom Apps are typically approved automatically.

Install Dependencies

Critical: venv vs System Python

The Hermes binary uses the Python interpreter inside the project's venv. All pip installs must target the venv, otherwise installed packages won't be visible to Hermes.

# For source installation users
/path/to/hermes-agent/venv/bin/pip install lark_oapi websockets python-socks

# For one-click installer users
hermes pip install lark_oapi websockets python-socks

Known Issue: Missing python-socks

If your system environment has SOCKS proxy variables set (e.g., ALL_PROXY), the Lark SDK will require the python-socks package at import time. If it's not installed in the venv, Gateway startup will fail:

[Lark] [ERROR] connect failed, err: python-socks is required to use a SOCKS proxy

Fix: Make sure it's installed in the correct Python environment — venv/bin/pip install python-socks, not the system pip.

Configure Hermes

Option A: Interactive Configuration

hermes gateway
# Select Feishu / Lark
# Enter your App ID and App Secret when prompted
# Select WebSocket mode

Option B: Manual Configuration

Edit ~/.hermes/.env and add:

# Feishu / Lark basic configuration
FEISHU_APP_ID=cli_xxxxxxxxxx         # Replace with your App ID
FEISHU_APP_SECRET=***    # Replace with your App Secret
FEISHU_DOMAIN=feishu                 # feishu (China) or lark (International)
FEISHU_CONNECTION_MODE=websocket     # Recommended: WebSocket long connection mode

# User access control
GATEWAY_ALLOW_ALL_USERS=true         # Testing phase: allow all users
# For production, change to false and configure the whitelist:
# FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy  # Users' open_id, comma-separated

Start the Gateway

hermes gateway start

After starting, check the logs to confirm the WebSocket connection is established:

tail -f ~/.hermes/logs/gateway.log

A successful log entry should contain:

[Lark] [INFO] connected to wss://msg-frontier.feishu.cn/ws/v2?...

Search for your Bot's name in Feishu and send a test message. If Cuttlefish replies, the connection is successful!

Set Home Chat

In the Feishu chat, send:

/set-home

This sets the current chat as the Home Chat. Scheduled task (Cron) results and cross-platform notifications will be sent here.

You can also pre-configure it:

# In ~/.hermes/.env
FEISHU_HOME_CHAT_ID=oc_xxxxxxxxxxxxx

Group Chat Policy

The bot responds in group chats only when @mentioned by default. Control group chat behavior via environment variables:

# always: respond to all messages in groups (requires @bot)
# mention_only: only respond to @bot messages
# ignore: completely ignore group chats
FEISHU_GROUP_POLICY=always

Security Reminder

In production, always configure FEISHU_ALLOWED_USERS — do not use GATEWAY_ALLOW_ALL_USERS=true. Otherwise, anyone who can reach the bot can use your Agent.

Common Startup Errors

Error Message	Cause	Solution
python-socks is required	Missing dependency or wrong Python environment	venv/bin/pip install python-socks
Unauthorized user	User allowlist not configured	Set GATEWAY_ALLOW_ALL_USERS=true or FEISHU_ALLOWED_USERS
Connection timeout	Network/firewall issue	Confirm access to wss://msg-frontier.feishu.cn
App ID/Secret error	Credential misconfiguration	Check that values in .env match the open platform

Operations Command Quick Reference

hermes gateway start      # Start background service
hermes gateway stop       # Stop service
hermes gateway restart    # Restart service
hermes gateway status     # View status
hermes doctor             # Health check
hermes doctor --fix       # Auto-fix issues
tail -f ~/.hermes/logs/gateway.log  # Real-time logs

Configuration Reference

Environment Variable	Description	Default
FEISHU_APP_ID	Feishu App ID	-
FEISHU_APP_SECRET	Feishu App Secret	-
FEISHU_DOMAIN	API domain (feishu or lark)	feishu
FEISHU_CONNECTION_MODE	Connection mode (websocket or webhook)	websocket
FEISHU_ALLOWED_USERS	Allowed user open_id list (comma-separated)	-
GATEWAY_ALLOW_ALL_USERS	Allow all users (true/false)	false

Telegram Configuration

Step 1: Create a Bot

1. Search for @BotFather in Telegram, send /newbot
2. Follow the prompts to set the bot name and username
3. Record the returned Bot Token (format like 123456789:ABCdefGHI...)

Step 2: Configure Hermes

Edit ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456...wxyz

Step 3: Start

hermes gateway start

Open Telegram, find your bot, and send a message to test.

---

Discord Configuration

Step 1: Create a Discord Application

1. Open Discord Developer Portal
2. Click "New Application", fill in a name
3. Go to the "Bot" page, click "Add Bot"
4. Click "Reset Token", copy the Bot Token
5. Under "OAuth2 → URL Generator", check bot, copy the invite link
6. Use the link to invite the Bot to your server

Step 2: Configure Hermes

Edit ~/.hermes/.env:

DISCORD_BOT_TOKEN=MTIzND...xxxx

Step 3: Start

hermes gateway start

---

Gateway Service Management

Linux (systemd)

# Install as system service (auto-start on boot)
hermes gateway install --system

# Start / Stop / Restart / View status
hermes gateway start
hermes gateway stop
hermes gateway restart
hermes gateway status

# View logs
hermes gateway logs

macOS (launchd)

# Install as user service
hermes gateway install

# Start / Stop / Restart
hermes gateway start
hermes gateway stop
hermes gateway restart

TIP

The generated plist file on macOS is located at ~/Library/LaunchAgents/ai.hermes.gateway.plist.

---

Multi-Platform Integration

You can configure multiple platforms simultaneously in ~/.hermes/.env:

# Feishu
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=***
FEISHU_MODE=websocket

# Telegram
TELEGRAM_BOT_TOKEN=***

# Discord
DISCORD_BOT_TOKEN=***

# Enable all at once
GATEWAY_ALLOW_ALL_USERS=true

When Gateway starts, it connects to all configured platforms simultaneously, routing messages to the same AI Agent.

---

Common Issues

Problem	Cause	Solution
Feishu bot not responding	Permissions not configured	Check app permissions, ensure im:message is enabled
WebSocket connection failed	Missing websockets package	pip install websockets
Telegram Bot unresponsive	Token error	Re-obtain Token from BotFather
Discord Bot offline	Not invited to server	Use OAuth2 link to invite Bot
Gateway startup error	Port conflict / env var error	Check with hermes doctor
Security warning: no allowed users	ALLOW_ALL_USERS=true	Configure GATEWAY_ALLOWED_USERS

Further Reading

• Official docs: Messaging Gateway
• Feishu configuration: Feishu / Lark Setup
• Telegram configuration: Telegram Setup
• Discord configuration: Discord Setup

---