This document was written by AI and has been manually reviewed.

Feishu / Lark

The Feishu driver supports two receive modes and sends via the Feishu IM v1 API using lark-oapi.

Feishu (China) and Lark (international) use the same API and the same driver.

App permissions

In the Feishu/Lark developer console, grant the app the following scopes under Permissions & Scopes and publish the app version:

Scope	Purpose
im:message (or im:message:send)	Send messages — required for outgoing bridging
im:message:receive_v1	Receive message events
im:resource (or im:resource:upload)	Upload images and files when forwarding attachments
contact:contact.base:readonly	Resolve sender open_id to a display name and avatar

TIP

If you see Access denied errors in the logs, the app version is missing one or more of the above scopes. Add the required scope(s) under Permissions & Scopes, then publish a new version of the app.

contact:contact.base:readonly is optional — without it, the sender will be shown as their raw open_id.

Receive modes

Long connection / WebSocket (default)

The driver establishes a persistent outbound WebSocket connection to Feishu's servers. No public HTTP endpoint is required — useful for local or firewalled deployments.

Setup

1. Go to the Feishu Open Platform (or Lark Developer).
2. Create a custom app and grant the scopes listed above.
3. Enable the im.message.receive_v1 event under Event Subscriptions.
4. Select "Use long connection to receive events" instead of setting a request URL.
5. Copy the App ID and App Secret.
6. Publish the app version and add the bot to the target group chat.

Feishu pushes events to an HTTP endpoint you expose. The driver starts an aiohttp server on a configurable port.

HTTP webhook

Setup

1. Go to the Feishu Open Platform (or Lark Developer).
2. Create a custom app and grant the scopes listed above.
3. Enable the im.message.receive_v1 event under Event Subscriptions.
4. Set the request URL to http://your-host:8080/event (matching your listen_port and listen_path).
5. Copy the App ID, App Secret, Verification Token, and Encrypt Key (leave encrypt key blank to disable encryption).
6. Publish the app version and add the bot to the target group chat.
7. Set use_long_connection: false in your config.

Public endpoint required

Feishu must be able to reach your HTTP endpoint from the internet. Use a reverse proxy, tunnel (e.g. ngrok / Cloudflare Tunnel), or deploy on a public server.

Config keys

Add under feishu.<instance_id> in config.json:

Key	Required	Default	Description
app_id	Yes	—	Feishu/Lark App ID
app_secret	Yes	—	Feishu/Lark App Secret
use_long_connection	No	true	true = WebSocket long connection; false = HTTP webhook
verification_token	No	""	Event verification token — HTTP webhook mode only
encrypt_key	No	""	Event encryption key — HTTP webhook mode only (leave empty to disable)
listen_port	No	8080	HTTP port to listen on — HTTP webhook mode only
listen_path	No	"/event"	HTTP path for incoming events — HTTP webhook mode only

Long connection example

{
  "feishu": {
    "fs_main": {
      "app_id": "cli_xxxxxxxxxxxx",
      "app_secret": "your_app_secret"
    }
  }
}

HTTP webhook example

{
  "feishu": {
    "fs_main": {
      "app_id": "cli_xxxxxxxxxxxx",
      "app_secret": "your_app_secret",
      "verification_token": "your_verification_token",
      "encrypt_key": "",
      "listen_port": 8080,
      "listen_path": "/event",
      "use_long_connection": false
    }
  }
}

Rule channel keys

Use under channels or from/to in rules.json:

Key	Description
chat_id	Feishu open chat ID, e.g. "oc_xxxxxxxxxxxxxxxxxx"

{
  "fs_main": { "chat_id": "oc_xxxxxxxxxxxxxxxxxx" }
}

You can find the chat ID in Group Settings / the Feishu API Debugging Platform, or from the event payload of any message sent to the bot in that chat.

Feishu Official Document: Chat ID description - includes the detailed instructions to obtain chat id

Notes

• Currently only text messages are received. Other message types (cards, files, stickers) are ignored on the receive side.
• Outgoing attachments are sent as URLs appended to the message text (Feishu file upload via the API requires additional permissions).
• The sender's display name and avatar are resolved via the contact API (contact:contact.base:readonly). Without that scope the sender is shown as their raw open_id.