feishu-task

Feishu Task Management

🚨 Must-read before execution

• ✅ Time format: ISO 8601 / RFC 3339 (with time zone), for example 2026-02-28T17:00:00+08:00
• ✅ Identity authorization: The tool supports auth_type as user(default, user identity) or tenant(app identity).
• ✅ Task Agent (feishu_task_agent): Only supports app identity (tenant), does not support user identity
• ✅ current_user_id is strongly recommended: Obtain it 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"
• ✅ append_steps task_steps[].timestamp: second-level Unix timestamp (10 digits), do not use milliseconds (13 digits)

---

📋 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, auth_type
Query incomplete tasks	feishu_task_task	list	-	completed=false	page_size, auth_type, agent_task_status
Get task details	feishu_task_task	get	task_guid	-	auth_type
Complete task	feishu_task_task	patch	task_guid, completed_at	-	auth_type
Uncomplete task	feishu_task_task	patch	task_guid, completed_at="0"	-	auth_type
Change due time	feishu_task_task	patch	task_guid, due	-	auth_type
Add task members	feishu_task_task	add_members	task_guid, members[]	-	auth_type
Append task step records	feishu_task_task	append_steps	task_guid, idempotent_key, task_steps[]	task_steps[].timestamp uses seconds (10 digits)	-
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[]	-	-
Upload task attachments	feishu_task_attachment	upload	resource_id, file(base64)	name	resource_type
Register task Agent	feishu_task_agent	register	-	Only supports tenant (app identity)	-
Update task Agent Profile	feishu_task_agent	update_profile	profile_content	Only supports tenant (app identity)	-

---

🎯 Core constraints (knowledge not revealed by the Schema)

1. Authorization identity and visibility (auth_type)

The tool supports two call identities auth_type：

• user (default): User identity (user_access_token). Used for scenarios that require strictly acting on behalf of the user or querying the user's private tasks.
  • ⚠️ When using the user identity, you can only view and edittasks in which you are a member。
  • ⚠️ If you did not add yourself as a member when creating it, you cannot edit the task afterward。
• tenant: App identity (tenant_access_token). When the user identity does not meet the requirements, use the app identity. If the created task does not add the user as a member, the user may not be able to see it.

Automatic protection mechanism：

• Pass in the current_user_id parameter (obtained from SenderId)
• If members does not contain current_user_id, the tool willautomatically add as a follower
• Ensure the creator can always edit and view the task

2. Roles and types of task members

• Role (role)：
  • assignee: Responsible for completing the task, can edit the task
  • follower: Follows task progress, receives notifications
• Type (type)：
  • user (default, user): A regular Feishu user
  • app (application/bot): If adding the bot itself or another application to the task, you must specify type: "app"

Example of adding members：

{
  "members": [
    {"id": "ou_xxx", "role": "assignee", "type": "user"},  // 负责人（用户）
    {"id": "cli_yyy", "role": "follower", "type": "app"}   // 关注人（机器人/应用）
  ]
}

Description：id By default, open_id。

3. Task list role conflict

Symptom: When creating a list (tasklist.create), memberswas passed, but the returned tasklist.members is empty or missing members

Cause: The creator automatically becomes the list owner(owner). If members includes the creator, that user ultimately becomes the owner and is removed from members (a user can have only one role)

Recommendation: Do not include the creator in members ; only add other collaborating members

4. Three usages of completed_at

1) Complete the task (set 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 the upper layer has strictly generated it):

{
  "completed_at": "1740545400000"  // 毫秒时间戳字符串
}

5. Roles of list members

Member type	Role	Description
user	owner	Owner, can transfer ownership
user	editor	Can edit, can modify the list and tasks
user	viewer	Can view, read-only permission
chat	editor/viewer	The entire group gets permission

Description: When creating a list, the creator automatically becomes the owner, and there is no need to specify it in members.

---

📌 Usage scenario examples

Scenario 1: Create a task and assign an assignee

{
  "action": "create",
  "summary": "准备周会材料",
  "description": "整理本周工作进展和下周计划",
  "current_user_id": "ou_发送者的open_id",
  "auth_type": "tenant",
  "due": {
    "timestamp": "2026-02-28 17:00:00",
    "is_all_day": false
  },
  "members": [
    {"id": "ou_协作者的open_id", "role": "assignee", "type": "user"}
  ]
}

Description：

• summary is a required field
• current_user_id It is strongly recommended to pass it in (obtained from SenderId); the tool will automatically add it as a follower
• members It can include only other collaborators; the current user will be added automatically
• Time uses the ISO 8601 format with a time zone

Scenario 2: Query incomplete tasks I am responsible for

{
  "action": "list",
  "completed": false,
  "page_size": 20,
  "auth_type": "user"
}

Scenario 3: Add a bot or member to an existing task

{
  "action": "add_members",
  "task_guid": "任务的guid",
  "auth_type": "tenant",
  "members": [
    {"id": "cli_机器人的app_id", "role": "follower", "type": "app"}
  ]
}

Scenario 4: Complete a task

{
  "action": "patch",
  "task_guid": "任务的guid",
  "completed_at": "2026-02-26 15:30:00"
}

Scenario 5: Uncomplete a task (restore to incomplete status)

{
  "action": "patch",
  "task_guid": "任务的guid",
  "completed_at": "0"
}

Scenario 6: Create a list and add collaborators

{
  "action": "create",
  "name": "产品迭代 v2.0",
  "members": [
    {"id": "ou_xxx", "role": "editor"},
    {"id": "ou_yyy", "role": "viewer"}
  ]
}

Scenario 7: View incomplete tasks in a list

{
  "action": "tasks",
  "tasklist_guid": "清单的guid",
  "completed": false
}

Scenario 8: All-day task

{
  "action": "create",
  "summary": "年度总结",
  "due": {
    "timestamp": "2026-03-01 00:00:00",
    "is_all_day": true
  }
}

Scenario 9: Register a task Agent (application identity only)

{
  "action": "register",
  "auth_type": "tenant"
}

Scenario 10: Update the task Agent Profile (application identity only)

{
  "action": "update_profile",
  "auth_type": "tenant",
  "profile_content": "some profile content"
}

---

🔍 Common errors and troubleshooting

Error symptom	Root cause	Solution
Unable to edit the task after creation	Did not add yourself to members when creating	When creating, add at least the current user (SenderId) as an assignee or follower
patch fails with a message that task_guid is missing	task_guid parameter not passed	patch/get/add_members must pass task_guid
tasks failure prompt: tasklist_guid missing	tasklist_guid parameter not passed	tasklist.tasks action must pass tasklist_guid
Uncomplete failed	completed_at format error	Use "0" string, not the number 0
Incorrect time	Used a Unix timestamp	Use ISO 8601 format instead (with time zone):2024-01-01T00:00:00+08:00
Failed to add bot	Member type not specified as app	Specify the bot's type as "app"

---

📚 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 assigned to yourself

B. How to Get the GUID

• task_guid: after creating a task, get it from the return value's task.guid get it, or query via list query
• tasklist_guid: after creating a tasklist, get it from the return value's tasklist.guid get it, or query via list query

C. How to Add a Task to a Tasklist

Specify the tasklists parameter when creating a task:

{
  "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 tasklists you have permission for (tasklists you are a member of)
• Adding a task to a tasklist requires edit permission for both the task and the tasklist