lark-im
飞书即时通讯:收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送交互卡片(Interactive Card)。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶(添加/移除/查询置顶会话)、管理标签数据、发送交互卡片时使用。
SKILL.mddoubao/skills/lark-im/SKILL.md
GitHubim (v1)
Core Concepts
- Message: A single message in a chat, identified by
message_id(om_xxx). Supports types: text, post, image, file, audio, video, sticker, interactive (card), share_chat, share_user, merge_forward, etc. - Chat: A group chat or P2P conversation, identified by
chat_id(oc_xxx). - Thread: A reply thread under a message, identified by
thread_id(om_xxx or omt_xxx). - Reaction: An emoji reaction on a message.
- Flag: A bookmark on a message or thread.
- Feed Shortcut: A chat pinned to the current user's feed sidebar, identified by
feed_card_id(anoc_xxxopen_chat_id for CHAT type). - Feed Group: A tag that groups feed cards in the feed list, identified by
feed_group_id(ofg_xxx). Members are feed cards, each identified byfeed_id+feed_type. Two types:normal(members managed explicitly) andrule(members auto-derived from rules).
Resource Relationships
Chat (oc_xxx)
├── Message (om_xxx)
│ ├── Thread (reply thread)
│ ├── Reaction (emoji)
│ └── Resource (image / file / video / audio)
└── Member (user)
Important Notes
AppLink and Share Links
Messages may contain navigation links, shared message snapshots, or links to other resources. When reading or summarizing messages, read linked content needed for the task rather than treating the link label as its contents. A message's own message_app_link opens that message; links embedded in its content may reference additional material. Follow AppLink identification and reading to identify the resource and choose the reading workflow.
When returning links, prefer CLI-returned values: use chat_app_link to open joined conversations, message_app_link to open messages, and share_link to invite others to groups. If manually building a joined-conversation AppLink, use https://<applink_host>/client/chat/open?openChatId=<oc_xxx>, never chatId=<oc_xxx> or lark://...chat_id=<oc_xxx>.
Sender Name Resolution
When fetching messages (+chat-messages-list, +threads-messages-list, +messages-mget, +messages-search), the CLI shows a display name for message senders:
- Server-provided name: the read APIs return
sender_name(plus the full-i18nsender_i18n_namesmap) on each messagesender; the CLI surfaces it as the sender'snamefor message senders. No name lookup and no extra permission are needed — no contact scope and noapplication:bot.basic_info:read. - Fallback to id: when the server does not provide a name, the sender is shown by its id and the command still exits 0. There is no contact-directory fallback.
The raw sender_name is not duplicated in output (its value is in name); the full sender_i18n_names map (all locales) is preserved for consumers that need a specific language, alongside an optional open_bot_id (ou_) for bot senders aligned with the message-receive event channel. System messages (msg_type: system) have no sender name — that is normal, not an error.
Default message enrichment (reactions / update_time)
The four message-pulling shortcuts (+messages-mget, +chat-messages-list, +messages-search, +threads-messages-list) automatically attach a reactions block and (for edited messages) update_time to each returned message — no separate im.reactions.batch_query call is needed. Pass --no-reactions to opt out. For the full contract (output shape, the im:message.reactions:read scope requirement, and the "missing field ≠ fetch failure" data rules), read references/lark-im-message-enrichment.md.
Compact message output (--concise)
Some message-listing shortcuts support --concise for compact Markdown output. Use it when the user asks for concise output or a smaller result/file; check --help for availability and do not combine it with an explicit --format, an enabled --json, or a non-empty --jq.
Citation preservation:
+chat-messages-list --conciseemits plain Markdown and bypasses the normal JSON envelope, so citation-enabled runs do not expose thecitationsfield. When citation sources must be preserved, omit--conciseand use the default JSON output.
Opt-in resource auto-download (--download-resources)
+chat-messages-list, +messages-mget, and +threads-messages-list accept --download-resources to save eligible attachments into ./lark-im-resources/ and add a resources array to each message. It is off by default; stickers are not downloadable. A failed attachment is reported on that resource without aborting the message pull. Use +messages-resources-download for one attachment. See references/lark-im-message-enrichment.md for the output contract.
Folder resources are containers, not files — a folder file_key cannot be downloaded directly. Expand it first with lark-cli im files folder --recursive --file-key <folder_key> --srctype message --srcid <message_id>, then download the files inside with +messages-resources-download.
Card Messages (Interactive)
Before sending, replying with, or updating any interactive card (+messages-send / +messages-reply / messages.patch), you MUST read references/card/lark-im-card-create.md and follow its workflow. The card JSON passed to --msg-type interactive --content (send/reply) or messages.patch --data (update) must be the output of that workflow — never hand-write or copy a card payload.
Audio Messages
--audio sends a voice message and supports only Opus audio files, for example .opus files or Ogg Opus (.ogg) files. For mp3, wav, or other non-Opus audio, either convert to .opus first and keep using --audio, or send the original file as an attachment with --file.
Sending Doc Content as a Message
When sending content fetched from a Lark doc as a message, fetch the doc with --doc-format im-markdown, then send it as a message using the --markdown format. The fetched content is already in markdown; in any content-forwarding scenario, keep the fetched original text and send it in the --markdown format. Note: if the doc contains a cite tag with type="user", keep it as-is and do not strip the tag.
Flag Types
Flags support two layers:
- Message-layer flag:
(ItemTypeDefault, FlagTypeMessage)— regular message bookmark - Feed-layer flag:
(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed)— thread as feed-layer bookmark
Item types for feed-layer flags:
- ItemTypeThread (4) = thread in a topic-style chat
- ItemTypeMsgThread (11) = thread in a regular chat
Feed Shortcut
Feed shortcuts add chats to the current user's feed sidebar. They are distinct from flags:
- Flag = bookmark on a message/thread, scoped to the user's bookmark list.
- Feed shortcut = entry in the user's feed sidebar (currently only chats).
Key limits:
- Only CHAT-type (
feed_card_idisoc_xxx) is exposed via OpenAPI; doc/app/subscription shortcuts exist internally but are not yet whitelisted. - All three operations (create/remove/list) are user-identity only — they sign with
user_access_token. - Batch size is 10 per call for create/remove; list is a one-page wrapper with opaque
page_tokenpagination.
Shortcuts(推荐优先使用)
Shortcut 是对常用操作的高级封装(lark-cli im +<verb> [flags])。有 Shortcut 的操作优先使用。
Pro 私有路由:仅当上下文出现固定标注
合并转发消息 ID: <copied_id>,共 <message_count> 条时提取copied_id。同一上下文可按出现顺序收集 1~10 个 ID,并按私有命令说明调用im +shared-message-mget --message-ids ...;普通数字或om_Message ID 不触发。裸调用默认读取消息快照、话题回复和 reaction;仅当用户明确要求不读取话题回复或 reaction 时,分别增加--no-thread-replies或--no-reactions。二进制资源在用户需要时增加--download-resources,多个选项可组合使用。
| Shortcut | 说明 |
|---|---|
+chat-create |
Create a group chat or topic chat; user; --chat-mode group |
+chat-list |
List chats the current user is a member of; defaults to groups; pass --types=p2p,group to include p2p single chats (user-only); user; supports sorting, auto-pagination, --exclude-muted (user-only) |
+chat-members-list |
List members of a chat; returns separate users[] buckets; callable as user; --member-types filters which kinds to return; --page-all pagination; surfaces truncations[] when the server caps a bucket |
+chat-messages-list |
List messages in a chat or P2P conversation; user; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range, --order asc/desc sorting, auto-pagination. When using this tool, be sure to preserve the citation sources. |
+chat-search |
Search visible group chats by --query keyword and/or --member-ids; user; e.g. look up chat_id by group name; supports type filters, sorting, auto-pagination, and --exclude-muted (user identity only). When using this tool, be sure to preserve the citation sources. |
+chat-update |
Update group chat name or description; user; updates a chat's name or description |
+messages-edit |
Edit a message the current user sent (text/post, including the attachment zone); user; PUT /open-apis/im/v1/messages/:message_id |
+message-read-users |
List users who read one message; user; identity-specific scopes; supports bounded auto-pagination |
+messages-mget |
Batch get messages by IDs; user; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
+shared-message-mget |
Pro 私有;读取 1~10 个 Copied Message 快照;默认补拉 thread / reaction,可用 --no-* 关闭;resource download 按需开启 |
+messages-read-status |
Batch query whether the current user read 1–50 messages; user-only; returns readable items and invalid message IDs |
+messages-reply |
Reply to a message (supports thread replies); user; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
+messages-resources-download |
Download an image/file from a message; folders are not directly downloadable — expand with im files folder --recursive first, then download the files inside; user |
+messages-search |
Search messages across chats (supports keyword, sender, time range filters) with user identity; filters by chat/sender/attachment/time, supports auto-pagination via --page-all / --page-limit, enriches results via batched mget and chats batch_query. When using this tool, be sure to preserve the citation sources. |
+messages-send |
Send a message to a chat or direct message; user; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
+threads-messages-list |
List messages in a thread; user; accepts om_/omt_ input, resolves message IDs to thread_id, supports --order asc/desc sorting, auto-pagination |
+flag-create |
Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode) |
+flag-cancel |
Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer |
+flag-list |
List bookmarks; user-only; auto-enriches feed-type thread entries with message content; --page-all is capped by --page-limit (default 20, max 1000), and has_more=true means the result is incomplete |
+feed-shortcut-create |
Add chats to the user's feed shortcuts; user-only; oc_xxx chat IDs only; batch up to 10 per call; --head/--tail controls insertion order; partial failures return an ok:false ledger |
+feed-shortcut-remove |
Remove chats from the user's feed shortcuts; user-only; batch up to 10 per call; removing an absent shortcut is idempotent success; real per-item failures return an ok:false ledger |
+feed-shortcut-list |
List one page of the user's feed shortcuts; user-only; omit --page-token for the first page; default output enriches CHAT entries under detail; pass --no-detail to skip the extra lookup and im:chat:read scope |
+feed-group-list |
List the caller's feed groups (tags); user-only; supports --page-all auto-pagination |
+feed-group-list-item |
List feed cards in a feed group (tag); user-only; enriches each item with chat_name resolved from feed_id; supports --page-all auto-pagination |
+feed-group-query-item |
Look up specific feed cards in a feed group (tag) by ID; user-only; enriches each item with chat_name resolved from feed_id |
API Resources
lark-cli schema im.<resource>.<method> # 调用 API 前必须先查看参数结构
lark-cli im <resource> <method> [flags] # 调用 API
重要:使用原生 API 时,必须先运行
schema查看--data/--params参数结构,不要猜测字段格式。
chats
get— 获取群信息。Identity: supportsuseronly; the caller must be in the target chat to get full details, and must belong to the same tenant for internal chats.link— 获取群分享链接。Identity: supportsuseronly; the caller must be in the target chat, must be an owner or admin when chat sharing is restricted to owners/admins, and must belong to the same tenant for internal chats.update— 更新群信息。Identity: supportsuseronly.
chat.members
chat.user_setting
batch_query— 批量查询当前用户在群内的个人偏好设置 (e.g.is_mutedmutes normal messages,is_mute_at_allmutes @all messages); up to 10 chats per request. Identity:useronly (user_access_token); the caller must be in each target chat.batch_update— 批量更新当前用户在群内的个人偏好设置 (e.g.is_mutedmutes normal messages,is_mute_at_allmutes @all messages); up to 10 chats per request. Identity:useronly (user_access_token); the caller must be in each target chat.
chat.nickname
get— 获取自己的群昵称。Get your own nickname in the chat (self-only). Identity:useronly (user_access_token); returns an empty string when no nickname is set.update— 设置自己的群昵称。Set or update your own nickname in the chat (self-only). Identity:useronly (user_access_token);nicknamemust be a non-empty string (max 300 bytes). Use DELETE to clear it.delete— 清空自己的群昵称。Clear your own nickname in the chat (self-only). Identity:useronly (user_access_token).
chat.join_requests
list— 列出群的待审批入群申请(仅群主/管理员,user_access_token)。List pending join requests for a chat. Identity:useronly (user_access_token); the caller must be the chat owner or an admin. Paginated (page_size1-100); stop onhas_more == false—page_tokenis returned even on the last page, so paging while it is present never terminates.handle— 批量审批入群申请(approve/reject,仅群主/管理员,user_access_token)。Approve or reject pending join requests in bulk (1-50 items, processed in order). Identity:useronly (user_access_token); the caller must be the chat owner or an admin.results[]mirrorsitems[]in count and order — check eachresult(success/failed/already_handled); exit 0 does not mean every item succeeded.
chat.managers
add_managers— 指定群管理员。Identity: supportsuseronly; only the group owner can add managers; max 10 managers per chat (20 for super-large chats), and at most 50 users per request.delete_managers— 删除群管理员。Identity: supportsuseronly; only the group owner can remove managers; max 50 users or 50 users per request.
chat.moderation
get— 获取群成员发言权限。Identity: supportsuseronly; the caller must be in the target chat and belong to the same tenant.
message_links
query— Query message sharing-link content. Read the copied snapshot using the full message link URL; do not infer chronology from array position; check chat_info.is_authorized separately.Must-read
resources
download— Download message sharing-link resources. Download one sharing-link resource with srctype=messagelink and the URL token as srcid; use --output to save the binary response. User identity requires one of im:message, im:message:readonly, or im:message.history:readonly.Must-read
messages
read_status— 批量查询当前用户对消息的已读状态。Identity:useronly (user_access_token); accepts up to 50 message IDs and returns readable items plus invalid message IDs.Must-readforward— 转发消息。Identity: supportsuseronly.patch— 更新已发送的消息卡片。Update an interactive message card sent by the app. This CLI runs the API with user identity; the message must have been sent within the last 14 days, andcontentmust be a JSON-serialized string no larger than 30 KB.Must-read
reactions
batch_query— 批量获取消息表情。Identity: supportsuseronly.Must-readcreate— 添加消息表情回复。Identity: supportsuseronly; the caller must be in the conversation that contains the message.Must-readdelete— 删除消息表情回复。Identity: supportsuseronly; the caller must be in the conversation that contains the message, and can only delete reactions added by itself.Must-readlist— 获取消息表情回复。Identity: supportsuseronly; the caller must be in the conversation that contains the message.Must-read
threads
forward— 转发话题。Identity: supportsuseronly.
images
create— 上传图片。Identity: supportsuseronly; user identity requiresim:resourcescope on the UAT.
files
create— 上传文件。Identity: supportsuseronly; user identity requiresim:resourcescope on the UAT.
pins
create— Pin 消息。Identity: supportsuseronly.delete— 移除 Pin 消息。Identity: supportsuseronly.list— 获取群内 Pin 消息。Identity: supportsuseronly.
feed.groups
batch_add_item— Batch add feed cards to a feed group. Identity:useronly (user_access_token).Must-readbatch_query— Batch query feed groups. Identity:useronly (user_access_token).Must-readbatch_remove_item— Batch remove feed cards from a feed group. Identity:useronly (user_access_token).Must-readcreate— Create a feed group. Identity:useronly (user_access_token).Must-readdelete— Delete a feed group. Identity:useronly (user_access_token).Must-readupdate— Update a feed group. Identity:useronly (user_access_token).Must-read
权限表
| 方法 | 所需 scope |
|---|---|
chats.create |
im:chat:create |
chats.get |
im:chat:read |
chats.link |
im:chat:read |
chats.update |
im:chat:update |
chat.members.create |
im:chat.members:write_only |
chat.members.delete |
im:chat.members:write_only |
chat.members.get |
im:chat.members:read |
+chat-members-list |
im:chat.members:read |
chat.user_setting.batch_query |
im:chat.user_setting:read |
chat.user_setting.batch_update |
im:chat.user_setting:write |
chat.managers.add_managers |
im:chat.managers:write_only |
chat.managers.delete_managers |
im:chat.managers:write_only |
chat.moderation.get |
im:chat.moderation:read |
chat.moderation.update |
im:chat:moderation:write_only |
chat.join_requests.list |
im:chat.membership_application:read |
chat.join_requests.handle |
im:chat.membership_application:write |
+messages-edit |
im:message.send_as_user and im:message |
+messages-read-status |
user: im:message:readonly (recommended), im:message, or im:message:get_as_user |
+message-read-users |
user: im:message:readonly (recommended), im:message, im:message:basic, or im:message:get_as_user; bot: im:message:readonly |
message_links.query |
im:message.message_link:read |
resources.download |
im:message, im:message:readonly, or im:message.history:readonly |
messages.read_status |
im:message:readonly (recommended), im:message, or im:message:get_as_user |
messages.delete |
im:message:recall |
messages.forward |
im:message |
messages.merge_forward |
im:message |
messages.read_users |
user: im:message:readonly (recommended), im:message, im:message:basic, or im:message:get_as_user; bot: im:message:readonly |
messages.patch |
im:message:update |
messages.urgent_app |
im:message.urgent |
messages.urgent_phone |
im:message.urgent:phone |
messages.urgent_sms |
im:message.urgent:sms |
reactions.batch_query |
im:message.reactions:read |
reactions.create |
im:message.reactions:write_only |
reactions.delete |
im:message.reactions:write_only |
reactions.list |
im:message.reactions:read |
threads.forward |
im:message |
images.create |
im:resource |
files.create |
im:resource |
pins.create |
im:message.pins:write_only |
pins.delete |
im:message.pins:write_only |
pins.list |
im:message.pins:read |
feed.groups.batch_add_item |
im:feed_group_v1:write |
feed.groups.batch_query |
im:feed_group_v1:read |
feed.groups.batch_remove_item |
im:feed_group_v1:write |
feed.groups.create |
im:feed_group_v1:write |
feed.groups.delete |
im:feed_group_v1:write |
feed.groups.update |
im:feed_group_v1:write |