Feishu / Lark
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:
| 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 |
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
Go to the Feishu Open Platform (or Lark Developer).
Create a custom app and grant the scopes listed above.
Enable the im.message.receive_v1 event under Event Subscriptions.
Select “Use long connection to receive events” instead of setting a request URL.
Copy the App ID and App Secret.
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
Go to the Feishu Open Platform (or Lark Developer).
Create a custom app and grant the scopes listed above.
Enable the im.message.receive_v1 event under Event Subscriptions.
Set the request URL to http://your-host:8080/event (matching your listen_port and listen_path).
Copy the App ID, App Secret, Verification Token, and Encrypt Key (leave encrypt key blank to disable encryption).
Publish the app version and add the bot to the target group chat.
Set use_long_connection: false in your config.
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:
| 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:
| 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.