Feishu Toolkit

Complete Feishu (Lark) integration toolkit for AI agents. Read/write documents, fetch chat history, send files & screenshots, manage permissions, and create...

Feishu Toolkit (飞书工具箱)

A comprehensive Feishu (Lark) integration skill for AI agents. Covers 6 major capabilities:

1. 📄 Document Operations — Read, create, write, and append Feishu Docs, Sheets, Bitable, Wiki
2. 💬 Chat History — Fetch and summarize group chat messages
3. 📎 File Sending — Upload and send files to Feishu chats via REST API
4. 📸 Screenshot — Capture macOS screenshots and send to Feishu
5. 🔐 Permission Management — List, add, remove document collaborators
6. ⏰ Cron Reminders — Create scheduled recurring reminders to Feishu chats

---

Prerequisites

Feishu App Setup

1. Go to Feishu Open Platform and create an app
2. Enable required permissions:
   • im:message:send_as_bot — Send messages
   • im:resource — Upload files/images
   • docx:document — Read/write documents
   • drive:permission — Manage permissions (optional)
3. Set FEISHU_APP_ID and FEISHU_APP_SECRET environment variables

Authentication

All API calls use Feishu's tenant access token:

import requests

def get_tenant_token(app_id, app_secret):
    r = requests.post(
        'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal',
        json={'app_id': app_id, 'app_secret': app_secret}
    )
    return r.json()['tenant_access_token']

---

1. Document Operations (Read/Write/Create/Append)

Read a Document

# Fetch document content as Markdown
# Supports: doc, docx, sheet, bitable, wiki
GET /open-apis/docx/v1/documents/{document_id}/raw_content

Create a Document

POST /open-apis/docx/v1/documents
Body: {"title": "My Document"}

Write (Overwrite) a Document

# Overwrite entire document content with Markdown
POST /open-apis/docx/v1/documents/{document_id}/blocks/batch_update

Append Content (Long Documents)

For documents exceeding LLM output limits:

1. Create the document first to get a doc_token
2. Chunk content into logical sections
3. Append each chunk sequentially
4. Do NOT try to write the entire document in one call if it is very long

Wiki URL Resolution

Wiki URLs need to be resolved to actual document tokens first:

POST /open-apis/wiki/v2/spaces/get_node
Body: {"token": "wiki_token"}
# Returns the actual doc_token and doc_type

---

2. Chat History

Fetch and summarize messages from a Feishu group chat.

Fetch Messages

# GET /open-apis/im/v1/messages
params = {
    'container_id_type': 'chat',
    'container_id': chat_id,
    'page_size': 50
}

Message Types

Type	Handling
text	Extract .body.content JSON → text field
interactive	Extract text nodes from elements array
image	Note as [图片]
system	Filter out unless relevant

Pagination

If has_more=true, fetch more pages using page_token. Default: 50 messages per page.

---

3. File Sending

Send files to Feishu chats via REST API.

Upload File

# POST /open-apis/im/v1/files
headers = {'Authorization': f'Bearer {token}'}
data = {'file_type': 'stream', 'file_name': 'filename.ext'}
files = {'file': ('filename.ext', open(path, 'rb'), 'application/octet-stream')}

Supported file_type: opus, mp4, pdf, doc, xls, ppt, stream (generic)

Send File Message

# POST /open-apis/im/v1/messages
json = {
    'receive_id': chat_id,
    'msg_type': 'file',
    'content': json.dumps({'file_key': file_key})
}

---

4. Screenshot & Send

Capture macOS screenshots and send to Feishu.

# 1. Capture screenshot
SCREENSHOT_PATH="$TMPDIR/screenshot_$(date +%s).png"
screencapture -x "$SCREENSHOT_PATH"

# 2. Upload image
# POST /open-apis/im/v1/images
# data: image_type=message, file=screenshot

# 3. Send image message
# POST /open-apis/im/v1/messages
# msg_type: image, content: {"image_key": "..."}

Note: Use $TMPDIR not /tmp on macOS.

---

5. Permission Management

Manage document/file permissions.

Actions

Action	Description
list	List all collaborators
add	Add collaborator with permission level
remove	Remove a collaborator

Token Types

doc, docx, sheet, bitable, folder, file, wiki, mindnote

Member Types

email, openid, userid, unionid, openchat, opendepartmentid

Permission Levels

Level	Description
view	View only
edit	Can edit
full_access	Full access (can manage permissions)

Example: Share document

# POST /open-apis/drive/v1/permissions/{token}/members
params = {'type': 'docx'}
json = {
    'member_type': 'email',
    'member_id': '[e-mail]',
    'perm': 'edit'
}

Note: Permission management is sensitive. Use with caution.

---

6. Cron Reminders

Create recurring scheduled reminders to Feishu chats.

Before Creating

Always confirm with the user:

1. Frequency: How often? (e.g., every 10 min, every hour, daily at 9am)
2. Target: Where to send? (default: current IM conversation)

Template

cron add \
  --name "<task_name>" \
  --every "<interval>" \
  --session main \
  --system-event "[CRON] <task_name>. Send message to Feishu: '<reminder_content>'"

Interval Examples

Interval	Description
1m	Every minute
5m	Every 5 minutes
30m	Every 30 minutes
1h	Every hour
*/30 * * * *	Cron expression (with --tz)

Management

cron list          # List all tasks
cron edit <id>     # Edit task
cron rm <id>       # Delete (ask user first!)
cron runs --id <id> # View execution history
cron run <id>      # Manual trigger

---

API Reference

API	Method	Path
Tenant Token	POST	/auth/v3/tenant_access_token/internal
Read Document	GET	/docx/v1/documents/{id}/raw_content
Create Document	POST	/docx/v1/documents
Send Message	POST	/im/v1/messages
Upload File	POST	/im/v1/files
Upload Image	POST	/im/v1/images
List Messages	GET	/im/v1/messages
Manage Permissions	POST	/drive/v1/permissions/{token}/members
Resolve Wiki	POST	/wiki/v2/spaces/get_node

Base URL: https://open.feishu.cn/open-apis

---

Notes

• All APIs require tenant_access_token in the Authorization header
• File upload uses multipart/form-data
• Message sending uses application/json
• Bot can only download files it uploaded itself
• For detailed API docs, visit: https://open.feishu.cn/document