---
id: daily-lark-im
name: "lark-im"
url: https://skills.yangsir.net/skill/daily-lark-im
author: larksuite
domain: ai-agent-external-interaction
tags: ["api-integration", "saas", "automation"]
install_count: 156100
rating: 4.80 (20 reviews)
github: https://github.com/larksuite/cli
---

# lark-im

> 操作飞书即时消息，支持发送文本、富文本等多种消息类型到群聊或私聊

**Stats**: 156,100 installs · 4.8/5 (20 reviews)

## Before / After 对比

### 飞书消息发送

**Before**:

手动调用飞书IM API，构造不同消息类型的JSON结构，调试消息格式和权限问题耗时较长

**After**:

通过统一的命令接口发送消息，自动处理消息格式和权限验证，支持文本、卡片、图片等多种类型

| Metric | Before | After | Change |
|---|---|---|---|
| 发送时间 | 20分钟 | 2分钟 | -90% |

## Readme

# lark-im

# im (v1)

**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](https://github.com/larksuite/cli/blob/HEAD/skills/lark-im/../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`](https://github.com/larksuite/cli/blob/HEAD/skills/lark-im/references/lark-im-chat-create.md)
Create a group chat with bot identity; bot-only; creates private/public chats, invites users/bots, optionally sets bot manager

[`+chat-messages-list`](https://github.com/larksuite/cli/blob/HEAD/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/larksuite/cli/blob/HEAD/skills/lark-im/references/lark-im-chat-search.md)
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`](https://github.com/larksuite/cli/blob/HEAD/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/larksuite/cli/blob/HEAD/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/larksuite/cli/blob/HEAD/skills/lark-im/references/lark-im-messages-reply.md)
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`](https://github.com/larksuite/cli/blob/HEAD/skills/lark-im/references/lark-im-messages-resources-download.md)
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`](https://github.com/larksuite/cli/blob/HEAD/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, enriches results via mget and chats batch_query

[`+messages-send`](https://github.com/larksuite/cli/blob/HEAD/skills/lark-im/references/lark-im-messages-send.md)
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`](https://github.com/larksuite/cli/blob/HEAD/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

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

- `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](https://github.com/larksuite/cli/blob/HEAD/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/larksuite/cli/blob/HEAD/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/larksuite/cli/blob/HEAD/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/larksuite/cli/blob/HEAD/skills/lark-im/references/lark-im-reactions.md)

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

Weekly Installs3.6KRepository[larksuite/cli](https://github.com/larksuite/cli)GitHub Stars1First SeenTodaySecurity Audits[Gen Agent Trust HubPass](/larksuite/cli/lark-im/security/agent-trust-hub)[SocketWarn](/larksuite/cli/lark-im/security/socket)[SnykWarn](/larksuite/cli/lark-im/security/snyk)Installed oncodex3.6Kopencode3.6Kgithub-copilot3.6Kcursor3.6Kgemini-cli3.6Kcline3.6K

---
*Source: https://skills.yangsir.net/skill/daily-lark-im*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-lark-im/markdown*