> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt
> Use this file to discover all available pages before exploring further.

# lark-im

> 飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、管理标记数据时使用。

| 项目 | 内容                                                                                                                                                                                                                                                             |
| -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 来源 | [skills/lark-im/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/SKILL.md)                                                                                                                                   |
| 分类 | 飞书/Lark 办公套件                                                                                                                                                                                                                                                   |
| 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/lark-im/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) |

# im (v1)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/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.

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

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

| Shortcut                                                                                                                                                                     | 说明                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`+chat-create`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-chat-create.md)                                 | Create a group chat; user/bot; creates private/public chats, invites users/bots, optionally sets bot manager                                                                                                                                                            |
| [`+chat-messages-list`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-chat-messages-list.md)                   | 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`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-chat-search.md)                                 | Search visible group chats by `--query` keyword and/or `--member-ids`; user/bot; e.g. look up chat\_id by group name; supports type filters, sorting, and pagination                                                                                                    |
| [`+chat-update`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-chat-update.md)                                 | Update group chat name or description; user/bot; updates a chat's name or description                                                                                                                                                                                   |
| [`+messages-mget`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-messages-mget.md)                             | Batch get messages by IDs; user/bot; fetches up to 50 om\_ message IDs, formats sender names, expands thread replies                                                                                                                                                    |
| [`+messages-reply`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-messages-reply.md)                           | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key                                                                                                                                     |
| [`+messages-resources-download`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; supports automatic chunked download for large files (8MB chunks), auto-detects file extension from Content-Type                                                                                                         |
| [`+messages-search`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-messages-search.md)                         | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch\_query |
| [`+messages-send`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-messages-send.md)                             | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key                                                                                                                               |
| [`+threads-messages-list`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-threads-messages-list.md)             | List messages in a thread; user/bot; accepts om\_/omt\_ input, resolves message IDs to thread\_id, supports sort/pagination                                                                                                                                             |
| [`+flag-create`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-flag-create.md)                                 | Create a bookmark on a message or thread; user-only; defaults to message-layer flag; feed-layer flag requires explicit --item-type + --flag-type                                                                                                                        |
| [`+flag-cancel`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-flag-cancel.md)                                 | Cancel (remove) a bookmark. When no --flag-type is given, checks if the message is a thread root message; if so, cancels both message and feed layers                                                                                                                   |
| [`+flag-list`](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-flag-list.md)                                     | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination                                                                                                                                           |

## API Resources

```bash theme={null}
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](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-reactions.md)
* `create` — 添加消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-reactions.md)
* `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](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-reactions.md)
* `list` — 获取消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/lark-im/references/lark-im-reactions.md)

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

## 权限表

| 方法                       | 所需 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.bots`      | `im:chat.members:read`            |
| `chat.members.create`    | `im:chat.members:write_only`      |
| `chat.members.delete`    | `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`             |
| `threads.forward`        | `im:message`                      |
| `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`            |