lark-im

Name: lark-im
Author: larksuite

bylarksuite· 47 skills

Installs

390k

Stars

16k

Forks

1.2k

How to install lark-im?

larksuite/cli/lark-im

$npx -y skills add larksuite/cli --skill lark-im

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/larksuite/cli" --skill "larksuite/cli/lark-im"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/larksuite/cli" that are relevant to the current task. Run `npx skills add "https://github.com/larksuite/cli"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

1	# im (v1)
2
3	CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理
4
5	## Core Concepts
6
7	- 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.
8	- Chat: A group chat or P2P conversation, identified by `chat_id` (oc_xxx).
9	- Thread: A reply thread under a message, identified by `thread_id` (om_xxx or omt_xxx).
10	- Reaction: An emoji reaction on a message.
11	- Flag: A bookmark on a message or thread.
12	- Feed Shortcut: A chat pinned to the current user's feed sidebar, identified by `feed_card_id` (an `oc_xxx` open_chat_id for CHAT type).
13	- Feed Group: A tag that groups feed cards in the feed list, identified by `feed_group_id` (ofg_xxx). Members are feed cards, each identified by `feed_id` + `feed_type`. Two types: `normal` (members managed explicitly) and `rule` (members auto-derived from rules).
14
15	## Resource Relationships
16
17	```
18	Chat (oc_xxx)
19	├── Message (om_xxx)
20	│ ├── Thread (reply thread)
21	│ ├── Reaction (emoji)
22	│ └── Resource (image / file / video / audio)
23	└── Member (user / bot)
24	```
25
26	## Important Notes
27
28	### Identity and Token Mapping
29
30	- `--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.
31	- `--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.
32	- 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.
33
34	### Sender Name Resolution
35
36	When fetching messages (`+chat-messages-list`, `+threads-messages-list`, `+messages-mget`, `+messages-search`), the CLI shows a display name for both user and bot senders:
37
38	- Server-provided name: the read APIs return `sender_name` (plus the full-i18n `sender_i18n_names` map) on each message `sender`; the CLI surfaces it as the sender's `name` for users and bots alike. No name lookup and no extra permission are needed — no contact scope and no `application:bot.basic_info:read`.
39	- Fallback to id: when the server does not provide a name, the sender is shown by its id and the command still exits 0. There is no contact-directory fallback.
40
41	The raw `sender_name` is not duplicated in output (its value is in `name`); the full `sender_i18n_names` map (all locales) is preserved for consumers that need a specific language, alongside an optional `open_bot_id` (`ou_`) for bot senders aligned with the message-receive event channel. System messages (`msg_type: system`) have no sender name — that is normal, not an error.
42
43	### Default message enrichment (reactions / update_time)
44
45	The four message-pulling shortcuts (`+messages-mget`, `+chat-messages-list`, `+messages-search`, `+threads-messages-list`) automatically attach a `reactions` block and (for edited messages) `update_time` to each returned message — no separate `im.reactions.batch_query` call is needed. Pass `--no-reactions` to opt out. For the full contract (output shape, the `im:message.reactions:read` scope requirement, and the "missing field ≠ fetch failure" data rules), read [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
46
47	### Opt-in resource auto-download (`--download-resources`)
48
49	`+chat-messages-list`, `+messages-mget`, and `+threads-messages-list` accept `--download-resources` (off by default — no `resources` block and no extra requests when omitted). When set, eligible message resources (image/file/audio/video/media + post-embedded; stickers excluded) are downloaded into `./lark-im-resources/` and each message gains a `resources` array of `{message_id, key, type, local_path, size_bytes}`. Downloads are deduped by `(message_id, file_key)`, run with bounded concurrency, and isolate single-resource failures (`error: true` + stderr warning). Scope: requires `im:message:readonly` (already declared by the listing commands — no extra scope); works under both user and bot identity. For one-off downloads use [`+messages-resources-download`](references/lark-im-messages-resources-download.md). Full contract: [`references/lark-im-message-enrichment.md`](references/lark-im-message-enrichment.md).
50
51	### Card Messages (Interactive)
52
53	Before sending or replying with any `interactive` card (`+messages-send` / `+messages-reply`), you MUST read [`references/card/lark-im-card-create.md`](references/card/lark-im-card-create.md) and follow its workflow. The card JSON passed to `--msg-type interactive --content` must be the output of that workflow — never hand-write or copy a card payload.
54
55	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.
56
57	`interactive` cards support callback events (`card.action.trigger`) — see [`references/lark-im-card-action-reply.md`](references/lark-im-card-action-reply.md).
58
59	### Audio Messages
60
61	`--audio` sends a voice message and supports only Opus audio files, for example `.opus` files or Ogg Opus (`.ogg`) files. For `mp3`, `wav`, or other non-Opus audio, either convert to `.opus` first and keep using `--audio`, or send the original file as an attachment with `--file`.
62
63	### Sending Doc Content as a Message
64
65	When sending content fetched from a Lark doc as a message, fetch the doc with --doc-format im-markdown, then send it as a message using the --markdown format. The fetched content is already in markdown; in any content-forwarding scenario, keep the fetched original text and send it in the --markdown format. Note: if the doc contains a cite tag with type="user", keep it as-is and do not strip the tag.
66
67	### Flag Types
68
69	Flags support two layers:
70
71	- Message-layer flag: `(ItemTypeDefault, FlagTypeMessage)` — regular message bookmark
72	- Feed-layer flag: `(ItemTypeThread/ItemTypeMsgThread, FlagTypeFeed)` — thread as feed-layer bookmark
73
74	Item types for feed-layer flags:
75	- ItemTypeThread (4) = thread in a topic-style chat
76	- ItemTypeMsgThread (11) = thread in a regular chat
77
78	### Feed Shortcut
79
80	Feed shortcuts add chats to the current user's feed sidebar. They are distinct from flags:
81
82	- Flag = bookmark on a message/thread, scoped to the user's bookmark list.
83	- Feed shortcut = entry in the user's feed sidebar (currently only chats).
84
85	Key limits:
86	- Only CHAT-type (`feed_card_id` is `oc_xxx`) is exposed via OpenAPI; doc/app/subscription shortcuts exist internally but are not yet whitelisted.
87	- All three operations (create/remove/list) are user-identity only — they sign with `user_access_token`.
88	- Batch size is 10 per call for create/remove; list is a one-page wrapper with opaque `page_token` pagination.
89
90	## Shortcuts（推荐优先使用）
91
92	Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。有 Shortcut 的操作优先使用。
93
94	\| Shortcut \| 说明 \|
95	\|----------\|------\|
96	\| [`+chat-create`](references/lark-im-chat-create.md) \| Create a group chat or topic chat; user/bot; --chat-mode group\|topic; private/public; invites users/bots; optionally sets bot manager \|
97	\| [`+chat-list`](references/lark-im-chat-list.md) \| List chats the current user/bot is a member of; defaults to groups; pass --types=p2p,group to include p2p single chats (user-only); user/bot; supports sorting, pagination, --exclude-muted (user-only) \|
98	\| [`+chat-members-list`](references/lark-im-chat-members-list.md) \| List members of a chat; returns separate users[] / bots[] buckets; callable as user or bot; --member-types filters which kinds to return; --page-all pagination; surfaces truncations[] when the server caps a bucket \|
99	\| [`+chat-messages-list`](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 \|
100	\| [`+chat-search`](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, pagination, and --exclude-muted (user identity only) \|
101	\| [`+chat-update`](references/lark-im-chat-update.md) \| Update group chat name or description; user/bot; updates a chat's name or description \|
102	\| [`+messages-mget`](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 \|
103	\| [`+messages-reply`](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 \|
104	\| [`+messages-resources-download`](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 \|
105	\| [`+messages-search`](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 \|
106	\| [`+messages-send`](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 \|
107	\| [`+threads-messages-list`](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 \|
108	\| [`+flag-create`](references/lark-im-flag-create.md) \| Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode) \|
109	\| [`+flag-cancel`](references/lark-im-flag-cancel.md) \| Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer \|
110	\| [`+flag-list`](references/lark-im-flag-list.md) \| List bookmarks; user-only; auto-enriches feed-type thread entries with message content; `--page-all` is capped by `--page-limit` (default 20, max 1000), and `has_more=true` means the result is incomplete \|
111	\| [`+feed-shortcut-create`](references/lark-im-feed-shortcut-create.md) \| Add chats to the user's feed shortcuts; user-only; oc_xxx chat IDs only; batch up to 10 per call; `--head`/`--tail` controls insertion order; partial failures return an `ok:false` ledger \|
112	\| [`+feed-shortcut-remove`](references/lark-im-feed-shortcut-remove.md) \| Remove chats from the user's feed shortcuts; user-only; batch up to 10 per call; removing an absent shortcut is idempotent success; real per-item failures return an `ok:false` ledger \|
113	\| [`+feed-shortcut-list`](references/lark-im-feed-shortcut-list.md) \| List one page of the user's feed shortcuts; user-only; omit `--page-token` for the first page; default output enriches CHAT entries under `detail`; pass `--no-detail` to skip the extra lookup and `im:chat:read` scope \|
114	\| [`+feed-group-list`](references/lark-im-feed-group-list.md) \| List the caller's feed groups (tags); user-only; supports `--page-all` auto-pagination \|
115	\| [`+feed-group-list-item`](references/lark-im-feed-group-list-item.md) \| List feed cards in a feed group (tag); user-only; enriches each item with chat_name resolved from feed_id; supports --page-all auto-pagination \|
116	\| [`+feed-group-query-item`](references/lark-im-feed-group-query-item.md) \| Look up specific feed cards in a feed group (tag) by ID; user-only; enriches each item with chat_name resolved from feed_id \|
117
118	## API Resources
119
120	```bash
121	lark-cli schema im.<resource>.<method> # 调用 API 前必须先查看参数结构
122	lark-cli im <resource> <method> [flags] # 调用 API
123	```
124
125	> 重要：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
126
127	### chats
128
129	- `create` — 创建群。Identity: `bot` only (`tenant_access_token`).
130	- `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.
131	- `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.
132	- `update` — 更新群信息。Identity: supports `user` and `bot`.
133
134	### chat.members
135
136	- `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`.
137	- `delete` — 将用户或机器人移出群聊。Identity: supports `user` and `bot`; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
138
139	### chat.user_setting
140
141	- `batch_query` — 批量查询当前用户在群内的个人偏好设置 (e.g. `is_muted` mutes normal messages, `is_mute_at_all` mutes @all messages); up to 10 chats per request. Identity: `user` only (`user_access_token`); the caller must be in each target chat.
142	- `batch_update` — 批量更新当前用户在群内的个人偏好设置 (e.g. `is_muted` mutes normal messages, `is_mute_at_all` mutes @all messages); up to 10 chats per request. Identity: `user` only (`user_access_token`); the caller must be in each target chat.
143
144	### chat.nickname
145
146	- `get` — 获取自己的群昵称。Get your own nickname in the chat (self-only). Identity: `user` only (`user_access_token`); returns an empty string when no nickname is set.
147	- `update` — 设置自己的群昵称。Set or update your own nickname in the chat (self-only). Identity: `user` only (`user_access_token`); `nickname` must be a non-empty string (max 300 bytes). Use DELETE to clear it.
148	- `delete` — 清空自己的群昵称。Clear your own nickname in the chat (self-only). Identity: `user` only (`user_access_token`).
149
150	### chat.managers
151
152	- `add_managers` — 指定群管理员。Identity: supports `user` and `bot`; only the group owner can add managers; max 10 managers per chat (20 for super-large chats), and at most 5 bots per request.
153	- `delete_managers` — 删除群管理员。Identity: supports `user` and `bot`; only the group owner can remove managers; max 50 users or 5 bots per request.
154
155	### chat.moderation
156
157	- `get` — 获取群成员发言权限。Identity: supports `user` and `bot`; the caller must be in the target chat and belong to the same tenant.
158	- `update` — 更新群发言权限。Identity: supports `user` and `bot`; only the group owner (or creator bot with `im:chat:operate_as_owner`) can update; the caller must be in the chat.
159
160	### messages
161
162	- `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.
163	- `forward` — 转发消息。Identity: supports `user` and `bot`.
164	- `merge_forward` — 合并转发消息。Identity: `bot` only (`tenant_access_token`).
165	- `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.
166	- `urgent_app` — 发送应用内加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
167	- `urgent_phone` — 发送电话加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
168	- `urgent_sms` — 发送短信加急。Identity: `bot` only (`tenant_access_token`); the bot must be the message sender and must be in the conversation that contains the message.
169
170	### reactions
171
172	- `batch_query` — 批量获取消息表情。Identity: supports `user` and `bot`.[Must-read](references/lark-im-reactions.md)
173	- `create` — 添加消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
174	- `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](references/lark-im-reactions.md)
175	- `list` — 获取消息表情回复。Identity: supports `user` and `bot`; the caller must be in the conversation that contains the message.[Must-read](references/lark-im-reactions.md)
176
177	### threads
178
179	- `forward` — 转发话题。Identity: supports `user` and `bot`.
180
181	### images
182
183	- `create` — 上传图片。Identity: `bot` only (`tenant_access_token`).
184
185	### pins
186
187	- `create` — Pin 消息。Identity: supports `user` and `bot`.
188	- `delete` — 移除 Pin 消息。Identity: supports `user` and `bot`.
189	- `list` — 获取群内 Pin 消息。Identity: supports `user` and `bot`.
190
191	### feed.groups
192
193	- `batch_add_item` — Batch add feed cards to a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
194	- `batch_query` — Batch query feed groups. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
195	- `batch_remove_item` — Batch remove feed cards from a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
196	- `create` — Create a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
197	- `delete` — Delete a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
198	- `update` — Update a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
199
200	## 权限表
201
202	\| 方法 \| 所需 scope \|
203	\|------\|-----------\|
204	\| `chats.create` \| `im:chat:create` \|
205	\| `chats.get` \| `im:chat:read` \|
206	\| `chats.link` \| `im:chat:read` \|
207	\| `chats.update` \| `im:chat:update` \|
208	\| `chat.members.create` \| `im:chat.members:write_only` \|
209	\| `chat.members.delete` \| `im:chat.members:write_only` \|
210	\| `chat.members.get` \| `im:chat.members:read` \|
211	\| `+chat-members-list` \| `im:chat.members:read` \|
212	\| `chat.user_setting.batch_query` \| `im:chat.user_setting:read` \|
213	\| `chat.user_setting.batch_update` \| `im:chat.user_setting:write` \|
214	\| `chat.managers.add_managers` \| `im:chat.managers:write_only` \|
215	\| `chat.managers.delete_managers` \| `im:chat.managers:write_only` \|
216	\| `chat.moderation.get` \| `im:chat.moderation:read` \|
217	\| `chat.moderation.update` \| `im:chat:moderation:write_only` \|
218	\| `messages.delete` \| `im:message:recall` \|
219	\| `messages.forward` \| `im:message` \|
220	\| `messages.merge_forward` \| `im:message` \|
221	\| `messages.read_users` \| `im:message:readonly` \|
222	\| `messages.urgent_app` \| `im:message.urgent` \|
223	\| `messages.urgent_phone` \| `im:message.urgent:phone` \|
224	\| `messages.urgent_sms` \| `im:message.urgent:sms` \|
225	\| `reactions.batch_query` \| `im:message.reactions:read` \|
226	\| `reactions.create` \| `im:message.reactions:write_only` \|
227	\| `reactions.delete` \| `im:message.reactions:write_only` \|
228	\| `reactions.list` \| `im:message.reactions:read` \|
229	\| `threads.forward` \| `im:message` \|
230	\| `images.create` \| `im:resource` \|
231	\| `pins.create` \| `im:message.pins:write_only` \|
232	\| `pins.delete` \| `im:message.pins:write_only` \|
233	\| `pins.list` \| `im:message.pins:read` \|
234	\| `feed.groups.batch_add_item` \| `im:fe

6 picks

Type

Run `npx skills use "https://github.com/larksuite/cli" --skill "larksuite/cli/lark-im"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/larksuite/cli" that are relevant to the current task. Run `npx skills add "https://github.com/larksuite/cli"` and select the relevant skills, then follow their instructions.

lark-im

How to install lark-im?

Related

lark-im

How to install lark-im?

Related