wecomcli-todo

WeCom Todo Management Skill

wecom-cli is the command-line program provided by WeCom. All operations are performed by executing wecom-cli commands.

Overview

wecomcli-todo provides complete management capabilities for WeCom todos, including:

1. Query todo list - Filter by creation time and reminder time, supports pagination, returns summary info
2. Get todo details - Batch retrieve full details (including content and assignees) by todo ID list
3. Create todo - Create a new todo with content, assignees, and reminder time
4. Update todo - Modify existing todo's content, assignees, status, or reminder time
5. Delete todo - Delete a specified todo
6. Change user todo status - Change the current user's status for a todo (reject/accept/complete)

Command Invocation

Execute the specified command:

wecom-cli todo <tool_name> '<json_params>'

Behavior Policy

After listing, always get details: get_todo_list only returns summary info like todo ID and status, not the actual content or assignees. A list without content is useless to users—they want to know "what to do", not a bunch of IDs. Therefore, every time you call get_todo_list and get results, you must immediately call get_todo_detail with the returned todo IDs to get full details (content, assignees, etc.) before presenting to the user. This is not optional but a necessary step to fulfill the user's request.

Convert person IDs to names (critical step): The follower_id and creator_id in get_todo_detail results are internal system IDs. Showing them directly to users is meaningless—users don't recognize IDs, only names. Therefore, before presenting todo details to the user, you must call the wecomcli-contact skill to get the address book and match all follower_id and creator_id to real names. Specifically:

wecom-cli contact get_userlist '{}'

If an ID is not found in the address book, display it as "Unknown user (ID: xxx)".

Must notify user when pagination is incomplete: The get_todo_list API is paginated; you don't have to fetch all data at once. But if the response has has_more as true, there are more todos not returned—when presenting the current results, you must explicitly tell the user "There are more todos not shown. Do you want to continue viewing?" The user may not know there is more data; if you don't tell them, they'll think what they see is everything, which could cause them to miss important todos.

Retry policy: When encountering "HTTP error" or "HTTP request failed", retry up to three times.

---

Command Details

1. Query Todo List (get_todo_list)

Query the current user's todo list, supports filtering by time and pagination. Returns summary info (without content and assignees).

Execute Command

wecom-cli todo get_todo_list '<json_params>'

Parameters

Parameter	Type	Required	Description
create_begin_time	string	❌	Creation start time, format: YYYY-MM-DD HH:mm:ss
create_end_time	string	❌	Creation end time, format: YYYY-MM-DD HH:mm:ss
remind_begin_time	string	❌	Reminder start time, format: YYYY-MM-DD HH:mm:ss
remind_end_time	string	❌	Reminder end time, format: YYYY-MM-DD HH:mm:ss
limit	number	❌	Max number of items, default 10, max 20
cursor	string	❌	Pagination cursor, omit on first request, pass next_cursor from previous response on subsequent requests

Response Format

{
    "errcode": 0,
    "errmsg": "ok",
    "index_list": [
        {
            "todo_id": "TODO_ID",
            "todo_status": 1,
            "user_status": 1,
            "creator_id": "CREATOR_ID",
            "remind_time": "2025-06-01 09:00:00",
            "create_time": "2025-01-15 10:30:00",
            "update_time": "2025-01-16 14:20:00"
        }
    ],
    "next_cursor": "NEXT_CURSOR",
    "has_more": false
}

Response Fields

Field	Type	Description
index_list	array	Todo list
index_list[].todo_id	string	Unique todo ID
index_list[].todo_status	number	Todo status: 0-completed, 1-in progress, 2-deleted
index_list[].user_status	number	User status: 0-rejected, 1-accepted, 2-completed
index_list[].creator_id	string	Creator ID
index_list[].remind_time	string	Reminder time
index_list[].create_time	string	Creation time
index_list[].update_time	string	Update time
next_cursor	string	Next page cursor
has_more	boolean	Whether there are more records

The list returns summary info (without content and assignees). After getting the list, you must call get_todo_detail to get full details before presenting to the user.

---

2. Get Todo Details (get_todo_detail)

Batch query full details by todo ID list, including content and assignee info.

Execute Command

wecom-cli todo get_todo_detail '<json_params>'

Parameters

Parameter	Type	Required	Description
todo_id_list	array	✅	List of todo IDs, max 20

Example

wecom-cli todo get_todo_detail '{"todo_id_list": ["TODO_ID_1", "TODO_ID_2"]}'

Response Format

{
    "errcode": 0,
    "errmsg": "ok",
    "data_list": [
        {
            "todo_id": "TODO_ID",
            "todo_status": 1,
            "content": "Complete Q2 planning document",
            "follower_list": {
                "followers": [
                    {
                        "follower_id": "FOLLOWER_ID",
                        "follower_status": 1,
                        "update_time": "2025-01-16 14:20:00"
                    }
                ]
            },
            "creator_id": "CREATOR_ID",
            "user_status": 1,
            "remind_time": "2025-06-01 09:00:00",
            "create_time": "2025-01-15 10:30:00",
            "update_time": "2025-01-16 14:20:00"
        }
    ]
}

Response Fields

Field	Type	Description
data_list	array	Todo details list, max 20 items
data_list[].todo_id	string	Todo ID
data_list[].todo_status	number	Todo status: 0-completed, 1-in progress, 2-deleted
data_list[].content	string	Todo content
data_list[].follower_list.followers	array	Assignee list
data_list[].follower_list.followers[].follower_id	string	Assignee ID (userid) — must convert to name via wecomcli-contact before display
data_list[].follower_list.followers[].follower_status	number	Assignee status: 0-rejected, 1-accepted, 2-completed
data_list[].follower_list.followers[].update_time	string	Assignee status update time
data_list[].creator_id	string	Creator ID — must convert to name via wecomcli-contact before display
data_list[].user_status	number	Current user status
data_list[].remind_time	string	Reminder time
data_list[].create_time	string	Creation time
data_list[].update_time	string	Update time

---

3. Create Todo (create_todo)

Create a new todo with content, assignees, and reminder time.

Execute Command

wecom-cli todo create_todo '<json_params>'

Parameters

Parameter	Type	Required	Description
content	string	✅	Todo content
follower_list	object	❌	Assignee list, format see note 6
remind_time	string	❌	Reminder time, format: YYYY-MM-DD HH:mm:ss

Example

wecom-cli todo create_todo '{"content": "<todo content>", "remind_time": "2025-06-01 09:00:00"}'

Response Format

{
    "errcode": 0,
    "errmsg": "ok",
    "todo_id": "TODO_ID"
}

Response Fields

Field	Type	Description
todo_id	string	Newly created todo unique ID

---

4. Update Todo (update_todo)

Modify existing todo's content, assignees, status, or reminder time.

Execute Command

wecom-cli todo update_todo '<json_params>'

Parameters

Parameter	Type	Required	Description
todo_id	string	✅	Todo ID
content	string	❌	New todo content
follower_list	object	❌	New assignee list (full replacement, not append), format see note 6. To add assignees, first query existing ones, merge, then submit
todo_status	number	❌	New todo status: 0-completed, 1-in progress, 2-deleted. For deletion, use delete_todo
remind_time	string	❌	New reminder time

Example

wecom-cli todo update_todo '{"todo_id": "TODO_ID", "content": "<todo content>", "remind_time": "2025-07-01 09:00:00"}'

Response Format

{
    "errcode": 0,
    "errmsg": "ok"
}

---

5. Delete Todo (delete_todo)

Delete a specified todo.

Execute Command

wecom-cli todo delete_todo '<json_params>'

Parameters

Parameter	Type	Required	Description
todo_id	string	✅	Todo ID

Example

wecom-cli todo delete_todo '{"todo_id": "TODO_ID"}'

Response Format

{
    "errcode": 0,
    "errmsg": "ok"
}

Deletion is irreversible; confirm with the user before executing.

---

6. Change User Todo Status (change_todo_user_status)

Change the current user's status for a todo (reject/accept/complete).

Execute Command

wecom-cli todo change_todo_user_status '<json_params>'

Parameters

Parameter	Type	Required	Description
todo_id	string	✅	Todo ID
user_status	number	✅	User status: 0-rejected, 1-accepted, 2-completed

Example

wecom-cli todo change_todo_user_status '{"todo_id": "TODO_ID", "user_status": 2}'

Response Format

{
    "errcode": 0,
    "errmsg": "ok"
}

Response Fields

Field	Type	Description
errcode	number	Return code, 0 means success
errmsg	string	Error message, "ok" on success

---

Typical Workflows

Complete workflow steps, command examples, and display formats are detailed in examples/workflows.md

Workflow	Use Case	Key Points
Workflow 1: View todo list	"Show my recent todos"	Standard three steps: get_todo_list → get_todo_detail → contact name conversion; check has_more pagination
Workflow 2: Query by time range	"What todos were created this month?"	Pass create_begin_time / create_end_time filter, then same as workflow 1
Workflow 3: Create and assign todo	"Create a todo for Zhang San to complete the requirements doc"	First get userid via wecomcli-contact, then create_todo with follower_list
Workflow 4: Mark todo complete	"Mark this todo as done"	Distinguish scenario A (set todo_status=0) and scenario B (set user_status=2)
Workflow 5: Update todo	"Change reminder time to next Friday"	First query list+details to locate target, then update_todo
Workflow 6: Delete todo	"Delete that todo"	Must confirm with user before deletion, irreversible
Workflow 7: Paginated fetch	When todo count exceeds single page limit	Loop fetch via cursor, must notify user if not all fetched

---

Notes

1. todo_id source rule

   • todo_id must come from get_todo_list results; do not guess or construct it yourself
   • Users usually provide todo content description rather than ID; first query list via get_todo_list then match
   • If multiple similar todos match, show a candidate list for user confirmation

2. follower_id source rule

   • follower_id is the userid, must be obtained via wecomcli-contact skill's get_userlist API
   • Do not guess userid based on user name
   • If multiple people with the same name are found, show a candidate list for user selection

3. Person IDs must be converted to names

   • follower_id and creator_id in results are internal identifiers; users cannot recognize them
   • Before displaying todo details, get the address book via wecom-cli contact get_userlist '{}'
   • Match follower_id / creator_id with userid from the address book, display name instead
   • If an ID is not found in the address book, display as "Unknown user (ID: xxx)"

4. Time format

   • All time parameters use YYYY-MM-DD HH:mm:ss format
   • When users say "tomorrow", "next Monday", etc., calculate the specific date based on the current date

5. Status value meanings

   • Todo status (todo_status): 0-completed, 1-in progress, 2-deleted
   • User status (user_status): 0-rejected, 1-accepted, 2-completed
   • Assignee status (follower_status): 0-rejected, 1-accepted, 2-completed

6. follower_list format (when used as input parameter)

   "follower_list": {
       "followers": [
           {
               "follower_id": "FOLLOWER_ID",
               "follower_status": 1
           }
       ]
   }
   

   follower_id is the userid, must be obtained via wecomcli-contact; do not guess or construct it.

7. Destructive operation confirmation

   • Must confirm with user before deleting a todo (delete_todo)
   • Recommend confirming with user before changing status to "rejected" (user_status=0)

8. Must get details

   • get_todo_list returns summary info (without content and assignees); after getting the list, immediately call get_todo_detail to get full content before presenting to the user; do not just show the list summary

9. Must notify when pagination incomplete

   • If has_more is true, when presenting results to the user, explicitly state "There are more todos not shown" and ask if they want to continue viewing

10. Single detail request limit

    • todo_id_list can contain at most 20 IDs; batch requests if more

11. Error handling

    • If errcode is not 0, the API call failed; inform the user of the error message in errmsg

12. Address book query

    • When involving assignees, first get the full address book members via wecomcli-contact skill's get_userlist API, then locally filter by name/alias to match the corresponding userid. This API has no parameters and returns the list of members visible to the current user (including userid, name, alias)