Connect LobeHub to Feishu (飞书)

By connecting a Feishu channel to your LobeHub agent, team members can interact with the AI assistant directly in Feishu private chats and group conversations.

If you are using the international version (Lark), please refer to the Lark setup guide.

Prerequisites

• A LobeHub account with an active subscription
• A Feishu account with permissions to create enterprise apps

Step 1: Create a Feishu App

Visit open.feishu.cn/app and sign in with your account.

Create an Enterprise App

Click Create Enterprise App. Fill in the app name (e.g., "LobeHub 助手"), description, and icon, then submit the form.

Copy App Credentials

Go to Credentials & Basic Info and copy:

• App ID (format: cli_xxx)
• App Secret

Important: Keep your App Secret confidential. Never share it publicly.

</Steps>

Step 2: Configure App Permissions and Bot

In your app settings, go to Permissions & Scopes, click Batch Import, and paste the JSON below to grant the bot all necessary permissions.

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

Enable Bot Capability

Go to App Capability → Bot. Toggle the bot capability on and set your preferred bot name.

</Steps>

Step 3: Configure Feishu in LobeHub

In LobeHub, navigate to your agent's settings, then select the Channels tab. Click 飞书 (Feishu) from the platform list.

Fill in App Credentials

Enter the following fields:

• App ID — The App ID from your Feishu app
• App Secret — The App Secret from your Feishu app

You don't need to fill in Verification Token or Encrypt Key at this point — you can set them up after configuring the Event Subscription in Step 4.

Save and Copy the Webhook URL

Click Save Configuration. After saving, an Event Subscription URL will be displayed. Copy this URL — you will need it in the next step.

</Steps>

Step 4: Set Up Event Subscription in Feishu

Go back to your app in the Feishu Developer Portal. Navigate to Event Subscription.

Configure the Request URL

Paste the Event Subscription URL you copied from LobeHub into the Request URL field. The platform will verify the endpoint automatically.

Add the Message Event

Add the following event:

• im.message.receive_v1 — Triggered when a message is received

This allows your app to receive messages and forward them to LobeHub.

(Recommended) Fill in Verification Token and Encrypt Key

After configuring Event Subscription, you can find the Verification Token and Encrypt Key at the top of the Event Subscription page under Encryption Strategy.

Go back to LobeHub's channel settings and fill in:

• Verification Token — Used to verify that webhook events originate from Feishu
• Encrypt Key (optional) — Used to decrypt encrypted event payloads

Click Save Configuration again to apply.

</Steps>

Step 5: Publish the App

In your app settings, go to Version Management & Release. Create a new version with release notes.

Submit for Review

Submit the version for review and publish. For enterprise self-managed apps, approval is typically automatic. </Steps>

Step 6: Test the Connection

Back in LobeHub's channel settings, click Test Connection to verify the credentials. Then find your bot in Feishu by searching its name and send it a message to confirm it responds.

Step 7: Set Your Platform Identity (Recommended)

One optional field under Advanced Settings carries a lot of weight in day-to-day use — fill it in once and most surprises go away.

Your Platform User ID

This is your own Feishu open_id (the per-app, per-user identifier — not the same as your Feishu mobile number or email), used by:

• Pairing approval — required when DM Policy is set to Pairing, since /approve <code> is the owner's command and the runtime checks the sender against this ID.
• AI tools push — lets the agent reach you proactively (reminders, notifications) by mapping its internal user reference to your Feishu account.
• Anti-lockout — auto-trusted by Allowed Users, so scoping the bot to teammates won't accidentally lock you out.

To get it: DM the bot once and inspect the inbound event payload — the open_id field on the sender is yours. The Feishu Developer Portal also exposes a User ID lookup that maps mobile/email to open_id. Paste it into Your Platform User ID in LobeHub's Advanced Settings.

Feishu doesn't expose a single "default server" concept that AI tools can pivot on (the bot operates per-tenant via credentials), so the Default Server field is not exposed for Feishu channels.

Access Policies

Two independent policies gate inbound traffic. Both default to Open.

Allowed User IDs (global)

A populated Allowed User IDs field is a global gate — DMs and group @mentions are restricted to listed Feishu open_id values. Empty means "no user-level filter". Read the open_id from the event payload, or copy the User ID displayed in the Feishu Developer Portal.

DM Policy

• Open (default) — Any tenant member can DM the bot (subject to the global allowlist when set).
• Allowlist — DMs require the sender to be in Allowed User IDs. Differs from Open only when the list is empty: Allowlist then fails closed (no DMs).
• Pairing — Same gate as Allowlist, but a non-listed sender receives a one-time pairing code instead of a flat rejection. Approve via /approve <code> and the applicant is auto-appended to Allowed User IDs. Requires Your Platform User ID to be set (the runtime checks the /approve sender against it) and a configured Redis backend.
• Disabled — The bot ignores all DMs and only responds to chat-group @mentions.

Group Policy

Controls which Feishu chat groups the bot will respond in.

• Open (default) — Respond to @mentions in any chat group the bot has been added to.
• Allowlist — Respond only in chats whose chat_id is listed in Allowed Channel IDs (read it from the event payload).
• Disabled — Ignore all group traffic; the bot only responds to DMs.

See the Channels overview for cross-platform details.

Configuration Reference

Troubleshooting

• Event Subscription URL verification failed: Ensure you saved the configuration in LobeHub first, and the URL was copied correctly.
• Bot not responding: Verify the app is published and approved, the bot capability is enabled, and the im.message.receive_v1 event is subscribed.
• Bot ignores DMs: Open Advanced Settings in LobeHub and check DM Policy. If it is Disabled, switch to Open or Allowlist. If it is Allowlist, confirm the sender's open_id is listed in Allowed User IDs.
• Permission errors: Confirm all required permissions are added and approved in the Developer Portal.
• Test Connection failed: Double-check the App ID and App Secret.