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

# Connect LobeHub to Lark

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

> If you are using the Chinese version (飞书), please refer to the [Feishu setup guide](/docs/usage/channels/feishu).

## Prerequisites

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

## Step 1: Create a Lark App

<Steps>
  ### Open the Developer Portal

  Visit [open.larksuite.com/app](https://open.larksuite.com/app) and sign in with your account.

  ### Create an Enterprise App

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

  ![](/blog/assetsa8003533498461272ea15a19407db9f4.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/assetscb1c097430e064f8f99de85e5f078784.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": [
        "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",
        "event:ip_list",
        "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": []
    }
  }
  ```

  <Callout type={'info'}>
    The scopes above are tailored for Lark (international). Some Feishu-specific scopes (e.g. `aily:*`, `corehr:*`, `im:chat.access_event.bot_p2p_chat:read`) are not available on Lark and have been excluded.
  </Callout>

  ![](/blog/assets1aaca5d65761b58564e3f196a91cde3e.webp)

  ### Enable Bot Capability

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

## Step 3: Configure Lark in LobeHub

<Steps>
  ### Open Channel Settings

  In LobeHub, navigate to your agent's settings, then select the **Channels** tab. Click **Lark** from the platform list.

  ### Fill in App Credentials

  Enter the following fields:

  - **App ID** — The App ID from your Lark app
  - **App Secret** — The App Secret from your Lark 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/assets0a25d3ffb02d35f6f28cdfa9da2dccd8.webp)
</Steps>

## Step 4: Set Up Event Subscription in Lark

<Steps>
  ### Open Event Subscription Settings

  Go back to your app in the Lark 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/assets313dfd5108d6fade542c846a87e2aa5a.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**.

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

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

  Click **Save Configuration** again to apply.

  ![](/blog/assetscfcdfc63bc4f8defc06accef81339a5b.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.

  ### Submit for Review

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

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

## Step 6: Test the Connection

Back in LobeHub's channel settings, click **Test Connection** to verify the credentials. Then find your bot on Lark 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 Lark `open_id` (the per-app, per-user identifier — **not** the same as your Lark 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 Lark 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 Lark 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.

> Lark 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 Lark 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 Lark `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 Lark 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 Lark 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 Lark app's App ID (`cli_xxx`)                                                                     |
| **App Secret**             | Yes      | Your Lark 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 Lark Developer Portal                                          |
| **Allowed User IDs**       | No       | Comma- or whitespace-separated Lark `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 Lark `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. Make sure you selected "Lark" (not "飞书") in LobeHub's channel settings.
