lark-im

SkillCommunityAudit warningsTranslated from Chinese

This skill provides comprehensive management for Lark instant messaging, including sending and receiving messages, managing group chats, and handling file transfers. It supports both user and bot identities to perform tasks like searching chat history, managing group members, and interacting with message reactions or bookmarks.

Compatibility:

Install:

npx skills add larksuite/cli/lark-im

View on skills.sh

im (v1)

CRITICAL, MUST read ../lark-shared/SKILL.md before starting, as it contains authentication and permission handling.

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 (Recommended)

Shortcuts are high-level wrappers for common operations (lark-cli im +<verb> [flags]). Use shortcuts whenever available.

Shortcut	Description
`+chat-create`	Create a group chat or topic chat; user/bot; --chat-mode group
`+chat-list`	List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only)
`+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 --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)
`+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); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key
`+messages-resources-download`	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`	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`	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`	List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination
`+flag-create`	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`	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`	List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination

API Resources

lark-cli schema im.<resource>.<method>   # Check parameter structure before calling API
lark-cli im <resource> <method> [flags] # Call API

Important: When using native APIs, you must run schema first to view the --data / --params structure. Do not guess field formats.

chats

create, Create a group. Identity: bot only (tenant_access_token).
get, Get group information. 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, Get group share 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.
update, Update group information. Identity: supports user and bot.

chat.members

bots, Get list of bots in the group. Identity: supports user and bot; the caller must be in the target chat and must belong to the same tenant for internal chats.
create, Add users or bots to the group chat. 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, Remove users or bots from the group chat. Identity: supports user and bot; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
get, Get group member list. 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, Recall a message. 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, Forward a message. Identity: supports user and bot.
merge_forward, Merge and forward messages. Identity: bot only (tenant_access_token).
read_users, Query message read status. 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, Batch get message reactions. Identity: supports user and bot.Must-read
create, Add a message reaction. Identity: supports user and bot; the caller must be in the conversation that contains the message.Must-read
delete, Delete a message reaction. 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, Get message reactions. Identity: supports user and bot; the caller must be in the conversation that contains the message.Must-read

threads

forward, Forward a thread. Identity: supports user and bot.

images

create, Upload an image. Identity: bot only (tenant_access_token).

pins

create, Pin a message. Identity: supports user and bot.
delete, Remove a pinned message. Identity: supports user and bot.
list, Get pinned messages in a group. Identity: supports user and bot.

Permission Table

Method	Required scope
`chats.create`	`im:chat:create`
`chats.get`	`im:chat:read`
`chats.link`	`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`

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

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`	Create a group chat or topic chat; user/bot; --chat-mode group
`+chat-list`	List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only)
`+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 --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)
`+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); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key
`+messages-resources-download`	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`	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`	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`	List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination
`+flag-create`	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`	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`	List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-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.
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
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

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

Categories:

Communication

Share:

Details:

Installs
264,350
First seen
Jun 10, 2026

Security audits

Gen Agent Trust HubPASS

SocketPASS

SnykWARN (medium risk)

ZeroLeaksPASS

View Repository

Auto-fetched from GitHub 10 hours ago.

Stats via skills.sh.

Skills similar to lark-im:

Installs

Installs

Installs

lark-im

SkillCommunityAudit warningsTranslated from Chinese

This skill provides comprehensive management for Lark instant messaging, including sending and receiving messages, managing group chats, and handling file transfers. It supports both user and bot identities to perform tasks like searching chat history, managing group members, and interacting with message reactions or bookmarks.

Compatibility:

Install:

npx skills add larksuite/cli/lark-im

View on skills.sh

im (v1)

CRITICAL, MUST read ../lark-shared/SKILL.md before starting, as it contains authentication and permission handling.

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

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

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 (Recommended)

Shortcuts are high-level wrappers for common operations (lark-cli im +<verb> [flags]). Use shortcuts whenever available.

Shortcut	Description
`+chat-create`	Create a group chat or topic chat; user/bot; --chat-mode group
`+chat-list`	List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only)
`+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 --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)
`+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); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key
`+messages-resources-download`	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`	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`	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`	List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination
`+flag-create`	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`	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`	List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination

API Resources

lark-cli schema im.<resource>.<method>   # Check parameter structure before calling API
lark-cli im <resource> <method> [flags] # Call API

Important: When using native APIs, you must run schema first to view the --data / --params structure. Do not guess field formats.

chats

create, Create a group. Identity: bot only (tenant_access_token).
get, Get group information. 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, Get group share 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.
update, Update group information. Identity: supports user and bot.

chat.members

bots, Get list of bots in the group. Identity: supports user and bot; the caller must be in the target chat and must belong to the same tenant for internal chats.
create, Add users or bots to the group chat. 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, Remove users or bots from the group chat. Identity: supports user and bot; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
get, Get group member list. 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, Recall a message. 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, Forward a message. Identity: supports user and bot.
merge_forward, Merge and forward messages. Identity: bot only (tenant_access_token).
read_users, Query message read status. 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, Batch get message reactions. Identity: supports user and bot.Must-read
create, Add a message reaction. Identity: supports user and bot; the caller must be in the conversation that contains the message.Must-read
delete, Delete a message reaction. 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, Get message reactions. Identity: supports user and bot; the caller must be in the conversation that contains the message.Must-read

threads

forward, Forward a thread. Identity: supports user and bot.

images

create, Upload an image. Identity: bot only (tenant_access_token).

pins

create, Pin a message. Identity: supports user and bot.
delete, Remove a pinned message. Identity: supports user and bot.
list, Get pinned messages in a group. Identity: supports user and bot.

Permission Table

Method	Required scope
`chats.create`	`im:chat:create`
`chats.get`	`im:chat:read`
`chats.link`	`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`

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

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

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`	Create a group chat or topic chat; user/bot; --chat-mode group
`+chat-list`	List groups the current user/bot is a member of; user/bot; supports sorting, pagination, and --exclude-muted (user identity only)
`+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 --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)
`+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); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key
`+messages-resources-download`	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`	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`	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`	List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination
`+flag-create`	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`	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`	List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-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.
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
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

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