Lark (Feishu) Integration
Table of contents
- Features
- Setup Guide
- Configuration Reference
- Commands
- Access Control (ACL)
- Private Chat (P2P)
- Lark Tools Sharing One App
- Technical Details
- Troubleshooting
- Next Steps
Lark/Feishu (飞书) integration for enterprise communication.
Features
- Bidirectional Communication: Send and receive messages via Lark bot
- Session Binding: Bind Lark chats to chat.nvim sessions
- Markdown Rendering: Replies arrive as interactive cards, not raw markup
- Access Control: Whitelist / blacklist by
open_id, manageable from the chat - Private Chat (P2P): Talk to the bot in a 1:1 chat, no
@mentionneeded - Multi-chat: Several groups and private chats polled side by side, each with its own message cursor and optional session binding
- Isolated Workspaces: Every private chat gets its own working directory, so two peers never share a file tree
- Shared App: The same credentials power the
bitable,lark_sheetsandlark_docxtools
Setup Guide
Five steps in the Lark open platform, then one local config:
- Create a custom app → get
App ID/App Secret - Enable the bot capability
- Add permissions
- Publish and release a version (needs admin approval)
- Add the bot to a chat and read the
chat_id - Configure chat.nvim
chat.nvim polls the Lark Open API. You do not need to configure “Event Subscriptions” (事件订阅) or a request URL in the developer console — leave those empty.
1. Create the app
- Open https://open.feishu.cn/app
- Click Create custom app (创建企业自建应用)
- Fill in a name and description, then submit
- Open the app → Credentials & Basic Info (凭证与基础信息)
- Copy App ID (
cli_xxxxxxxx) and App Secret
Keep
app_secretsecure. Never commit it to version control — prefer anenvvar or a local file that is git-ignored.
2. Enable the bot capability
The integration talks to the chat through a bot, so the capability must be on:
- App → Add app capability (添加应用能力)
- Enable Bot (机器人)
- Optionally set a bot name and avatar — this is what users see in the group
Without this step the bot info call returns no bot and messages sent to the chat fail with a “bot not available” style error.
3. Add permissions
App → Permissions & Scopes (权限管理) → search and enable:
| Permission | What it is used for |
|---|---|
im:message |
Send messages and read messages the bot receives |
im:message.group_msg |
Read messages in groups (the polling endpoint) |
im:message.group_msg is a sensitive scope: the tenant admin has to
approve it. This is the single most common reason a fresh app replies nothing
— the scope exists but is still pending approval.
Two optional scopes, needed only for specific features:
| Permission | When it is needed |
|---|---|
im:chat (readonly) |
Listing the chats the bot joined, to find a chat_id |
contact:user.id:readonly |
Resolving ACL entries written as email / mobile to open_id |
Scopes for the document tools live in Lark Tools
below. The exact scope names can differ slightly between tenants: if a name is
not listed in your console, search the keyword part (im:message, contact,
bitable, sheet, docx) and check the requirement in the
API Explorer.
4. Publish and release a version
Scopes only take effect after a version is released and approved:
- App → Version Management & Release (版本管理与发布)
- Create version → fill in the version number and changelog
- Set Availability (可用范围) — who in the tenant may use the app
- Submit for release; an admin approves it in the admin console (管理员后台 → 应用管理 → 待审批)
After approval, reopening the permission page shows the scopes as enabled. Editing scopes later requires a new version — this is why “I added the permission but it still fails” usually means version not re-published.
5. Add the bot to a chat and get the chat_id
- In Lark, open the target group → Settings (群设置) → Bots (群机器人) → Add bot → pick your app
- Send a message in the group that
@mentionsthe bot - Read the
chat_id(oc_xxxxxxxx):
- API Explorer (simplest): call
GET /open-apis/im/v1/chatsin https://open.feishu.cn/api-explorer — every chat the bot joined is listed with itschat_id - Runtime log: after one
@mention, print the raw payloads with:lua vim.print(require('chat.log').view_all())
chat_idstarts withoc_. A useropen_id(ou_...) or the chat’s display name is not a substitute. For a one-to-one chat, theoc_id is created on first contact — read it from the first message payload.
6. Configure chat.nvim
require('chat').setup({
integrations = {
lark = {
app_id = 'cli_xxxxxxxxxxxx',
app_secret = 'YOUR_APP_SECRET',
chat_id = 'oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
},
},
})
Then bind the current session with :Chat bridge lark. ACL and the full option
list are in Configuration Reference.
Configuration Reference
| Option | Type | Default | Description |
|---|---|---|---|
integrations.lark.app_id |
string |
— | App ID, required |
integrations.lark.app_secret |
string |
— | App Secret, required |
integrations.lark.chat_id |
string |
— | Target chat (oc_...), required |
integrations.lark.acl.mode |
string |
'allow_all' |
allow_all | whitelist | blacklist |
integrations.lark.acl.whitelist |
string[] |
{} |
Users allowed to talk (whitelist mode) |
integrations.lark.acl.blacklist |
string[] |
{} |
Users blocked (blacklist mode) |
integrations.lark.acl.admins |
string[] |
{} |
Users allowed to run /allow, /deny and /acl |
integrations.lark.p2p.allow |
string[] |
{} |
Users allowed to use private chat (default: deny) |
integrations.lark.p2p.greeting |
string |
see below | Text sent when a private chat is opened |
integrations.lark.p2p.auto_create |
boolean |
true |
Open a private chat for allowed users on connect |
integrations.lark.p2p.cwd_root |
string |
first allowed_path |
Root for per-chat p2p workspaces |
Every ACL list accepts an open_id (ou_...), an email address, or a mobile
number. open_id entries cost zero API calls; email / mobile entries are
resolved once on connect and then cached. The same is true for p2p.allow.
p2p.cwd_root is where private-chat workspaces are created; leave it unset to
derive the root from allowed_path. See
Isolated workspaces for the details.
Complete example:
require('chat').setup({
integrations = {
lark = {
app_id = 'cli_xxxxxxxxxxxx',
app_secret = 'YOUR_APP_SECRET',
chat_id = 'oc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
acl = {
-- allow_all (default) | whitelist | blacklist
mode = 'whitelist',
-- users allowed to talk to the bot (whitelist mode)
whitelist = { 'ou_xxx', '[email protected]' },
-- users blocked from the bot (blacklist mode)
blacklist = {},
-- users allowed to run /allow, /deny and /acl
admins = { 'ou_admin' },
},
p2p = {
-- users allowed to open a private chat, deny by default.
-- Omit this to fall back to acl.admins + acl.whitelist.
allow = { 'ou_xxx' },
-- text sent when a private chat is opened
greeting = 'Hi, this is the chat.nvim bot. Reply here to talk to Neovim.',
-- open a private chat for the allowed users on connect (default: true)
auto_create = true,
-- root for the per-chat workspaces (default: first allowed_path entry)
-- each private chat works in <cwd_root>/lark-<chat_id>
cwd_root = '/home/me/projects',
},
},
},
})
Commands
| Command | Description |
|---|---|
:Chat bridge lark |
Bind the current session to the Lark chat |
/allow @user |
In-chat: grant the mentioned user access (admins) |
/deny @user |
In-chat: revoke access from the user (admins) |
/acl |
In-chat: reply with the current mode and id lists |
The in-chat commands are recognised only when sent by a configured admin, and
only when the message @mentions the bot. Requests from non-admins are dropped
silently — no reply — so the group is not spammed.
Persistence and revocation
/allow and /deny write the ACL to the state file the moment they change
anything — save_state() runs inside the command, before the reply goes out —
so the edit is on disk even when Neovim is killed right after. They survive
restarts without editing the config, and they take precedence over the
configured acl.mode: an admin can blacklist someone even while running in
allow_all.
| Step | What happens |
|---|---|
/allow @user |
the resolved open_id is added to the runtime whitelist and removed from the runtime blacklist |
/deny @user |
the resolved open_id is added to the runtime blacklist and removed from the runtime whitelist |
| save | lark.json gains acl.whitelist / acl.blacklist arrays, sorted by open_id |
| restart | connect loads the file and both lists are restored before the first poll |
Neither command edits the config: acl.whitelist / acl.blacklist in your
setup stay exactly as written, and the runtime lists are stored beside them.
Both lists are stored as open_ids, even when the command was given an
email or a mobile number: @alice is resolved to ou_alice first, so the
state file only ever contains ou_.... The resolved-identity cache is
persisted as well, so a restart does not re-issue the lookup behind it.
The state file is read by
connect, not when the module is loaded — so before:Chat bridge larkhas run in the current Neovim, the runtime lists are empty andget_acl()returns the configured entries only. Connecting is enough to restore them; no command is required.
Only the message cursors are reset on start (see Multiple chats at once); the ACL lists are untouched by that reset.
Config and runtime entries are two layers
The configured acl.whitelist / acl.blacklist and the runtime entries are
merged, not overwritten, and a runtime entry wins:
- a runtime grant beats
mode = 'blacklist' - a runtime deny beats
mode = 'allow_all' - removing an entry from the config does not revoke a runtime grant, and a runtime grant cannot be cancelled through the config at all
Revoke in the layer that holds the entry:
| Goal | Do this | Side effect |
|---|---|---|
Undo one /allow @user |
/deny @user |
the user also lands in the runtime blacklist, so allow_all will not re-admit them |
| Erase a user completely | :Chat unbridge lark, delete their ou_... from both arrays in lark.json, restart |
none — indistinguishable from a user that was never granted |
| Undo a config edit | edit the config | runtime entries stay as they are |
The connected process keeps the state in memory, so a hand edit of lark.json
is overwritten by the next save_state(); unbind first, or edit while Neovim
is closed.
Access Control (ACL)
By default everyone in the bound chat may talk to the bot. Set
integrations.lark.acl (see the example above) to
restrict who can trigger replies.
| Mode | Behaviour |
|---|---|
allow_all |
Default. Everyone in the chat may talk to the bot. |
whitelist |
Only the listed open_ids (plus admins) may talk to it. |
blacklist |
Everyone except the listed open_ids may talk to it. |
Notes:
- Admins always pass. An admin bypasses the ACL, so a whitelist that locked them out can still be repaired from inside the group.
- Recent speakers are cached. Every non-bot speaker is recorded in the
state file (up to 30, newest first) and exposed through
require('chat.integrations.lark').get_recent_senders(), so open_ids can be picked instead of copied out of the open platform console. - Unresolved entries fail safely. If an email / mobile cannot be resolved
(missing permission or offline), it never matches: fail-closed for
admins/whitelist, fail-open forblacklist. The failure is logged at connect time together with the affected entries. - App scope still applies. The Lark admin console “app availability” setting is the outer, coarse-grained control; the ACL here is the fine one.
Private Chat (P2P)
A private chat is a normal oc_... conversation, so it is polled exactly like
a group. Two things differ:
- No
@mentionis required. The message is addressed to the bot by definition, soSkip message (not mention)never applies. - Access is deny-by-default.
acl.mode = 'allow_all'is a statement about the bound group and does not let anyone in the tenant open a DM. Setintegrations.lark.p2p.allow; when that list is absent,acl.admins ∪ acl.whitelist ∪ runtime whitelistis used instead.
Opening a private chat
A polling bot cannot learn the oc_ id of a p2p conversation from an incoming
message — there is no cursor for a conversation it does not know yet. So the
conversation is created from this side, through the API:
-- returns the p2p chat_id once the conversation exists
require('chat.integrations.lark').create_p2p('ou_xxxxxxxx', function(ok, result)
if ok then
print('p2p chat_id: ' .. result)
end
end)
The call does three things:
- sends
p2p.greetingwithreceive_id_type=open_id(this is the message the user sees, nothing is sent twice) - reads that message back (
GET /im/v1/messages/{message_id}) to obtain thechat_id - registers the container as
chat_type = 'p2p', so the poller starts reading it
create_p2p refuses an open_id that p2p.allow does not list, and returns
the existing chat_id when the conversation is already known (no greeting is
re-sent).
Automatic provisioning
You normally do not have to call create_p2p yourself. On connect the
integration walks the curated allow-list and opens a p2p chat for everyone in
it that does not have one yet:
| Source | Provisioned |
|---|---|
p2p.allow when set |
yes |
otherwise acl.admins |
yes |
acl.whitelist (the wider fallback) |
no |
acl.whitelist is excluded on purpose: provisioning sends a greeting, so a
long whitelist would be spammed on every connect. Those users can still open
the chat themselves.
/allow @user also provisions immediately, so a freshly granted admin can DM
the bot without waiting for a restart.
Every provisioned container gets its own session (lark-<chat_id>) right
away, so the private chat has its own context from the first message.
integrations.lark.p2p.auto_create = false turns automatic provisioning off —
create_p2p still works on demand.
" manually provision without restarting
:lua require('chat.integrations.lark').provision_p2p()
Replies to a p2p chat are sent with
receive_id_type=open_idto the registered peer, so the container id is only needed for polling. A message arriving in that container from anybody other than the registered peer is dropped.
Isolated workspaces
A private chat is one person talking to the bot alone, so two peers must never
share a working directory: they would see each other’s files, and one user’s
edits — or a git checkout — would land in another user’s tree.
Each p2p chat therefore works in <cwd_root>/lark-<chat_id>:
| Chat type | Working directory |
|---|---|
| group | the Neovim cwd (deliberately shared) |
| p2p | <cwd_root>/lark-<chat_id> |
cwd_root comes from integrations.lark.p2p.cwd_root; when that is unset the
first allowed_path entry is used. The fallback is deliberate — a workspace
outside allowed_path would be refused by every file tool, and keeping the root
inside the allowed tree means the isolation never widens what the bot may touch.
With neither configured the workspace is skipped and the session keeps the
Neovim cwd, which is what older versions always did.
When cwd_root points outside allowed_path (an absolute root of its own), the
directory is registered into allowed_path at runtime, so the file tools accept
it without the user repeating the path in config. Registration is runtime-only:
it never touches the config file and does not widen the allowed tree on the next
start.
Creating and registering both run on every binding lookup, not only once at
provisioning. The runtime entry does not survive a restart, and the directory may
have been deleted while the plugin was down — so both are repaired the next time
the chat resolves its session. read_file, find_files and the git tools all
reject a missing or unregistered directory, which is why this has to happen
before a chat can work at all.
The session’s working directory is assigned once, when the session is created. Re-binding a chat to an existing session keeps it in the directory it already has (and
cwd_rootchanges do not migrate it), so a live workspace is never moved under the running request. To relocate a chat, delete its session first. Creating and registering the directory itself is not a one-off: see above.
The name is sanitized to a single path segment, so an unexpected chat_id can
not escape the root.
Multiple chats at once
Every chat keeps its own message cursor, so an active group can no longer
starve a quiet private chat (a single shared start_time used to skip it).
Chats are polled sequentially, one request at a time.
The cached cursor is reset to “now” on every start, before the first poll
and immediately written back to the state file. The cursor records where the
previous run stopped, not a backlog to replay: resuming from an hours-old
start_time would make the first tick fetch everything sent while the plugin
was down and answer it in one burst. Only messages arriving after the plugin
started are considered; ids left over from the previous session stay in
processed_ids, so the boundary between runs is still guarded.
Bindings are per chat as well: /session inside a chat binds that chat only,
while :Chat bridge lark keeps its platform-level meaning and addresses the
configured chat_id.
Unbinding a session clears both levels — the platform-level binding and every
per-chat binding pointing at that session — so a p2p chat cannot keep answering
after :Chat unbridge lark reported success.
A binding whose session was deleted is dropped and recreated on next use rather
than returned: the conversation keeps its stable derived id (lark-<chat_id>),
so it resumes with a working session instead of silently writing replies into a
session that no longer exists. Bindings set by hand to a session this module did
not derive are left untouched.
Lark Tools Sharing One App
The credentials under integrations.lark are reused by the Lark tools, so a
single app serves both chat and document automation. Enable the scope only for
the tools you actually use, then release a new version:
| Tool | Scope | Documents |
|---|---|---|
bitable |
bitable:app |
bitable |
lark_sheets |
sheets:spreadsheet |
lark_sheets |
lark_docx |
docx:document |
lark_docx |
Technical Details
- API: Lark Open API (
https://open.feishu.cn/open-apis),tenant_access_tokenauthentication refreshed 5 minutes before expiry and shared with the tools - Polling: every 3 seconds,
page_size=50, newest first, usingstart_timefrom the last seen message. Each chat (group or p2p) keeps its own cursor, and chats are polled one request at a time - Reply Trigger: in groups the bot only answers when
@mentioned(mentions[].idequals the botopen_id); in a p2p chat no mention is required - Working Directory: a p2p session starts in
<cwd_root>/lark-<chat_id>(see Isolated workspaces); groups keep the Neovim cwd - Message Limit: 30,720 characters per chunk; longer replies are split
- Message Format: interactive card (schema 2.0) with a
markdownelement - State Persistence:
stdpath('data')/chat.nvim/integration/lark.json(respectsstorage_dirwhen set) — holds the per-chat cursors and session bindings, runtime ACL entries, recent senders and the resolved identity cache. A state file written by an older version (nocontainerskey) still loads: the configuredchat_idbecomes the single container, resuming at the oldlast_message_time
Troubleshooting
The bot never replies
Check in the order failures actually happen:
- Bot capability enabled? (Step 2) — without it no message is delivered.
im:message.group_msgapproved? A sensitive scope needs admin sign-off; “added but not approved” looks identical to “not added”.- Version released after the scope change? Scopes are frozen per version.
- Bot added to the chat? It must be a member of the conversation.
- Did the message
@mentionthe bot? Mentions are required in groups. chat_idcorrect (oc_...)? A useropen_idor a chat name will be accepted by the config but silently fetches nothing.- Sender passes the ACL?
allow_allby default, so this is rare.
Then read the log — it names the actual cause:
:lua vim.print(require('chat.log').view_all())
Look for [Lark] Skip fetch, [Lark] Skip send or skip message lines.
A private chat gets no reply
p2p is deny-by-default, so a silent chat is usually the expected behaviour:
- Is the sender in
p2p.allow? A missing list falls back toacl.admins ∪ acl.whitelist; an explicit list is the whole policy - Was the conversation ever opened? The
oc_id is only known aftercreate_p2p()— or after automatic provisioning on connect — and an unknown chat is never polled.p2p.auto_create = falsedisables the automatic path, so only a manualcreate_p2p()registers the chat - Did the greeting go out? Look for a
[Lark] Skip send/[Lark] Skip fetchline with thereceive_id_type=open_idrequest, or a[Lark] p2p provisioning skipped (<open_id>)debug line - Is the polled container id the same one?
get_containers()lists every chat the bot reads; a p2p entry must carrychat_type = 'p2p'
[Lark] Skip p2p message (peer not allowed) and
[Lark] p2p sender mismatch name a rejected message directly.
File tools refuse the p2p workspace
The workspace is created and registered into allowed_path automatically
whenever the chat resolves its session, so this is rare — it usually means the
directory could not be created:
- Is
p2p.cwd_root(or the firstallowed_path) pointing at the right place? The session works in<cwd_root>/lark-<chat_id> - Look for
[Lark] Could not create workspace— an unwritable root falls back to the session default instead, and no registration takes place - Was the session created before
cwd_rootwas set? The session’s working directory is fixed at creation; delete the session so the next message provisions it again in the new root - Does
allowed_pathreject.git? A workspace under a.gitdirectory is refused by design and is never registered
Authentication errors
Symptom: Cannot authenticate with Lark API (Invalid access token).
Solution:
- Verify
app_idandapp_secretare correct (the secret is shown only once; regenerate it if lost) - Confirm the app is released and approved
- Read the log for the token response — transport failures (DNS, TLS, proxy) are reported separately from API errors, and a silent curl failure leaves an empty response body
Missing scope
Symptom: no permission or code 1254005 in the response body.
Solution: enable the scope, then create and release a new version. Permissions never apply retroactively to an existing version.
An ACL user never matches
Solution:
- Prefer
open_id(ou_...) — it needs no lookup - If you used an email / mobile, enable
contact:user.id:readonlyand reconnect; the cache only resolves on connect - Compare the logged
unresolved ACL entrieslist against the config - Make sure the message really comes from that user — app (bot) messages are skipped before the ACL is checked
Next Steps
- Discord Integration - Setup Discord bot
- Telegram Integration - Setup Telegram bot
- IM Integration Overview - All IM integrations
</Content>