im (v1)

CRITICAL, Before starting, you MUST use the Read tool to read ../lark-shared/SKILL.md, which contains information on 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.
• 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).
• 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).

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.

Default message enrichment (reactions / update_time)

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.

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

Feed Shortcut

Feed shortcuts add chats to the current user's feed sidebar. They are distinct from flags:

• Flag = bookmark on a message/thread, scoped to the user's bookmark list.
• Feed shortcut = entry in the user's feed sidebar (currently only chats).

Key limits:

• Only CHAT-type (feed_card_id is oc_xxx) is exposed via OpenAPI; doc/app/subscription shortcuts exist internally but are not yet whitelisted.
• All three operations (create/remove/list) are user-identity only, they sign with user_access_token.
• Batch size is 10 per call for create/remove; list is a one-page wrapper with opaque page_token pagination.

Shortcuts (Recommended for priority use)

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>   # Must view parameter structure before calling API
lark-cli im <resource> <method> [flags] # Call API

Important: When using native APIs, you must first run schema to view the --data / --params parameter 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 user or bot to 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 user or bot from 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, Revoke 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 message. Identity: supports user and bot.
• merge_forward, Merge 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.
• urgent_app, Send in-app urgent notification. Identity: bot only (tenant_access_token); the bot must be the message sender and must be in the conversation that contains the message.
• urgent_phone, Send phone urgent notification. Identity: bot only (tenant_access_token); the bot must be the message sender and must be in the conversation that contains the message.
• urgent_sms, Send SMS urgent notification. Identity: bot only (tenant_access_token); the bot must be the message sender and must be in the conversation that contains the message.

reactions

• batch_query, Batch get message reactions. Identity: supports user and bot.Must-read
• create, Add message reaction. Identity: supports user and bot; the caller must be in the conversation that contains the message.Must-read
• delete, Delete 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 thread. Identity: supports user and bot.

images

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

pins

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

feed.groups

• batch_add_item, Batch add feed cards to a feed group. Identity: user only (user_access_token).Must-read
• batch_query, Batch query feed groups. Identity: user only (user_access_token).Must-read
• batch_remove_item, Batch remove feed cards from a feed group. Identity: user only (user_access_token).Must-read
• create, Create a feed group. Identity: user only (user_access_token).Must-read
• delete, Delete a feed group. Identity: user only (user_access_token).Must-read
• update, Update a feed group. Identity: user only (user_access_token).Must-read

Permission Table