Back to Details

feishu-im-read

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

飞书 IM 消息读取

Feishu IM Message Reading

执行前必读

Pre-execution Notes

  • 该 Skill 中的所有消息读取工具均以用户身份调用，只能读取用户有权限的会话
  • feishu_im_user_get_messages
    中 
    open_id
    和 
    chat_id
    必须二选一
  • 消息中出现 
    thread_id
    时，根据用户意图判断是否用 
    feishu_im_user_get_thread_messages
    读取话题内回复
  • 以用户身份读取后，如果消息内容中出现资源标记时，用 
    feishu_im_user_fetch_resource
    下载，需要 
    message_id
    + 
    file_key
    + 
    type
  • All message reading tools in this Skill are called with user identity, and can only read sessions that the user has permission to access
  • In 
    feishu_im_user_get_messages
    , either 
    open_id
    or 
    chat_id
    must be provided (not both)
  • When 
    thread_id
    appears in a message, judge whether to use 
    feishu_im_user_get_thread_messages
    to read thread replies based on user intent
  • After reading with user identity, if resource markers appear in the message content, use 
    feishu_im_user_fetch_resource
    to download, which requires 
    message_id
    + 
    file_key
    + 
    type

快速索引：意图 → 工具

Quick Index: Intent → Tool

用户意图工具必填参数常用可选
获取群聊/单聊历史消息feishu_im_user_get_messageschat_id 或 open_id（二选一）relative_time, start_time/end_time, page_size, sort_rule
获取话题内回复消息feishu_im_user_get_thread_messagesthread_id（omt_xxx）page_size, sort_rule
跨会话搜索消息feishu_im_user_search_messages至少一个过滤条件query, sender_ids, chat_id, relative_time, start_time/end_time, page_size
下载消息中的图片feishu_im_user_fetch_resourcemessage_id, file_key（img_xxx）, type="image"-
下载消息中的文件/音频/视频feishu_im_user_fetch_resourcemessage_id, file_key（file_xxx）, type="file"-
User IntentToolRequired ParametersCommon Optional Parameters
Retrieve historical messages of group/one-on-one chatsfeishu_im_user_get_messageschat_id or open_id (choose one)relative_time, start_time/end_time, page_size, sort_rule
Retrieve reply messages in threadsfeishu_im_user_get_thread_messagesthread_id (omt_xxx)page_size, sort_rule
Search messages across sessionsfeishu_im_user_search_messagesAt least one filter conditionquery, sender_ids, chat_id, relative_time, start_time/end_time, page_size
Download images in messagesfeishu_im_user_fetch_resourcemessage_id, file_key (img_xxx), type="image"-
Download files/audio/video in messagesfeishu_im_user_fetch_resourcemessage_id, file_key (file_xxx), type="file"-

核心约束

Core Constraints

1. 时间范围：确保消息覆盖完整

1. Time Range: Ensure Complete Message Coverage

当用户没有明确指定时间范围时，根据用户意图推断合适的 
relative_time
，确保返回的消息能完整覆盖用户关心的内容。用户明确指定时间时直接使用用户的值。
When the user does not specify a time range explicitly, infer an appropriate 
relative_time
based on user intent to ensure the returned messages fully cover the content the user cares about. Use the user-specified value directly when the time is clearly indicated.

2. 分页：根据需要翻页获取更多结果

2. Pagination: Retrieve More Results as Needed

  • page_size
    范围 1-50，默认 50
  • 返回结果中 
    has_more=true
    时，可使用 
    page_token
    继续获取下一页
  • 根据用户需求判断是否需要翻页：需要完整结果时继续翻页，浏览概览时第一页通常够用
  • page_size
    ranges from 1 to 50, default is 50
  • When 
    has_more=true
    is returned in the result, use 
    page_token
    to continue fetching the next page
  • Judge whether pagination is needed based on user needs: continue pagination when complete results are required, the first page is usually sufficient for overview browsing

3. 话题回复：主动展开话题获取上下文

3. Thread Replies: Actively Expand Threads to Obtain Context

获取历史消息时，返回的消息中如果包含 
thread_id
字段，推荐主动获取话题的最新 10 条回复（
page_size: 10, sort_rule: "create_time_desc"
）以提供更完整的上下文。
场景行为
获取历史消息并需要理解上下文（默认）对发现的 thread_id 调用 
feishu_im_user_get_thread_messages
获取最新 10 条回复
用户要求"完整对话"、"详细讨论"、"看看回复"获取话题全部回复（
page_size: 50, sort_rule: "create_time_asc"
），需要时翻页
用户只浏览消息概览 / 用户明确说不看回复跳过话题展开
注意：话题消息不支持时间过滤（飞书 API 限制），只能通过分页获取。
When retrieving historical messages, if the returned message contains a 
thread_id
field, it is recommended to actively fetch the latest 10 replies of the thread (
page_size: 10, sort_rule: "create_time_desc"
) to provide more complete context.
ScenarioAction
Retrieve historical messages and need to understand context (default)Call 
feishu_im_user_get_thread_messages
for detected thread_id to get the latest 10 replies
User requests "complete conversation", "detailed discussion", "check replies"Fetch all thread replies (
page_size: 50, sort_rule: "create_time_asc"
), paginate if necessary
User only browses message overview / User explicitly says not to view repliesSkip thread expansion
Note: Thread messages do not support time filtering (Feishu API restriction), and can only be obtained through pagination.

4. 跨会话消息搜索

4. Cross-session Message Search

feishu_im_user_search_messages
支持跨所有会话搜索消息：
参数说明
query
搜索关键词，匹配消息内容
sender_ids
发送者 open_id 列表
chat_id
限定搜索范围的会话 ID
mention_ids
被@用户的 open_id 列表
message_type
消息类型：file / image / media
sender_type
发送者类型：user / bot / all（默认 user）
chat_type
会话类型：group / p2p
搜索结果每条消息额外包含 
chat_id
、
chat_type
（p2p/group）、
chat_name
。单聊消息还有 
chat_partner
（对方 open_id 和名字）。
feishu_im_user_search_messages
supports searching messages across all sessions:
ParameterDescription
query
Search keywords, matching message content
sender_ids
List of sender open_ids
chat_id
Session ID to limit 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 is user)
chat_type
Session type: group / p2p
Each message in the search results additionally includes 
chat_id
, 
chat_type
(p2p/group), 
chat_name
. One-on-one chat messages also have 
chat_partner
(the other party's open_id and name).

5. 图片/文件/媒体资源的提取

5. Extraction of Images/Files/Media Resources

消息内容中可能出现以下资源标记，用 
feishu_im_user_fetch_resource
下载：
资源类型内容中的标记格式fetch_resource 参数
图片
![image](img_xxx)
message_id=
om_xxx
, file_key=
img_xxx
, type=
"image"
文件
<file key="file_xxx" .../>
message_id=
om_xxx
, file_key=
file_xxx
, type=
"file"
音频
<audio key="file_xxx" .../>
message_id=
om_xxx
, file_key=
file_xxx
, type=
"file"
视频
<video key="file_xxx" .../>
message_id=
om_xxx
, file_key=
file_xxx
, type=
"file"
从消息的 
message_id
字段和内容中的 
file_key
组合即可调用 fetch_resource。
注意：文件大小限制 100MB，不支持下载表情包、卡片中的资源。
The following resource markers may appear in message content, use 
feishu_im_user_fetch_resource
to download:
Resource TypeMarker Format in Contentfetch_resource Parameters
Image
![image](img_xxx)
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"
Combine the 
message_id
field of the message and the 
file_key
in the content to call fetch_resource.
Note: File size limit is 100MB, downloading stickers and resources in cards is not supported.

6. 时间过滤

6. Time Filtering

feishu_im_user_get_messages
和 
feishu_im_user_search_messages
支持时间过滤，话题消息不支持。
方式参数示例
相对时间
relative_time
today
、
yesterday
、
this_week
、
last_3_days
、
last_24_hours
精确时间
start_time
+ 
end_time
ISO 8601 格式：
2026-02-27T00:00:00+08:00
  • relative_time
    和 
    start_time/end_time
    互斥，不能同时使用
  • 可用的 relative_time 值：
    today
    、
    yesterday
    、
    day_before_yesterday
    、
    this_week
    、
    last_week
    、
    this_month
    、
    last_month
    、
    last_{N}_{unit}
    （unit: minutes/hours/days）
feishu_im_user_get_messages
and 
feishu_im_user_search_messages
support time filtering, while thread messages do not.
MethodParameterExample
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_time
    and 
    start_time/end_time
    are 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. open_id 与 chat_id 的选择

7. Selection of open_id and chat_id

参数格式适用场景
chat_id
oc_xxx
已知会话 ID（群聊或单聊均可）
open_id
ou_xxx
已知用户 ID，获取与该用户的单聊消息（自动解析为 chat_id）
两者必须二选一，优先使用 
chat_id
。
ParameterFormatApplicable Scenario
chat_id
oc_xxx
Known session ID (applicable to both group chats and one-on-one chats)
open_id
ou_xxx
Known user ID, retrieve one-on-one chat messages with this user (automatically parsed to chat_id)
Choose one of the two, priority is given to 
chat_id
.

使用场景示例

Usage Scenario Examples

场景 1: 获取群聊消息并展开话题

Scenario 1: Retrieve Group Chat Messages and Expand Threads

步骤 1：获取群聊消息
json
{ "chat_id": "oc_xxx" }
步骤 2：返回的消息中发现 
thread_id
，展开话题最新回复：
json
{ "thread_id": "omt_xxx", "page_size": 10, "sort_rule": "create_time_desc" }
Step 1: Retrieve group chat messages
json
{ "chat_id": "oc_xxx" }
Step 2: Detect 
thread_id
in the returned message, expand the latest thread replies:
json
{ "thread_id": "omt_xxx", "page_size": 10, "sort_rule": "create_time_desc" }

场景 2: 跨会话搜索消息

Scenario 2: Cross-session Message Search

json
{ "query": "项目进度", "chat_id": "oc_xxx" }
json
{ "query": "project progress", "chat_id": "oc_xxx" }

场景 3: 分页获取更多消息

Scenario 3: Retrieve More Messages via Pagination

第一次调用返回 
has_more: true
和 
page_token: "xxx"
，继续获取：
json
{ "chat_id": "oc_xxx", "page_token": "xxx" }
The first call returns 
has_more: true
and 
page_token: "xxx"
, continue fetching:
json
{ "chat_id": "oc_xxx", "page_token": "xxx" }

场景 4: 下载消息中的资源

Scenario 4: Download Resources in Messages

json
{ "message_id": "om_xxx", "file_key": "img_v3_xxx", "type": "image" }
json
{ "message_id": "om_xxx", "file_key": "img_v3_xxx", "type": "image" }

常见错误与排查

Common Errors and Troubleshooting

错误现象根本原因解决方案
消息结果太少时间范围太窄或未传时间参数根据用户意图推断合适的 
relative_time
消息不完整没有检查 has_more 并翻页has_more=true 时用 page_token 翻页
话题讨论内容不完整没有展开 thread_id发现 thread_id 时获取话题回复
"open_id 和 chat_id 不能同时提供"同时传了两个参数只传其中一个
"relative_time 和 start_time/end_time 不能同时使用"时间参数冲突选择一种时间过滤方式
"未找到与 open_id=xxx 的单聊会话"没有单聊记录改用 chat_id，或确认存在单聊
话题消息返回为空thread_id 格式不正确确认为 
omt_xxx
格式
图片/文件下载失败file_key 或 message_id 不匹配确认 file_key 来自该 message_id
权限不足用户未授权或无权限确认已完成 OAuth 授权且是会话成员
Error PhenomenonRoot CauseSolution
Too few message resultsTime range is too narrow or time parameter is not passedInfer an appropriate 
relative_time
based on user intent
Incomplete messagesDid not check has_more and paginateUse page_token to paginate when has_more=true
Incomplete thread discussion contentDid not expand thread_idFetch thread replies when thread_id is detected
"open_id and chat_id cannot be provided at the same time"Passed both parametersOnly pass one of them
"relative_time and start_time/end_time cannot be used at the same time"Time parameter conflictChoose one time filtering method
"No one-on-one chat session found with open_id=xxx"No one-on-one chat record existsUse chat_id instead, or confirm the existence of one-on-one chat
Empty thread message returnIncorrect thread_id formatEnsure it is in 
omt_xxx
format
Image/file download failedfile_key or message_id does not matchConfirm file_key comes from the corresponding message_id
Insufficient permissionsUser has not authorized or has no permissionConfirm OAuth authorization is completed and the user is a member of the session