lark-im-messages-search.md 11 KB
im +messages-search
Prerequisite: Read
../lark-shared/SKILL.mdfirst to understand authentication, global parameters, and safety rules.
Search Feishu messages across conversations. This shortcut automatically performs a multi-step workflow: search for message IDs, batch fetch message details, then enrich the results with chat context.
User identity only (
--as user). Bot identity is not supported.
This skill maps to the shortcut: lark-cli im +messages-search (internally calls POST /open-apis/im/v1/messages/search + batched GET /open-apis/im/v1/messages/mget, then batch-fetches chat context).
Commands
# Search by keyword
lark-cli im +messages-search --query "project progress"
# Restrict search to a specific group chat
lark-cli im +messages-search --query "weekly report" --chat-id oc_xxx
# Filter by sender (comma-separated)
lark-cli im +messages-search --query "requirement" --sender ou_xxx,ou_yyy
# Filter by attachment type
lark-cli im +messages-search --query "report" --include-attachment-type file
# Filter by chat type (group / p2p)
lark-cli im +messages-search --query "progress" --chat-type group
# Filter by sender type (user / bot)
lark-cli im +messages-search --query "reminder" --sender-type bot
# Exclude bot senders
lark-cli im +messages-search --query "reminder" --exclude-sender-type bot
# Only messages that @me
lark-cli im +messages-search --query "announcement" --is-at-me
# Combined filters + time range
lark-cli im +messages-search --query "meeting" --sender ou_xxx --chat-type group --start "2026-03-13T00:00:00+08:00" --end "2026-03-20T23:59:59+08:00"
# Specific time range (ISO 8601)
lark-cli im +messages-search --query "release" --start "2026-03-01T00:00:00+08:00" --end "2026-03-10T00:00:00+08:00"
# Output format options
lark-cli im +messages-search --query "test" --format pretty
lark-cli im +messages-search --query "test" --format table
lark-cli im +messages-search --query "test" --format csv
# Pagination
lark-cli im +messages-search --query "test" --page-token <PAGE_TOKEN>
# Auto-pagination across multiple pages
lark-cli im +messages-search --query "test" --page-all --format json
# Auto-pagination with an explicit page cap
lark-cli im +messages-search --query "test" --page-limit 5 --format json
# Preview the request without executing it
lark-cli im +messages-search --query "test" --dry-run
Parameters
| Parameter | Required | Description |
|---|---|---|
--query <text> |
No | Search keyword (may be empty when used with other filters) |
--chat-id <id> |
No | Restrict to chat IDs, comma-separated (oc_xxx,oc_yyy) |
--sender <ids> |
No | Sender open_ids, comma-separated (ou_xxx) |
--include-attachment-type <type> |
No | Attachment filter: file / image / video / link |
--chat-type <type> |
No | Chat type: group / p2p |
--sender-type <type> |
No | Sender type: user / bot |
--exclude-sender-type <type> |
No | Exclude messages from user or bot senders |
--is-at-me |
No | Only return messages that mention @me |
--start <time> |
No | Start time with local timezone offset required (e.g. 2026-03-24T00:00:00+08:00) |
--end <time> |
No | End time with local timezone offset required (e.g. 2026-03-25T23:59:59+08:00) |
--page-size <n> |
No | Page size (default 20, range 1-50) |
--page-token <token> |
No | Pagination token for the next page |
--page-all |
No | Automatically paginate through all result pages (up to 40 pages) |
--page-limit <n> |
No | Max pages to fetch when auto-pagination is enabled (default 20, max 40). Setting it explicitly also enables auto-pagination |
--format <fmt> |
No | Output format: json (default) / pretty / table / ndjson / csv |
--as <identity> |
No | Identity type (defaults to and only supports user) |
--dry-run |
No | Print the request only, do not execute it |
Core Constraints
1. Provide at least one filter whenever possible
All parameters are optional, but you should usually provide at least one filter (--query, --sender, --chat-id, etc.). Otherwise the search scope may be too broad and return low-signal results.
2. Two-step orchestration is automatic
The shortcut automatically performs:
- The search API returns matching
message_idvalues - The mget API fetches full message content for those message IDs in batch
- Chat context lookup is fetched in batch and attached to each message
The user does not need to manage the orchestration manually. When search results span multiple pages, the shortcut can also paginate automatically with --page-all or --page-limit.
3. Conversation context is enriched automatically
In JSON output, each message automatically includes conversation context:
| Field | Description |
|---|---|
chat_type |
Conversation type: p2p / group |
chat_name |
Group name (for groups) or the other participant's name (for p2p chats) |
chat_partner |
For p2p only: the other participant's open_id and name |
In pretty output, the chat column shows the chat name for groups, or "p2p" for direct messages.
Each message in JSON output contains:
| Field | Description |
|---|---|
message_id |
Message ID |
msg_type |
Message type: text, image, file, interactive, post, audio, video, system, etc. |
create_time |
Creation time |
sender |
Sender information (includes name for user senders) |
content |
Message content |
chat_id |
ID of the conversation the message belongs to |
deleted |
Whether the message has been recalled (true = recalled) |
updated |
Whether the message has been edited after sending |
mentions |
Array of @mentions in the message; each item contains {id, key, name}. Present only when the message contains @mentions |
thread_id |
Thread ID (omt_xxx) if the message has replies in a thread. Present only when replies exist |
4. Pagination behavior
- Default behavior is still single-page.
--page-tokenis the manual continuation mechanism when you already have a token from a previous response.--page-allenables auto-pagination and uses a default cap of 40 pages.--page-limit <n>enables auto-pagination with an explicit cap. If you pass--page-limitwithout--page-all, auto-pagination is still enabled.- When auto-pagination stops because of the configured page cap, the response still includes the last
has_more/page_tokenso you can continue manually.
5. Search results contain follow-up clues
In JSON output, each message includes chat_id and thread_id (when present). Use them with other shortcuts for deeper inspection:
# View the full message stream for the conversation that contains the search result
lark-cli im +chat-messages-list --chat-id <chat_id>
# View replies in the thread that contains the search result
lark-cli im +threads-messages-list --thread <thread_id>
Resource Rendering
Search results reuse the same content formatter as other read commands. Image messages are rendered as placeholders such as [Image: img_xxx]; resource binaries are not downloaded automatically.
Use im +messages-resources-download if you need to fetch the underlying image or file bytes from a specific message.
AI Usage Guidance
Resolving chat_id from a chat name
When the user refers to a chat by name and you need its chat_id for the --chat-id filter, use +chat-search first:
# Step 1: Find the chat_id by name
lark-cli im +chat-search --query "<chat name keyword>" --format json
# Step 2: Use the chat_id to narrow down message search
lark-cli im +messages-search --query "keyword" --chat-id <chat_id>
Do not use im chats search or im chats list — always use the +chat-search shortcut.
Work Summary / Report Generation
When the user asks you to summarize work, generate a weekly report, or compile activity from chat messages, you should paginate through all available results to get a complete picture. A single page is rarely enough for thorough summarization.
Strategy
- Start with targeted filters — use
--chat-id,--sender,--start,--endto narrow the scope as much as possible before paginating. - Prefer auto-pagination — for report and summary tasks, use
--page-all --format jsonby default. If you need a bounded run, use--page-limit <n> --format json. - Accumulate before summarizing — collect all pages of messages first, then analyze and summarize. Do not summarize after the first page alone — you will miss important context.
- Fall back to
--page-tokenwhen resuming — if auto-pagination hits the configured page cap and the response still hashas_more=true, continue from the returnedpage_token. - Use
--format json— JSON output includeshas_moreandpage_tokenfields needed for pagination.prettyandtableformats are useful for reading but not for resuming pagination reliably.
Example: Weekly work summary from a project chat
# Preferred: fetch automatically
lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-all --format json
# If you need to cap the run explicitly
lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-limit 5 --format json
# If the bounded run still returns has_more=true, continue manually
lark-cli im +messages-search --query "" --chat-id oc_xxx --sender ou_me --start "2026-03-18T00:00:00+08:00" --end "2026-03-25T23:59:59+08:00" --page-size 50 --page-token <token_from_previous_run> --format json
Key points
- Always paginate exhaustively for summary tasks. A single page of 20-50 messages is usually insufficient for a meaningful work summary.
- Prefer
--page-all; use--page-limitonly when you need to bound runtime or output volume. - If the user does not specify a time range, default to the current week (Monday to today) for weekly reports, or ask for clarification.
- When summarizing, group messages by topic/thread rather than by chronological order for better readability.
Common Errors and Troubleshooting
| Symptom | Root Cause | Solution |
|---|---|---|
| Too few results | The time range is too narrow or the keyword is too specific | Expand the time range and try broader keywords |
| No results | Missing permission or no match | Confirm search:message is authorized and relax the filters |
| Permission denied | Search scope not authorized | Run auth login --scope "search:message" |
References
- lark-im - all message-related commands
- lark-im-threads-messages-list - inspect thread replies
- lark-shared - authentication and global parameters