🚨 Must-read before execution
- ✅ Time format: ISO 8601 / RFC 3339 (with time zone), for example
2026-02-28T17:00:00+08:00 - ✅ current_user_id strongly recommended: obtained from the SenderId in the message context (ou_...); the tool will automatically add it as a follower (if not already in members), ensuring the creator can edit the task
- ✅ patch/get required:task_guid
- ✅ tasklist.tasks required:tasklist_guid
- ✅ Complete task:completed_at = "2026-02-26 15:00:00"
- ✅ Uncomplete (restore to incomplete):completed_at = "0"
📋 Quick index: intent → tool → required parameters
| User intent | Tool | action | Required parameters | Strongly recommended | Common optional |
|---|---|---|---|---|---|
| Create to-do | feishu_task_task | create | summary | current_user_id(SenderId) | members, due, description |
| Query incomplete tasks | feishu_task_task | list | - | completed=false | page_size |
| Get task details | feishu_task_task | get | task_guid | - | - |
| Complete task | feishu_task_task | patch | task_guid, completed_at | - | - |
| Uncomplete task | feishu_task_task | patch | task_guid, completed_at="0" | - | - |
| Change due time | feishu_task_task | patch | task_guid, due | - | - |
| Create tasklist | feishu_task_tasklist | create | name | - | members |
| View tasklist tasks | feishu_task_tasklist | tasks | tasklist_guid | - | completed |
| Add tasklist members | feishu_task_tasklist | add_members | tasklist_guid, members[] | - | - |
🎯 Core constraints (knowledge not revealed by the Schema)
1. The current tool uses user identity (built-in protection)
The tool uses user_access_token(user identity)
This means:
- ✅ When creating a task, you can specify any members (including assigning only to others)
- ⚠️ You can only view and edittasks where you are a member
- ⚠️ If you do not add yourself as a member when creating, you cannot edit the task afterward
Automatic protection mechanism:
- Pass in the
current_user_idparameter (obtained from SenderId) - If
membersdoes not containcurrent_user_id, the tool willautomatically add as a follower - Ensure the creator can always edit the task
Recommended usage: Always pass current_user_idwhen creating a task; the tool will automatically handle member relationships.
2. Description of task member roles
- assignee: responsible for completing the task, can edit the task
- follower: follows task progress, receives notifications
Example of adding members:
{
"members": [
{"id": "ou_xxx", "role": "assignee"}, // 负责人
{"id": "ou_yyy", "role": "follower"} // 关注人
]
}
Description:id uses the user's open_id(obtained from the SenderId in the message context)
3. Tasklist role conflict
Symptom: when creating a tasklist (tasklist.create), memberswas passed, but the returned tasklist.members is empty or missing members
Cause: the creator automatically becomes the tasklist owner(owner); if members includes the creator, that user ultimately becomes owner and is removed from members (the same user can only have one role)
Suggestion: do not include the creator in members ; only add other collaborating members
4. Three usages of completed_at
1) Complete a task (set the completion time):
{
"action": "patch",
"task_guid": "xxx",
"completed_at": "2026-02-26 15:30:00" // 北京时间字符串
}
2) Uncomplete (restore to incomplete status):
{
"action": "patch",
"task_guid": "xxx",
"completed_at": "0" // 特殊值 "0" 表示反完成
}
3) Millisecond timestamp(not recommended unless strictly generated by the upper layer):
{
"completed_at": "1740545400000" // 毫秒时间戳字符串
}
5. Roles of tasklist members
| Member type | Role | Description |
|---|---|---|
| user | owner | Owner, can transfer ownership |
| user | editor | Can edit, can modify the tasklist and tasks |
| user | viewer | Can view, read-only permission |
| chat | editor/viewer | The entire group gets permission |
Description: When creating a tasklist, the creator automatically becomes the owner; there is no need to specify this in members.
📌 Usage scenario examples
Scenario 1: Create a task and assign a person responsible
{
"action": "create",
"summary": "准备周会材料",
"description": "整理本周工作进展和下周计划",
"current_user_id": "ou_发送者的open_id",
"due": {
"timestamp": "2026-02-28 17:00:00",
"is_all_day": false
},
"members": [
{"id": "ou_协作者的open_id", "role": "assignee"}
]
}
Description:
summaryis a required fieldcurrent_user_idis strongly recommended to be passed in (obtained from SenderId); the tool will automatically add it as a followermemberscan contain only other collaborators; the current user will be added automatically- Time uses the Beijing time string format
Scenario 2: Query my incomplete tasks
{
"action": "list",
"completed": false,
"page_size": 20
}
Scenario 3: Complete a task
{
"action": "patch",
"task_guid": "任务的guid",
"completed_at": "2026-02-26 15:30:00"
}
Scenario 4: Uncomplete a task (restore to incomplete status)
{
"action": "patch",
"task_guid": "任务的guid",
"completed_at": "0"
}
Scenario 5: Create a tasklist and add collaborators
{
"action": "create",
"name": "产品迭代 v2.0",
"members": [
{"id": "ou_xxx", "role": "editor"},
{"id": "ou_yyy", "role": "viewer"}
]
}
Scenario 6: View incomplete tasks in a tasklist
{
"action": "tasks",
"tasklist_guid": "清单的guid",
"completed": false
}
Scenario 7: All-day task
{
"action": "create",
"summary": "年度总结",
"due": {
"timestamp": "2026-03-01 00:00:00",
"is_all_day": true
}
}
🔍 Common errors and troubleshooting
| Error symptom | Root cause | Solution |
|---|---|---|
| Cannot edit the task after creation | Did not add yourself to members at creation time | At creation time, add at least the current user (SenderId) as assignee or follower |
| patch fails with a task_guid missing message | Did not pass the task_guid parameter | patch/get must pass task_guid |
| tasks fails with a tasklist_guid missing message | Did not pass the tasklist_guid parameter | tasklist.tasks action must pass tasklist_guid |
| Uncomplete fails | Incorrect completed_at format | Use "0" string, not the number 0 |
| Incorrect time | Used a Unix timestamp | Switch to ISO 8601 format (with time zone):2024-01-01T00:00:00+08:00 |
📚 Appendix: Background knowledge
A. Resource relationships
任务清单(Tasklist)
└─ 自定义分组(Section,可选)
└─ 任务(Task)
├─ 成员:负责人(assignee)、关注人(follower)
├─ 子任务(Subtask)
├─ 截止时间(due)、开始时间(start)
└─ 附件、评论
Core concepts:
- Task: an independent to-do item, with a unique
task_guid - Tasklist: a container that organizes multiple tasks, with a unique
tasklist_guid - assignee: can edit the task and mark it complete
- follower: receives task update notifications
- MyTasks: the collection of all tasks whose assignee is yourself
B. How to get the GUID
- task_guid: after creating a task, get it from the return value's
task.guidget it, or query vialistquery - tasklist_guid: After creating the list, get it from the return value's
tasklist.guid, or query it vialistto look up
C. How to add a task to a list
When creating a task, specify the tasklists parameter:
{
"action": "create",
"summary": "任务标题",
"tasklists": [
{
"tasklist_guid": "清单的guid",
"section_guid": "分组的guid(可选)"
}
]
}
D. How to create recurring tasks
Use the repeat_rule parameter with RRULE format:
{
"action": "create",
"summary": "每周例会",
"due": {"timestamp": "2026-03-03 14:00:00", "is_all_day": false},
"repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO"
}
Note: Only tasks with a due time set can have recurrence rules set.
E. Data permissions
- You can only operate on tasks you have permission for (tasks you are a member of)
- You can only operate on lists you have permission for (lists you are a member of)
- Adding a task to a list requires edit permission for both the task and the list