Complete Feishu Setup Guide: Connect Hermes Agent to Feishu Bot

Hermes Agent Helperon a month ago

Overview

Feishu (Lark) is an enterprise collaboration platform. Hermes Agent supports conversational interactions with users through Feishu bots. This tutorial will guide you through the complete process from creating a Feishu app to configuring the Hermes Gateway.

🚀 Recommended: Use Feishu Config Helper (3 minutes)

We strongly recommend using the Hermes Agent Feishu Config Helper to configure your Feishu bot!

With the Feishu Config Helper, you only need to:

Manually create a Feishu app (see "Step 1" below)
Get your App ID and App Secret (see "Step 1" below)
Run the Feishu Config Helper - it will automatically complete all Feishu-side configurations (permissions, event subscriptions, etc.)
Configure the App ID and App Secret in the Hermes Service Manager

The Feishu Config Helper saves you 60+ minutes of manual configuration time by automatically handling tedious permission settings and event subscription setup.

If you prefer manual configuration, continue reading the full tutorial below.

Manual setup estimated time: 15-20 minutes

Required information:

App ID (unique application identifier)
App Secret (application secret key)
Feishu User ID (for access authorization)

Step 1: Create a Feishu Enterprise App

1.1 Access Developer Console

Open Feishu Open Platform or Lark Developer
Click "Developer Console" in the top right
Log in with your Feishu/Lark account if not already logged in

1.2 Create Application

On the "My Apps" page, click "Create Custom App"
Fill in the application details:
- App Name: Enter an identifiable name, e.g., "Hermes AI Assistant"
- App Description: Brief description of the app's purpose
- App Icon: Upload an app icon (optional)
Click "Create"

1.3 Get Credentials

After creation, go to the app details page:

Under "Credentials & Basic Info", find:
- App ID: Format like cli_xxxxxxxxxxxxxxxx
- App Secret: Click "Show" to reveal and copy

Save these two values securely - you'll need them for configuration.

Step 2: Configure App Permissions and Features

2.1 Add Bot Capability

Go to "Features" → "Bot"
Enable the "Enable Bot" toggle
Fill in bot information:
- Bot Name: The name users will see
- Bot Description: Brief explanation of bot functionality

2.2 Configure Event Subscription

Go to "Development Settings" → "Events & Callbacks"
Under "Event Subscription", click "Add Event"
Add the following events:
- im.message.receive_v1 (receive messages)

2.3 Configure Request URL (Webhook)

On the "Event Subscription" page:

Find the "Request URL" configuration

Enter your Hermes Gateway callback URL:

https://your-server-ip-or-domain:port/webhook/feishu

Click "Save"

Note: When saving, Feishu will send a verification request to this URL. Make sure the Gateway is running.

2.4 Request Permissions

Go to "Development Settings" → "Permissions & Scopes"
Request the following permissions:
- im:message (get and send messages in chats)
- im:message:send_as_bot (send messages as the bot)
- contact:user.id:readonly (get user IDs)

Step 3: Get Feishu User ID

The Feishu User ID (Open ID or User ID) is used to authorize which users can chat with the bot.

Method 1: Using Feishu Helper (Recommended)

We provide a convenient Feishu Helper tool:

Go to the Feishu Helper page
Download and install the Feishu Helper
Follow the on-page instructions to get your Feishu User ID

Method 2: Via API

In the Feishu Open Platform's "API Explorer"
Call the "Get User Info" endpoint
Extract open_id or user_id from the response

Method 3: Check Message Logs

Complete the configuration below and start the Gateway first
Send a test message to the bot
Check the Gateway logs for the sender's user ID

Step 4: Configure Hermes Gateway

Option 1: Via Hermes Service Manager (Recommended)

If you're using our managed service:

Go to the Hermes Service Manager page
Log in to your server management interface
In the "Config" tab, fill in:
- gateway.feishu.app_id: Your App ID
- gateway.feishu.app_secret: Your App Secret
- gateway.feishu.allowed_users: Authorized user IDs (comma-separated)
Click "Save Changes" to save and restart

Or use the "Feishu Setup" quick configuration tab for one-click setup.

Option 2: Via Interactive Wizard

Run in your server terminal:

hermes gateway setup

Follow the prompts:

Select "Feishu / Lark"
Enter App ID
Enter App Secret
Enter allowed user IDs (comma-separated)

Option 3: Manual Configuration

Edit the ~/.hermes/.env file and add:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_ALLOWED_USERS=ou_xxxxx,ou_yyyyy

Step 5: Publish the App

5.1 Create App Version

On the app details page, click "Create Version"
Fill in version number and update notes
Save the version

5.2 Request Publication

Click "Request Publication"
Select publication scope (recommend "Admin only" for initial testing)
Submit for review

5.3 After Approval

Once approved, authorized users can search for and add your bot in Feishu.

Step 6: Test and Verify

6.1 Start the Gateway

hermes gateway run

Or start as a system service:

hermes gateway install
hermes gateway start

6.2 Send Test Message

Find your bot in Feishu
Send a test message like "Hello"
If configured correctly, the bot will reply with an AI-generated response

Troubleshooting

Q: Bot receives messages but doesn't reply

Possible causes:

User ID not in FEISHU_ALLOWED_USERS
Incorrect App Secret
Gateway not running properly

Solutions:

Check the user ID in Gateway logs
Verify App Secret is correct
Run hermes gateway status to check service status

Q: Event subscription verification fails