Feishu Toolkit (飞书工具箱)
A comprehensive Feishu (Lark) integration skill for AI agents. Covers 6 major capabilities:
- 📄 Document Operations — Read, create, write, and append Feishu Docs, Sheets, Bitable, Wiki
- 💬 Chat History — Fetch and summarize group chat messages
- 📎 File Sending — Upload and send files to Feishu chats via REST API
- 📸 Screenshot — Capture macOS screenshots and send to Feishu
- 🔐 Permission Management — List, add, remove document collaborators
- ⏰ Cron Reminders — Create scheduled recurring reminders to Feishu chats
Prerequisites
Feishu App Setup
- Go to Feishu Open Platform and create an app
- Enable required permissions:
im:message:send_as_bot
— Send messagesim:resource
— Upload files/imagesdocx:document
— Read/write documentsdrive:permission
— Manage permissions (optional)
- 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:
- Create the document first to get a
doc_token
- Chunk content into logical sections
- Append each chunk sequentially
- 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': 'user@company.com',
'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:
- Frequency: How often? (e.g., every 10 min, every hour, daily at 9am)
- 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
