Must-read before execution
- All message reading tools in this Skill are called as the user, and can only read sessions the user has permission for
feishu_im_user_get_messagesinopen_idandchat_idmust choose one of the two- When
thread_idappears in a message, determine based on user intent whether to usefeishu_im_user_get_thread_messagesto read replies within the thread - After reading as the user, if a resource marker appears in the message content, use
feishu_im_user_fetch_resourceto download; requiresmessage_id+file_key+type
Quick index: intent → tool
| User intent | Tool | Required parameters | Common optional |
|---|---|---|---|
| Retrieve historical messages from group chats/direct chats | feishu_im_user_get_messages | chat_id or open_id (choose one of the two) | relative_time, start_time/end_time, page_size, sort_rule |
| Retrieve reply messages within a thread | feishu_im_user_get_thread_messages | thread_id（omt_xxx） | page_size, sort_rule |
| Search messages across sessions | feishu_im_user_search_messages | At least one filter condition | query, sender_ids, chat_id, relative_time, start_time/end_time, page_size |
| Download images in messages | feishu_im_user_fetch_resource | message_id, file_key（img_xxx）, type="image" | - |
| Download files/audio/video in messages | feishu_im_user_fetch_resource | message_id, file_key（file_xxx）, type="file" | - |
Core constraints
1. Time range: ensure messages are fully covered
When the user does not explicitly specify a time range, infer an appropriate relative_timebased on user intent, ensuring the returned messages fully cover the content the user cares about. When the user explicitly specifies a time, use the user's value directly.
2. Pagination: paginate as needed to retrieve more results
page_sizeRange 1-50, default 50- In the returned result, when
has_more=true, you can usepage_tokento continue retrieving the next page - Determine whether pagination is needed based on user needs: continue paginating when complete results are needed; the first page is usually enough when browsing an overview
3. Thread replies: proactively expand threads to obtain context
When retrieving historical messages, if the returned messages contain the thread_id field, it is recommended to proactively retrieve the latest 10 replies in the thread (page_size: 10, sort_rule: "create_time_desc") to provide more complete context.
| Scenario | Behavior |
|---|---|
| Retrieve historical messages and need to understand context (default) | Call feishu_im_user_get_thread_messages on discovered thread_id to retrieve the latest 10 replies |
| User requests "complete conversation", "detailed discussion", "look at the replies" | Retrieve all replies in the thread (page_size: 50, sort_rule: "create_time_asc"), paginate as needed |
| User only browses a message overview / user explicitly says not to view replies | Skip thread expansion |
Note: Thread messages do not support time filtering (Feishu API limitation), and can only be retrieved via pagination.
4. Cross-session message search
feishu_im_user_search_messages Supports searching messages across all sessions:
| Parameter | Description |
|---|---|
query |
Search keyword, matches message content |
sender_ids |
List of sender open_ids |
chat_id |
Session ID limiting the search scope |
mention_ids |
List of open_ids of mentioned users |
message_type |
Message type: file / image / media |
sender_type |
Sender type: user / bot / all (default user) |
chat_type |
Chat type: group / p2p |
Each message in the search results additionally contains chat_id、chat_type（p2p/group）、chat_name. P2P messages also have chat_partner(the other party's open_id and name).
5. Extracting image/file/media resources
The following resource markers may appear in the message content; use feishu_im_user_fetch_resource to download:
| Resource type | Marker format in content | fetch_resource parameter |
|---|---|---|
| Image |  |
message_id=om_xxx, file_key=img_xxx, type="image" |
| File | <file key="file_xxx" .../> |
message_id=om_xxx, file_key=file_xxx, type="file" |
| Audio | <audio key="file_xxx" .../> |
message_id=om_xxx, file_key=file_xxx, type="file" |
| Video | <video key="file_xxx" .../> |
message_id=om_xxx, file_key=file_xxx, type="file" |
From the message's message_id field and the file_key in the content, you can combine them to call fetch_resource.
Note: File size limit is 100MB; downloading resources in stickers and cards is not supported.
6. Time filtering
feishu_im_user_get_messages and feishu_im_user_search_messages support time filtering; thread messages do not.
| Method | Parameter | Example |
|---|---|---|
| Relative time | relative_time |
today、yesterday、this_week、last_3_days、last_24_hours |
| Exact time | start_time + end_time |
ISO 8601 format:2026-02-27T00:00:00+08:00 |
relative_timeandstart_time/end_timeare mutually exclusive, and cannot be used at the same time- Available relative_time values:
today、yesterday、day_before_yesterday、this_week、last_week、this_month、last_month、last_{N}_{unit}（unit: minutes/hours/days）
7. Choosing between open_id and chat_id
| Parameter | Format | Applicable scenario |
|---|---|---|
| chat_id | oc_xxx |
Known chat ID (either group chat or P2P) |
| open_id | ou_xxx |
Known user ID; get P2P messages with that user (automatically resolved to chat_id) |
You must choose one of the two; prefer using chat_id。
Usage scenario examples
Scenario 1: Get group chat messages and expand threads
Step 1: Get group chat messages
{ "chat_id": "oc_xxx" }
Step 2: In the returned messages, find thread_id, and expand the latest thread replies:
{ "thread_id": "omt_xxx", "page_size": 10, "sort_rule": "create_time_desc" }
Scenario 2: Search messages across chats
{ "query": "项目进度", "chat_id": "oc_xxx" }
Scenario 3: Paginate to get more messages
The first call returns has_more: true and page_token: "xxx"; continue getting:
{ "chat_id": "oc_xxx", "page_token": "xxx" }
Scenario 4: Download resources in messages
{ "message_id": "om_xxx", "file_key": "img_v3_xxx", "type": "image" }
Common errors and troubleshooting
| Error symptom | Root cause | Solution |
|---|---|---|
| Too few message results | The time range is too narrow or no time parameter was passed | Infer an appropriate relative_time |
| Incomplete messages | Did not check has_more and paginate | When has_more=true, use page_token to paginate |
| Incomplete thread discussion content | Did not expand thread_id | When thread_id is found, get the thread replies |
| "open_id and chat_id cannot be provided at the same time" | Both parameters were passed at the same time | Pass only one of them |
| "relative_time and start_time/end_time cannot be used at the same time" | Conflicting time parameters | Choose one time filtering method |
| "No P2P chat found with open_id=xxx" | No P2P chat records | Use chat_id instead, or confirm that a P2P chat exists |
| Thread message returned empty | Invalid thread_id format | Confirm it is omt_xxx format |
| Image/file download failed | file_key or message_id does not match | Confirm that file_key comes from that message_id |
| Insufficient permissions | The user is not authorized or does not have permission | Confirm that OAuth authorization has been completed and that the user is a conversation member |