Feishu Chat Browsing and Management

Browse Feishu one-on-one/group chat message history, search conversations, manage group chat information and members via feishu-cli.

Prerequisites

The core commands of this skill must use User Token, please log in first.

chat create

chat link

msg read-users

use App Token and belong to the feishu-cli-toolkit skill.

bash

feishu-cli auth login

Commands will directly report an error and prompt login methods if not logged in. The token is automatically loaded after login, no need to pass parameters manually.

Identity Description

Identity	Usage Scenario
User Token (Required)	All read/management commands of this skill: chat get/update/delete, member list/add/remove, msg get/history/list/pins/reaction/search-chats, search messages
App Token	Only `chat create` , `chat link` , `msg read-users` (these three commands are not part of the core process of this skill)

User Token Capabilities:

View group chat messages that the bot is not in
View one-on-one (p2p) chat messages
Search all conversations that the user has permission to access

Automatic Downgrade Mechanism

When using User Token to call

msg history

msg list

, if the bot is not in the target group, the API will return an empty result. The CLI will automatically detect this situation and downgrade to the search + get method to retrieve messages:

List API returns empty + has_more=true → automatically switch to search mode → retrieve message content one by one

This process is transparent to users, no manual intervention required.

Scenario 1: View Group Chat History Messages

This is the most common scenario - users want to see what a group has been discussing recently.

Step 1: Locate the Group Chat

If the user provides a group name instead of chat_id, search first:

bash

feishu-cli msg search-chats --query "group name keywords" -o json

The

chat_id

(in the format

oc_xxx

) in the output is the identifier required for subsequent commands.

Step 2: Retrieve Messages

bash

# Get the latest 50 messages (API single request limit is 50)
feishu-cli msg history \
  --container-id oc_xxx \
  --container-id-type chat \
  --page-size 50 \
  --sort-type ByCreateTimeDesc \
  -o json

# Retrieve by time range (--start-time is a millisecond timestamp, only returns messages after this time)
feishu-cli msg history \
  --container-id oc_xxx \
  --container-id-type chat \
  --page-size 50 \
  --start-time 1773778860000 \
  --sort-type ByCreateTimeDesc \
  -o json

# Retrieve older messages (use the page_token returned from the previous page for pagination)
feishu-cli msg history \
  --container-id oc_xxx \
  --container-id-type chat \
  --page-size 50 \
  --page-token "token returned from previous page" \
  -o json

Step 2.5: Determine Group Type and Retrieve Thread Replies

Feishu group chats are divided into regular groups and topic groups, with completely different message structures and retrieval strategies.

How to Determine Group Type

Observe the message fields returned by

msg history

Group Type	Characteristics	Example
Topic Group	Every message has a `thread_id` (in the format `omt_xxx` ), the main message stream only contains the first message of each topic	Thai Chinese Business Group
Regular Group	Independent messages have no `thread_id` , only replied messages and reply messages have `thread_id`	Claude Code Casual Chat Group

Thread-related Fields in Messages

Field	Description	Occurrence Condition
`thread_id`	Thread/topic ID (in the format `omt_xxx` )	All messages in topic groups / messages participating in threads in regular groups
`root_id`	Thread root message ID (i.e., the first message of the topic)	Thread reply messages
`parent_id`	Direct parent message ID (the message being replied to)	Thread reply messages

Regular Group: Retrieve All Messages at Once

msg history

for regular groups returns all messages (independent messages + thread replies), flattened in the same list. The reply relationship can be reconstructed via

root_id

parent_id

, no need to retrieve threads additionally.

Independent message:       No thread_id, no root_id
Replied message:   Has thread_id (automatically generated after being replied)
Thread reply:       Has thread_id + root_id + parent_id

Topic Group: Need to Retrieve Replies by Topic (Important)

msg history --container-id-type chat

for topic groups only returns the first message of each topic, thread replies are not in the main message stream. You must retrieve them individually by thread_id:

bash

# Retrieve all replies of a single topic (sorted in chronological order for easy reading)
feishu-cli msg history \
  --container-id omt_xxx \
  --container-id-type thread \
  --page-size 50 \
  --sort-type ByCreateTimeAsc \
  -o json

Complete Topic Group Retrieval Process:

bash

# 1. Retrieve the main message stream (first message of each topic)
feishu-cli msg history \
  --container-id oc_xxx \
  --container-id-type chat \
  --page-size 50 \
  --sort-type ByCreateTimeDesc \
  -o json

# 2. Extract all thread_id from the returned results

# 3. Retrieve replies for each thread_id (can be executed concurrently to improve efficiency)
feishu-cli msg history --container-id omt_xxx --container-id-type thread --page-size 50 --sort-type ByCreateTimeAsc -o json
feishu-cli msg history --container-id omt_yyy --container-id-type thread --page-size 50 --sort-type ByCreateTimeAsc -o json
# ... Multiple topics can be retrieved in parallel

Performance Tip: Active topics in topic groups may have 10-20 entries, it is recommended to retrieve multiple topics concurrently. Feishu API has no strict QPS limit for
msg history
(unlike the Search API), so concurrent calls are safe.

Step 3: Parse Message Content

The

body.content

returned by the API is a JSON string, common formats:

msg_type	content Format	Description
text	`{"text":"message content"}`	Plain text, `@_user_1` is an at placeholder
post	Rich text JSON	Contains title and paragraph structure
image	`{"image_key":"xxx"}`	Image
interactive	Card JSON	Interactive card
share_calendar_event	`{"summary":"meeting name","start_time":"ms","end_time":"ms",...}`	Calendar event share
sticker	`{"sticker_key":"xxx"}`	Sticker
file	`{"file_key":"xxx","file_name":"..."}`	File

Common way to extract text content using Python:

python

import json
content = json.loads(msg['body']['content'])
text = content.get('text', '')

Complete Example: Retrieve and Summarize the Latest N Messages of a Group Chat

bash

# 1. Search for the group chat
feishu-cli msg search-chats --query "Go Discussion Group" -o json

# 2. Retrieve messages (loop pagination until enough messages are obtained)
feishu-cli msg history \
  --container-id oc_xxx \
  --container-id-type chat \
  --page-size 50 \
  --sort-type ByCreateTimeDesc \
  -o json > /tmp/chat_page1.json

# 3. Extract page_token to retrieve the next page
# ... Loop until enough messages are obtained or has_more=false

Note: The page_size of the Search API is different from that of the List API, the actual number of returned items per page may be less than the requested value in downgrade mode. It is recommended to loop pagination until
has_more=false
or the target number is reached.

Scenario 2: View One-on-one Chat History with Someone

Feishu Open API does not support directly querying p2p chat records by user. It needs to be implemented indirectly through the Search API.

Method: Search + Filter

bash

# Search one-on-one chat messages
feishu-cli search messages "keywords" \
  --chat-type p2p_chat \
  -o json

# If you know the other party's open_id, filter by sender
feishu-cli search messages "keywords" \
  --chat-type p2p_chat \
  --from-ids ou_xxx \
  -o json

# Retrieve details of a single message
feishu-cli msg get om_xxx -o json

Find User ID

If the user only provides an email or mobile phone number, you can find the corresponding open_id:

bash

# Find user by email
feishu-cli user search --email user@example.com -o json

# Find user by mobile phone number
feishu-cli user search --mobile 13800138000 -o json

Note:
user search
only supports exact search via
--email
and
--mobile
, fuzzy search by name is not supported.

Restrictions

The
```
query
```
parameter of the Search API cannot be empty, at least one space
```
" "
```
is required
p2p chats cannot be searched via
```
msg search-chats
```
(this API only searches group chats)
The search results return a list of message IDs, you need to call
```
msg get
```
one by one to get the complete content
msg get
may return error 230001 for one-on-one chat messages (API restriction: some one-on-one chat messages do not support getting details via the Get API), in this case, you can only rely on the summary information in the search results

Scenario 3: Search Group Chats

Search Group Chat List

bash

# Search group chats by keyword
feishu-cli msg search-chats --query "keywords" -o json

# Retrieve all groups with pagination
feishu-cli msg search-chats --page-size 100 -o json

Search Messages Within a Group

bash

# Search messages in a specified group
feishu-cli search messages "keywords" --chat-ids oc_xxx -o json

More Search Features (by time range, message type, sender, cross-module search for documents/apps, etc.) Please use the feishu-cli-search skill, which provides complete filtering parameters and Token troubleshooting guides.

Scenario 4: Group Chat Information Management

View Group Information

bash

feishu-cli chat get oc_xxx

The default output is in JSON format, including group name, description, group owner, group type, member count, etc.

View Group Members

bash

# Retrieve member list
feishu-cli chat member list oc_xxx

# Specify ID type
feishu-cli chat member list oc_xxx --member-id-type user_id

# Retrieve with pagination (for large groups)
feishu-cli chat member list oc_xxx --page-size 100 --page-token "xxx"

Scope Requirement: When using User Token, the
im:chat:readonly
or
im:chat.members:read
scope is required. If error 99991679 is reported, re-authorize via
auth login --scopes "... im:chat:readonly"
.

Modify Group Information

bash

# Change group name
feishu-cli chat update oc_xxx --name "new group name"

# Change group description
feishu-cli chat update oc_xxx --description "new group description"

# Transfer group ownership
feishu-cli chat update oc_xxx --owner-id ou_xxx

Group Member Management

bash

# Add members
feishu-cli chat member add oc_xxx --id-list ou_xxx,ou_yyy

# Remove members
feishu-cli chat member remove oc_xxx --id-list ou_xxx

# Use user_id type
feishu-cli chat member add oc_xxx --id-list user_xxx --member-id-type user_id

Create Group Chat

bash

feishu-cli chat create --name "new group chat" --user-ids ou_xxx,ou_yyy

Note:
chat create
and
chat link
(get share link) only support App Token (tenant identity), not User Token.

Dissolve Group Chat

bash

feishu-cli chat delete oc_xxx
# Confirmation is required, irreversible operation

Scenario 5: Message Details and Interaction

Retrieve Details of a Single Message

bash

feishu-cli msg get om_xxx -o json

View Message Read Status

bash

feishu-cli msg read-users om_xxx -o json

Restriction: Only supports querying messages sent by the bot itself within 7 days, and the bot must be in the conversation. This command only uses App Token.

View Pinned Messages in Group

bash

feishu-cli msg pins --chat-id oc_xxx -o json

Pin/Unpin Messages

bash

# Pin message
feishu-cli msg pin <message_id>

# Unpin message
feishu-cli msg unpin <message_id>

Reaction Emoji Responses

bash

# Add emoji
feishu-cli msg reaction add <message_id> --emoji-type THUMBSUP

# Remove emoji
feishu-cli msg reaction remove <message_id> --reaction-id <REACTION_ID>

# Query emoji list
feishu-cli msg reaction list <message_id> [--emoji-type THUMBSUP] [--page-size 20]

Common emoji-type:

THUMBSUP

(Like),

SMILE

(Smile),

LAUGH

(Laugh),

HEART

(Love),

JIAYI

(Plus One),

OK

FIRE

Delete Message

Only messages sent by the bot itself can be deleted, and it is irreversible.

bash

feishu-cli msg delete <message_id>

Quick Reference Table for Common Operations

User Intent	Command	Token
View recent messages of a group	`msg history --container-id oc_xxx --container-id-type chat`	User
View thread replies of a topic group	`msg history --container-id omt_xxx --container-id-type thread`	User
View chat with someone	`search messages " " --chat-type p2p_chat --from-ids ou_xxx`	User
Search group chats	`msg search-chats --query "keywords"`	User
Search messages within a group	`search messages "keywords" --chat-ids oc_xxx`	User
Check group information	`chat get oc_xxx`	User
Check group members	`chat member list oc_xxx`	User
Change group name/owner	`chat update oc_xxx --name "new name"`	User
Add/remove group members	`chat member add/remove oc_xxx --id-list xxx`	User
Check message details	`msg get om_xxx`	User
View pinned messages	`msg pins --chat-id oc_xxx`	User
Pin/unpin message	`msg pin/unpin <message_id>`	User
Add Reaction	`msg reaction add <message_id> --emoji-type THUMBSUP`	User
Delete message	`msg delete <message_id>`	User
Check message read status	`msg read-users om_xxx`	App (only bot messages)
Create group chat	`chat create --name "group name"`	App
Get group link	`chat link oc_xxx`	App

Commands marked User must be preceded by
auth login
, an error will be reported if not logged in. Commands marked App use application identity, no login required.

Best Practices for Handling Large Volumes of Messages

When you need to retrieve and analyze a large number of messages (e.g., 100+):

Save to File: Output each page result with
```
-o json
```
and redirect to a file
Loop Pagination: Check
```
HasMore
```
and
```
PageToken
```
, loop retrieval until conditions are met
Parse with Python: The JSON message structure requires parsing
```
body.content
```
to extract text
Pay Attention to Rate Limits: The Search API has frequency limits, add a 1s delay between large numbers of requests;
```
msg history
```
has looser rate limits, concurrent calls are safe
Timestamp:
```
create_time
```
is a millisecond timestamp, divide by 1000 to convert to seconds
Concurrent Thread Retrieval for Topic Groups: Topic groups require separate calls to
```
msg history --container-id-type thread
```
for each
```
thread_id
```
, it is recommended to call multiple topics in parallel to improve efficiency (10-20 concurrent calls are tested to be problem-free)
Recalled Messages: Messages with
```
deleted: true
```
have content
```
"This message was recalled"
```
, they should be skipped during summarization

python

import json
from datetime import datetime

# Parse message time
ts = int(msg['create_time']) / 1000
dt = datetime.fromtimestamp(ts)
time_str = dt.strftime('%Y-%m-%d %H:%M')

# Extract text content
content = json.loads(msg['body']['content'])
text = content.get('text', '')

Permission Requirements

scope	Description	Corresponding Commands
`im:message:readonly`	Message reading	msg get/history/list
`im:message.group_msg:get_as_user`	Read group messages as User identity	msg history/list (required for reading group messages)
`im:message.pins`	Message pin management	msg pin/unpin/pins
`im:message.reactions`	Message Reaction	msg reaction add/remove/list
`im:message`	Message read/write	msg delete
`im:chat:read`	Group chat search	msg search-chats
`im:chat:readonly`	Group chat information read-only	chat get, chat member list
`im:chat.members:read`	Group member reading	chat member list
`im:chat`	Group chat management	chat update/delete
`im:chat.members`	Group member management	chat member add/remove
`search:message`	Message search	search messages

Division of Labor with Other Skills

Scenario	Skill to Use
Browse chat history, search group chats, group information/member management, Reaction/Pin/delete/get messages	feishu-cli-chat (this skill)
Send messages, reply, forward/merge forward	feishu-cli-msg
Search documents/apps, advanced message search (multi-condition filtering)	feishu-cli-search
Sheets, calendar, tasks, files, knowledge base and other modules	feishu-cli-toolkit
OAuth login, Token management	feishu-cli-auth

feishu-cli-chat

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Chat Browsing and Management

Prerequisites

Identity Description

Automatic Downgrade Mechanism

Scenario 1: View Group Chat History Messages

Step 1: Locate the Group Chat

Step 2: Retrieve Messages

Step 2.5: Determine Group Type and Retrieve Thread Replies

How to Determine Group Type

Thread-related Fields in Messages

Regular Group: Retrieve All Messages at Once

Topic Group: Need to Retrieve Replies by Topic (Important)

Step 3: Parse Message Content

Complete Example: Retrieve and Summarize the Latest N Messages of a Group Chat

Scenario 2: View One-on-one Chat History with Someone

Method: Search + Filter

Find User ID

Restrictions

Scenario 3: Search Group Chats

Search Group Chat List

Search Messages Within a Group

Scenario 4: Group Chat Information Management

View Group Information

View Group Members

Modify Group Information

Group Member Management

Create Group Chat

Dissolve Group Chat

Scenario 5: Message Details and Interaction

Retrieve Details of a Single Message

View Message Read Status

View Pinned Messages in Group

Pin/Unpin Messages

Reaction Emoji Responses

Delete Message

Quick Reference Table for Common Operations

Best Practices for Handling Large Volumes of Messages

Permission Requirements

Division of Labor with Other Skills