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.

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