lark-im

im (v1)

CRITICAL — 开始前 MUST 先用 File(action="read") 读取 ../lark-shared/SKILL.md，其中包含认证、权限处理

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 / bot)

Important Notes

Identity and Token Mapping

身份规则见 lark-shared。IM 特有注意：同一 API 用 user/bot 可能一成一败（群成员关系、群主/管理员、租户边界都按当前调用者校验）。

Sender Name Resolution

When fetching messages (+chat-messages-list, +threads-messages-list, +messages-mget, +messages-search), the CLI shows a display name for both user and bot 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 users and bots alike. 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.

Opt-in resource auto-download (--download-resources)

+chat-messages-list/+messages-mget/+threads-messages-list 支持 --download-resources（默认关）把图片/文件/音视频（不含 sticker）下载到 ./lark-im-resources/；完整契约见 message-enrichment。一次性下载用 +messages-resources-download。

Card Messages (Interactive)

Before sending or replying with any interactive card (+messages-send / +messages-reply), you MUST read references/card/lark-im-card-create.md and follow its workflow. The card JSON passed to --msg-type interactive --content must be the output of that workflow — never hand-write or copy a card payload.

Card messages (interactive type) are not yet supported for compact conversion in event subscriptions. The raw event data will be returned instead, with a hint printed to stderr.

interactive cards support callback events (card.action.trigger) — see references/lark-im-card-action-reply.md.

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 的操作优先使用。

API Resources

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

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

chats

• create — 创建群。Identity: bot only (tenant_access_token).
• get — 获取群信息。Identity: supports user and bot; 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 and bot; 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 and bot.

chat.members

• create — 将用户或机器人拉入群聊。Identity: supports user and bot; the caller must be in the target chat; for bot calls, added users must be within the app's availability; for internal chats the operator must belong to the same tenant; if only owners/admins can add members, the caller must be an owner/admin, or a chat-creator bot with im:chat:operate_as_owner.
• delete — 将用户或机器人移出群聊。Identity: supports user and bot; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.

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.managers

• add_managers — 指定群管理员。Identity: supports user and bot; only the group owner can add managers; max 10 managers per chat (20 for super-large chats), and at most 5 bots per request.
• delete_managers — 删除群管理员。Identity: supports user and bot; only the group owner can remove managers; max 50 users or 5 bots per request.

chat.moderation

• get — 获取群成员发言权限。Identity: supports user and bot; the caller must be in the target chat and belong to the same tenant.
• update — 更新群发言权限。Identity: supports user and bot; only the group owner (or creator bot with im:chat:operate_as_owner) can update; the caller must be in the chat.

messages

• delete — 撤回消息。Identity: supports user and bot; for bot calls, the bot must be in the chat to revoke group messages; to revoke another user's group message, the bot must be the owner, an admin, or the creator; for user P2P recalls, the target user must be within the bot's availability.
• forward — 转发消息。Identity: supports user and bot.
• merge_forward — 合并转发消息。Identity: bot only (tenant_access_token).
• read_users — 查询消息已读信息。Identity: bot only (tenant_access_token); the bot must be in the chat, and can only query read status for messages it sent within the last 7 days.
• urgent_app — 发送应用内加急。Identity: bot only (tenant_access_token); the bot must be the message sender and must be in the conversation that contains the message.
• urgent_phone — 发送电话加急。Identity: bot only (tenant_access_token); the bot must be the message sender and must be in the conversation that contains the message.
• urgent_sms — 发送短信加急。Identity: bot only (tenant_access_token); the bot must be the message sender and must be in the conversation that contains the message.

reactions

• batch_query — 批量获取消息表情。Identity: supports user and bot.Must-read
• create — 添加消息表情回复。Identity: supports user and bot; the caller must be in the conversation that contains the message.Must-read
• delete — 删除消息表情回复。Identity: supports user and bot; 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 and bot; the caller must be in the conversation that contains the message.Must-read

threads

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

images

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

files

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

pins

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

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

• 各方法所需 scope 见 lark-im-scopes.md；权限报错时优先按 lark-shared 读错误里的 missing_scopes