im (v1)

CRITICAL — 开始前 MUST 先用 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.

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

When using bot identity (

--as bot

) to fetch messages (e.g.

+chat-messages-list

+threads-messages-list

+messages-mget

), sender names may not be resolved (shown as open_id instead of display name). This happens when the bot cannot access the user's contact info.

Root cause: The bot's app visibility settings do not include the message sender, so the contact API returns no name.

Solution: Check the app's visibility settings in the Lark Developer Console — ensure the app's visible range covers the users whose names need to be resolved. Alternatively, use

--as user

to fetch messages with user identity, which typically has broader contact access.

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.

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（

lark-cli im +<verb> [flags]

）。有 Shortcut 的操作优先使用。

Shortcut	说明
`+chat-create`	Create a group chat with bot identity; bot-only; creates private/public chats, invites users/bots, optionally sets bot manager
`+chat-messages-list`	List messages in a chat or P2P conversation; user/bot; accepts --chat-id or --user-id, resolves P2P chat_id, supports time range/sort/pagination
`+chat-search`	Search visible group chats by keyword and/or member open_ids (e.g. look up chat_id by group name); user/bot; supports member/type filters, sorting, and pagination
`+chat-update`	Update group chat name or description; user/bot; updates a chat's name or description
`+messages-mget`	Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies
`+messages-reply`	Reply to a message (supports thread replies) with bot identity; bot-only; supports text/markdown/post/media replies, reply-in-thread, idempotency key
`+messages-resources-download`	Download images/files from a message; user/bot; downloads image/file resources by message-id and file-key to a safe relative output path
`+messages-search`	Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, enriches results via mget and chats batch_query
`+messages-send`	Send a message to a chat or direct message with bot identity; bot-only; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key
`+threads-messages-list`	List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination

API Resources

bash

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

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

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

权限表

方法	所需 scope
`chats.create`	`im:chat:create`
`chats.get`	`im:chat:read`
`chats.link`	`im:chat:read`
`chats.list`	`im:chat:read`
`chats.update`	`im:chat:update`
`chat.members.create`	`im:chat.members:write_only`
`chat.members.get`	`im:chat.members:read`
`messages.delete`	`im:message:recall`
`messages.forward`	`im:message`
`messages.merge_forward`	`im:message`
`messages.read_users`	`im:message:readonly`
`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`
`images.create`	`im:resource`
`pins.create`	`im:message.pins:write_only`
`pins.delete`	`im:message.pins:write_only`
`pins.list`	`im:message.pins:read`

lark-im

NPX Install

Tags

SKILL.md Content