lark-im

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

im (v1)

im（v1）

CRITICAL — 开始前 MUST 先用 Read 工具读取
../lark-shared/SKILL.md
，其中包含认证、权限处理

重要提示 — 开始前必须先用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.

消息（Message）：聊天中的单条消息，由
```
message_id
```
（格式为om_xxx）标识。支持的类型包括：文本、富文本（post）、图片、文件、音频、视频、贴纸、交互式卡片（interactive）、分享群聊、分享用户、合并转发等。
会话（Chat）：群聊或一对一对话，由
```
chat_id
```
（格式为oc_xxx）标识。
回复线程（Thread）：消息下的回复线程，由
```
thread_id
```
（格式为om_xxx或omt_xxx）标识。
表情回复（Reaction）：消息上的表情回应。

Resource Relationships

资源关系

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

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.

```
--as user
```
代表用户身份，使用
```
user_access_token
```
。调用以授权终端用户身份执行，因此权限同时取决于应用的权限范围和该用户对目标会话/消息/资源的访问权限。
```
--as bot
```
代表机器人身份，使用
```
tenant_access_token
```
。调用以应用机器人身份执行，因此行为取决于机器人的会话成员身份、应用可见性、可用范围以及机器人专属的权限范围。
如果某个IM API同时支持
```
user
```
和
```
bot
```
身份，令牌类型会改变操作者身份。同一API可能在一种身份下成功，另一种身份下失败，这是因为会根据当前调用者检查所有者/管理员身份、会话成员资格、租户边界或应用可用性。

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.

当使用机器人身份（

--as bot

）拉取消息时（例如

+chat-messages-list

、

+threads-messages-list

、

+messages-mget

），发送者名称可能无法解析（显示为open_id而非昵称）。这是因为机器人无法访问该用户的联系人信息。

根本原因：机器人所属应用的可见性设置未包含消息发送者，因此联系人API无法返回名称。

解决方案：在飞书开发者控制台检查应用的可见性设置——确保应用的可见范围覆盖需要解析名称的用户。或者使用

--as user

以用户身份拉取消息，通常用户身份拥有更广泛的联系人访问权限。

Card Messages (Interactive)

卡片消息（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.

事件订阅中暂不支持卡片消息（

interactive

类型）的精简转换，将返回原始事件数据，并在标准错误输出中打印提示信息。

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

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

lark-cli im +<verb> [flags]

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

快捷操作	说明
`+chat-create`	以机器人身份创建群聊；仅支持机器人；可创建私有/公开群聊、邀请用户/机器人，可选设置机器人管理员
`+chat-messages-list`	列出群聊或一对一对话中的消息；支持用户/机器人身份；接受--chat-id或--user-id参数，自动解析一对一对话的chat_id，支持时间范围/排序/分页
`+chat-search`	根据关键词和/或成员open_id搜索可见群聊（例如通过群名称查找chat_id）；支持用户/机器人身份；支持成员/类型筛选、排序和分页
`+chat-update`	更新群聊名称或描述；支持用户/机器人身份；修改群聊的名称或描述
`+messages-mget`	根据ID批量获取消息；支持用户/机器人身份；最多可拉取50条格式为om_的消息ID，自动格式化发送者名称，展开线程回复
`+messages-reply`	以机器人身份回复消息（支持线程回复）；仅支持机器人；支持文本/Markdown/富文本/媒体回复、线程内回复、幂等键
`+messages-resources-download`	从消息中下载图片/文件；支持用户/机器人身份；通过message-id和file-key将图片/文件资源下载到安全的相对输出路径
`+messages-search`	以用户身份跨会话搜索消息（支持关键词、发送者、时间范围筛选）；仅支持用户身份；可按会话/发送者/附件/时间筛选，通过mget和chats batch_query丰富结果
`+messages-send`	以机器人身份向群聊或一对一对话发送消息；仅支持机器人；可向指定chat-id或user-id发送文本/Markdown/富文本/媒体消息，支持幂等键
`+threads-messages-list`	列出线程中的消息；支持用户/机器人身份；接受om_/omt_格式的输入，自动将消息ID解析为thread_id，支持排序/分页

API Resources

API资源

bash

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

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

bash

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

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

chats

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

```
create
```
— 创建群聊。身份：仅支持
```
bot
```
（使用
```
tenant_access_token
```
）。
- ```
get
```
  — 获取群信息。身份：支持
```
user
```
  和
```
bot
```
  ；调用者必须在目标会话中才能获取完整详情，对于内部会话，调用者必须属于同一租户。
- ```
link
```
  — 获取群分享链接。身份：支持
```
user
```
  和
```
bot
```
  ；调用者必须在目标会话中，当群分享权限限制为所有者/管理员时，调用者必须是所有者或管理员；对于内部会话，调用者必须属于同一租户。
- ```
list
```
  — 获取用户或机器人所在的群列表。身份：支持
```
user
```
  和
```
bot
```
  。
- ```
update
```
  — 更新群信息。身份：支持
```
user
```
  和
```
bot
```
  。

chat.members

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.

```
create
```
— 将用户或机器人拉入群聊。身份：支持
```
user
```
和
```
bot
```
；调用者必须在目标会话中；使用
```
bot
```
身份调用时，添加的用户必须在应用的可用范围内；对于内部会话，操作者必须属于同一租户；如果仅所有者/管理员可添加成员，调用者必须是所有者/管理员，或者是拥有
```
im:chat:operate_as_owner
```
权限的群创建机器人。
- ```
get
```
  — 获取群成员列表。身份：支持
```
user
```
  和
```
bot
```
  ；调用者必须在目标会话中，对于内部会话，调用者必须属于同一租户。

messages

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.

```
delete
```
— 撤回消息。身份：支持
```
user
```
和
```
bot
```
；使用
```
bot
```
身份调用时，机器人必须在会话中才能撤回群消息；要撤回其他用户的群消息，机器人必须是所有者、管理员或创建者；对于用户一对一消息撤回，目标用户必须在机器人的可用范围内。
- ```
forward
```
  — 转发消息。身份：仅支持
```
bot
```
  （使用
```
tenant_access_token
```
  ）。
- ```
merge_forward
```
  — 合并转发消息。身份：仅支持
```
bot
```
  （使用
```
tenant_access_token
```
  ）。
- ```
read_users
```
  — 查询消息已读信息。身份：仅支持
```
bot
```
  （使用
```
tenant_access_token
```
  ）；机器人必须在会话中，且只能查询自身在过去7天内发送的消息的已读状态。

reactions

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

```
batch_query
```
— 批量获取消息表情。身份：支持
```
user
```
和
```
bot
```
。必读文档
- ```
create
```
  — 添加消息表情回复。身份：支持
```
user
```
  和
```
bot
```
  ；调用者必须在包含该消息的会话中。必读文档
- ```
delete
```
  — 删除消息表情回复。身份：支持
```
user
```
  和
```
bot
```
  ；调用者必须在包含该消息的会话中，且只能删除自身添加的表情回复。必读文档
- ```
list
```
  — 获取消息表情回复。身份：支持
```
user
```
  和
```
bot
```
  ；调用者必须在包含该消息的会话中。必读文档

images

images（图片）

```
create
```
— 上传图片。Identity:
```
bot
```
only (
```
tenant_access_token
```
).

```
create
```
— 上传图片。身份：仅支持
```
bot
```
（使用
```
tenant_access_token
```
）。

pins

pins（固定消息）

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

```
create
```
— 固定消息。身份：支持
```
user
```
和
```
bot
```
。
- ```
delete
```
  — 移除固定消息。身份：支持
```
user
```
  和
```
bot
```
  。
- ```
list
```
  — 获取群内固定消息。身份：支持
```
user
```
  和
```
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`

方法	所需 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`