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.

Resource Relationships

Chat (oc_xxx)
├── Message (om_xxx)
│   ├── Thread (reply thread)
│   ├── Reaction (emoji)
│   └── Resource (image / file / video / audio)
└── Member (user)

Important Notes

Identity and Token

All IM operations run as user identity with a user_access_token. Calls run as the authorized end user, so permissions depend on both the app scopes and that user's own access to the target chat/message/resource.

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.

Card Messages (Interactive)

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.

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

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 — 创建群。Prefer the +chat-create shortcut, which runs as the user.
• 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

• bots — 获取群内机器人列表。Identity: supports user only; the caller must be in the target chat and must belong to the same tenant for internal chats.
• create — 将用户或机器人拉入群聊。Identity: supports user only; the caller must be in the target chat; 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.
• delete — 将用户或机器人移出群聊。Identity: supports user only; only the group owner or an admin can remove others; max 50 users or 5 bots per request.
• get — 获取群成员列表。Identity: supports user only; the caller must be in the target chat and must belong to the same tenant for internal chats.

messages

• delete — 撤回消息。Identity: supports user only; you can revoke your own messages, and revoking another user's group message requires owner or admin privileges.
• forward — 转发消息。Identity: supports user only.
• merge_forward — 合并转发消息。Not available under user identity.
• read_users — 查询消息已读信息。Not available under user identity.
• urgent_app — 发送应用内加急。Not available under user identity.
• urgent_phone — 发送电话加急。Not available under user identity.
• urgent_sms — 发送短信加急。Not available under user identity.

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 — 上传图片。Not available under user identity.

pins

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

权限表