Feishu Group Manager

Quick Reference

Operation	Command	Billed
Check permissions	check_permissions	Free
Get access token	get_token	Free
List all groups	list_chats	Free
Find group by name	find_chat --name	Free
List group members	list_members --chat_id	Free
Search user by name	find_user --name	Free
Add member to group	add_member	0.002 USDT
Remove member	remove_member	0.002 USDT
Send message	send_message	0.002 USDT
Rename group	rename_chat	0.002 USDT
Create group	create_chat	0.002 USDT

When a write operation returns {"error": "payment_required", ...}: stop, show the message field to the user, and wait for them to top up before retrying.

---

First Use: Credential Check + Permission Verification

The user is already chatting via Feishu, so the app exists and credentials are configured. No need to ask them to set anything up.

Credentials are resolved automatically in this order:

1. Environment variables FEISHU_APP_ID / FEISHU_APP_SECRET
2. ~/.openclaw/openclaw.json → channels.feishu.accounts.<any>.appId / appSecret

On the first request of a session, run:

python3 {baseDir}/scripts/feishu.py check_permissions

If all_ok: true — proceed directly.

If all_ok: false — show the user a friendly message listing missing permissions and how to grant them, e.g.:

"Before I can manage your groups, your Feishu app needs a couple of extra permissions (takes ~2 min).

Missing:

• im:chat.member — add/remove group members
• contact:user.id:readonly — search members by name

Steps:

1. Open https://open.feishu.cn/app and find your app
2. Go to Permission Management → search and enable the permissions above
3. Go to Version Management → create a new version → submit for review
4. Once approved (usually a few minutes), let me know and I'll continue."

Re-run check_permissions after the user confirms. Cache the result for the session — only re-check if the user says they just updated permissions, or if Feishu returns error code 99991672.

---

Execution Flow

Step 1 — Understand intent

Confirm briefly in the user's language, e.g.: "Got it, I'll add Zhang San to the Marketing group."

Step 2 — Gather info

python3 {baseDir}/scripts/feishu.py get_token
python3 {baseDir}/scripts/feishu.py find_chat --token TOKEN --name "marketing"
python3 {baseDir}/scripts/feishu.py find_user --token TOKEN --name "Zhang San"

If multiple matches are returned, list them and ask the user to confirm.

Step 3 — Confirm before any write

"I'm about to add Zhang San (Marketing dept.) to Marketing Group. Confirm?"

Wait for confirmation before executing.

Step 4 — Execute and report

Success: "Done! Zhang San has been added to Marketing Group." Failure: Explain in plain language — never expose raw API errors.

---

Command Reference

# Check app permissions
python3 {baseDir}/scripts/feishu.py check_permissions

# Get tenant access token (auto-reads credentials)
python3 {baseDir}/scripts/feishu.py get_token

# List all groups
python3 {baseDir}/scripts/feishu.py list_chats --token TOKEN

# Find group by name (fuzzy)
python3 {baseDir}/scripts/feishu.py find_chat --token TOKEN --name "NAME"

# List group members
python3 {baseDir}/scripts/feishu.py list_members --token TOKEN --chat_id CHAT_ID

# Search user by name
python3 {baseDir}/scripts/feishu.py find_user --token TOKEN --name "NAME"

# Add member to group (billed)
python3 {baseDir}/scripts/feishu.py add_member \
  --token TOKEN --chat_id CHAT_ID \
  --target_user_id TARGET_UID --user_id CALLER_UID

# Remove member from group (billed)
python3 {baseDir}/scripts/feishu.py remove_member \
  --token TOKEN --chat_id CHAT_ID \
  --target_user_id TARGET_UID --user_id CALLER_UID

# Send message to group (billed)
python3 {baseDir}/scripts/feishu.py send_message \
  --token TOKEN --chat_id CHAT_ID --text "MESSAGE" --user_id CALLER_UID

# Rename group (billed)
python3 {baseDir}/scripts/feishu.py rename_chat \
  --token TOKEN --chat_id CHAT_ID --name "NEW NAME" --user_id CALLER_UID

# Create group and add members (billed)
python3 {baseDir}/scripts/feishu.py create_chat \
  --token TOKEN --name "GROUP NAME" --user_ids "uid1,uid2" --user_id CALLER_UID

--user_id is the caller's Feishu open_id — used for billing. Retrieve it from conversation context or from find_user results.

---

Error Handling

Error	Response
Group not found	"I couldn't find a group called 'X'. Could you give me the full name?"
User not found	"I couldn't find anyone called 'X'. Please check the name or provide their email."
Feishu error 99991672	Re-run check_permissions and show missing permission guidance
Token expired	Automatically re-call get_token and retry
Network error	"There was a problem reaching Feishu. Please try again in a moment."
payment_required	Show the message field (includes top-up link), stop, wait for user