Lark Im

im (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 (an oc_xxx open_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 by feed_id + feed_type. Two types: normal (members managed explicitly) and rule (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

Prefer CLI-returned links: 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-i18n sender_i18n_names map) on each message sender; the CLI surfaces it as the sender's name for message senders. No name lookup and no extra permission are needed — no contact scope and no application: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 --concise emits plain Markdown and bypasses the normal JSON envelope, so citation-enabled runs do not expose the citations field. When citation sources must be preserved, omit --concise and 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_id is oc_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_token pagination.

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，多个选项可组合使用。

API Resources

lark-cli schema im.<resource>.<method>   # 调用 API 前必须先查看参数结构
lark-cli im <resource> <method> [flags] # 调用 API

重要：使用原生 API 时，必须先运行 schema 查看 --data / --params 参数结构，不要猜测字段格式。

chats

• get — 获取群信息。Identity: supports user only; the caller must be in the target chat to get full details, and must belong to the same tenant for internal chats.
• link — 获取群分享链接。Identity: supports user only; 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: supports user only.

chat.members

chat.user_setting

• batch_query — 批量查询当前用户在群内的个人偏好设置 (e.g. is_muted mutes normal messages, is_mute_at_all mutes @all messages); up to 10 chats per request. Identity: user only (user_access_token); the caller must be in each target chat.
• batch_update — 批量更新当前用户在群内的个人偏好设置 (e.g. is_muted mutes normal messages, is_mute_at_all mutes @all messages); up to 10 chats per request. Identity: user only (user_access_token); the caller must be in each target chat.

chat.nickname

• get — 获取自己的群昵称。Get your own nickname in the chat (self-only). Identity: user only (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: user only (user_access_token); nickname must be a non-empty string (max 300 bytes). Use DELETE to clear it.
• delete — 清空自己的群昵称。Clear your own nickname in the chat (self-only). Identity: user only (user_access_token).

chat.join_requests

• list — 列出群的待审批入群申请（仅群主/管理员，user_access_token）。List pending join requests for a chat. Identity: user only (user_access_token); the caller must be the chat owner or an admin. Paginated (page_size 1-100); stop on has_more == false — page_token is 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: user only (user_access_token); the caller must be the chat owner or an admin. results[] mirrors items[] in count and order — check each result (success / failed / already_handled); exit 0 does not mean every item succeeded.

chat.managers

• add_managers — 指定群管理员。Identity: supports user only; 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: supports user only; only the group owner can remove managers; max 50 users or 50 users per request.

chat.moderation

• get — 获取群成员发言权限。Identity: supports user only; the caller must be in the target chat and belong to the same tenant.

messages

• read_status — 批量查询当前用户对消息的已读状态。Identity: user only (user_access_token); accepts up to 50 message IDs and returns readable items plus invalid message IDs.Must-read
• forward — 转发消息。Identity: supports user only.
• 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, and content must be a JSON-serialized string no larger than 30 KB.Must-read

reactions

• batch_query — 批量获取消息表情。Identity: supports user only.Must-read
• create — 添加消息表情回复。Identity: supports user only; the caller must be in the conversation that contains the message.Must-read
• delete — 删除消息表情回复。Identity: supports user only; the caller must be in the conversation that contains the message, and can only delete reactions added by itself.Must-read
• list — 获取消息表情回复。Identity: supports user only; the caller must be in the conversation that contains the message.Must-read

threads

• forward — 转发话题。Identity: supports user only.

images

• create — 上传图片。Identity: supports user only; user identity requires im:resource scope on the UAT.

files

• create — 上传文件。Identity: supports user only; user identity requires im:resource scope on the UAT.

pins

• create — Pin 消息。Identity: supports user only.
• delete — 移除 Pin 消息。Identity: supports user only.
• list — 获取群内 Pin 消息。Identity: supports user only.

feed.groups

• batch_add_item — Batch add feed cards to a feed group. Identity: user only (user_access_token).Must-read
• batch_query — Batch query feed groups. Identity: user only (user_access_token).Must-read
• batch_remove_item — Batch remove feed cards from a feed group. Identity: user only (user_access_token).Must-read
• create — Create a feed group. Identity: user only (user_access_token).Must-read
• delete — Delete a feed group. Identity: user only (user_access_token).Must-read
• update — Update a feed group. Identity: user only (user_access_token).Must-read

权限表