---
title: Connect LobeHub to Feishu (飞书)
description: >-
  Learn how to create a Feishu custom app and connect it to your LobeHub agent
  as a message channel, enabling your AI assistant to interact with team members
  on Feishu.
tags:
  - Feishu
  - 飞书
  - Message Channels
  - Bot Setup
  - Integration
---

# Connect LobeHub to Feishu (飞书)

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

> If you are using the international version (Lark), please refer to the [Lark setup guide](/docs/usage/channels/lark).

## Prerequisites

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

## Step 1: Create a Feishu App

<Steps>
  ### Open the Developer Portal

  Visit [open.feishu.cn/app](https://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.

  ![](/blog/assets086849ced67ad95fc3f0d1f509add1bf.webp)

  ### 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.

  ![](/blog/assetsf811b07c10e4a887248fc3f53d085241.webp)
</Steps>

## Step 2: Configure App Permissions and Bot

<Steps>
  ### Import Required Permissions

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

  ```json
  {
    "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"
      ]
    }
  }
  ```

  ![](/blog/assets03aba6c4b7a39ed9b1be75ecd8f335dc.webp)

  ### Enable Bot Capability

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

  ![](/blog/assetsb74a9fc9aecbaa74529cf0fb0da37bca.webp)
</Steps>

## Step 3: Configure Feishu in LobeHub

<Steps>
  ### Open Channel Settings

  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.

  ![](/blog/assetsbc6a72dc53430bbbbeafcc7d921396f4.webp)
</Steps>

## Step 4: Set Up Event Subscription in Feishu

<Steps>
  ### Open Event Subscription Settings

  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.

  ![](/blog/assetsb6f4b163825de58e2b6fe4dba8ef1b26.webp)

  ### (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**.

  ![](/blog/assets05b5684db0f7035e8f0609f6b1b8d85c.webp)

  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.

  ![](/blog/assets3fcf2ee44ffb6be5c3148667f0c1696e.webp)
</Steps>

## Step 5: Publish the App

<Steps>
  ### Create a Version

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

  ![](/blog/assetsbd0ac93d1d3bba86d5da86b9569a6fb1.webp)

  ### 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 on 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](/docs/usage/channels/overview#direct-message-policy) for cross-platform details.

## Configuration Reference

| Field                      | Required | Description                                                                                              |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| **App ID**                 | Yes      | Your Feishu app's App ID (`cli_xxx`)                                                                     |
| **App Secret**             | Yes      | Your Feishu app's App Secret                                                                             |
| **Verification Token**     | No       | Verifies webhook event source (recommended)                                                              |
| **Encrypt Key**            | No       | Decrypts encrypted event payloads                                                                        |
| **Event Subscription URL** | —        | Auto-generated after saving; paste into Feishu Developer Portal                                          |
| **Allowed User IDs**       | No       | Comma- or whitespace-separated Feishu `open_id` values. Global gate — applies to DMs and group @mentions |
| **DM Policy**              | No       | `open` (default), `allowlist`, `pairing`, or `disabled` — who is allowed to DM the bot                   |
| **Group Policy**           | No       | `open` (default), `allowlist`, or `disabled` — where the bot responds to @mentions                       |
| **Allowed Channel IDs**    | No       | Comma- or whitespace-separated Feishu `chat_id` values. Used when Group Policy is Allowlist              |

## 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.
