​

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

​

Important Notes

​

Identity and Token Mapping

• --as user means user identity and uses 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.
• --as bot means bot identity and uses tenant_access_token. Calls run as the app bot, so behavior depends on the bot’s membership, app visibility, availability range, and bot-specific scopes.
• If an IM API says it supports both user and bot, the token type changes who the operator is. The same API can succeed with one identity and fail with the other because owner/admin status, chat membership, tenant boundary, or app availability are checked against the current caller.

​

Sender Name Resolution with Bot Identity

​

Card Messages (Interactive)

​

Flag Types

• Message-layer flag: (ItemTypeDefault, FlagTypeMessage) — regular message bookmark
• Feed-layer flag: (ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed) — thread as feed-layer bookmark

• ItemTypeThread (4) = thread in a topic-style chat
• ItemTypeMsgThread (11) = thread in a regular chat

​

Shortcuts（推荐优先使用）

​

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.
• list — 获取用户或机器人所在的群列表。Identity: supports user and bot.
• update — 更新群信息。Identity: supports user and bot.

​

chat.members

• bots — 获取群内机器人列表。Identity: supports user and bot; the caller must be in the target chat and must belong to the same tenant for internal chats.
• 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.
• get — 获取群成员列表。Identity: supports user and bot; the caller must be in the target chat and must belong to the same tenant for internal chats.

​

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.

​

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: bot only (tenant_access_token).

​

pins

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

​

权限表