wecomcli-get-todo-list

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

企业微信待办列表查询技能

WeCom To-Do List Query Skill

wecom-cli
是企业微信提供的命令行程序，所有操作通过执行
wecom-cli
命令完成。

通过

wecom-cli

查询企业微信待办列表，支持按时间过滤和分页。

wecom-cli
is a command line program provided by WeCom, and all operations are completed by executing
wecom-cli
commands.

Query WeCom to-do list via

wecom-cli

, supporting time filtering and pagination.

行为策略

Behavior Strategy

查完列表必须查详情: 本接口只返回待办 ID 和状态等概要信息，不包含待办的实际内容和分派人。对用户来说，没有内容的待办列表毫无用处——他们想知道的是"要做什么"，而不是一串 ID。因此，每次调用 get_todo_list 拿到结果后，都要紧接着用返回的 todo_id 列表调用

wecomcli-get-todo-detail

获取完整详情（内容、分派人等），然后再向用户展示。这不是可选步骤，而是完成用户请求的必要环节。

分页未拉完时必须提醒用户: 接口是分页的，不要求一次性拉完所有数据。但如果响应中

has_more

为

true

，说明后面还有待办没有返回——这时你在展示当前结果的同时，必须明确告诉用户"还有更多待办未显示，是否需要继续查看？"。用户可能不知道后面还有数据，如果你不说，他们会以为看到的就是全部，这会导致遗漏重要待办。这是一个容易被忽略但后果严重的点，请务必执行。

重试策略: 遭遇"返回 HTTP 错误"或"HTTP 请求失败"时，主动重试，最多重试三次。

Must query details after getting the list: This interface only returns summary information such as to-do ID and status, and does not include the actual content of the to-do and the assignee. For users, a to-do list without content is completely useless - what they want to know is "what to do", not a string of IDs. Therefore, after each call to get_todo_list to get the result, you must immediately use the returned todo_id list to call

wecomcli-get-todo-detail

to get complete details (content, assignee, etc.) before displaying them to the user. This is not an optional step, but a necessary link to complete the user's request.

Must remind users when pagination is not fully pulled: The interface is paginated, and it is not required to pull all data at one time. But if

has_more

in the response is

true

, it means that there are still to-dos not returned later - when you display the current results, you must clearly tell the user "There are more to-dos not displayed, do you need to continue viewing?". Users may not know that there is more data later, if you don't mention it, they will think what they see is all, which will lead to missing important to-dos. This is a point that is easy to ignore but has serious consequences, please be sure to implement it.

Retry strategy: When encountering "return HTTP error" or "HTTP request failure", take the initiative to retry, up to three times.

调用方式

Calling Method

bash

wecom-cli todo get_todo_list '<json格式的入参>'

bash

wecom-cli todo get_todo_list '<json格式的入参>'

参数说明

Parameter Description

参数	类型	必填	说明
`create_begin_time`	string	❌	创建开始时间，格式： `YYYY-MM-DD HH:mm:ss`
`create_end_time`	string	❌	创建结束时间，格式： `YYYY-MM-DD HH:mm:ss`
`remind_begin_time`	string	❌	提醒开始时间，格式： `YYYY-MM-DD HH:mm:ss`
`remind_end_time`	string	❌	提醒结束时间，格式： `YYYY-MM-DD HH:mm:ss`
`limit`	number	❌	最大返回数量，默认 10，最大 20
`cursor`	string	❌	分页游标，首次请求不传，后续传入上次响应的 `next_cursor`

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	❌	Maximum number of returned items, default 10, maximum 20
`cursor`	string	❌	Pagination cursor, not passed for the first request, pass the `next_cursor` of the last response for subsequent requests

返回格式

Return Format

json

{
    "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
}

json

{
    "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
}

返回字段说明

Return Field Description

字段	类型	说明
`index_list`	array	待办列表
`index_list[].todo_id`	string	待办唯一 ID
`index_list[].todo_status`	number	待办状态： `0` -已完成， `1` -进行中， `2` -已删除
`index_list[].user_status`	number	用户状态： `0` -拒绝， `1` -接受， `2` -已完成
`index_list[].creator_id`	string	创建人 ID
`index_list[].remind_time`	string	提醒时间
`index_list[].create_time`	string	创建时间
`index_list[].update_time`	string	更新时间
`next_cursor`	string	下一页游标
`has_more`	boolean	是否还有更多记录

列表返回的是待办概要信息（不含内容和分派人）。拿到列表后，必须调用
wecomcli-get-todo-detail
获取完整详情再展示给用户。

Field	Type	Description
`index_list`	array	To-do list
`index_list[].todo_id`	string	Unique to-do ID
`index_list[].todo_status`	number	To-do 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 to-do summary information (excluding content and assignees). After getting the list, you must call
wecomcli-get-todo-detail
to get complete details before displaying them to the user.

典型工作流

Typical Workflow

查看待办列表（标准两步流程）

View To-do List (Standard Two-step Process)

用户问："看看我最近的待办" / "我有哪些待办事项？" / "我还有多少事要做？"

第一步：获取待办列表（只有 ID 和状态，没有内容）。

bash

wecom-cli todo get_todo_list '{}'

第二步（禁止跳过！）：用返回的 todo_id 列表调用 wecomcli-get-todo-detail 获取完整详情。

bash

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

两步缺一不可——只有拿到详情后，才能向用户展示有意义的待办内容。

第三步（条件执行）：检查第一步返回的
```
has_more
```
字段。如果为
```
true
```
，在展示结果时必须提醒用户："以上是部分待办，还有更多待办未显示，需要我继续查看吗？"——不提醒的话，用户会以为这就是全部。

User asks: "Check my recent to-dos" / "What to-do items do I have?" / "How many things do I still have to do?"

Step 1: Get the to-do list (only ID and status, no content).

bash

wecom-cli todo get_todo_list '{}'

Step 2 (Prohibited to skip!): Call wecomcli-get-todo-detail with the returned todo_id list to get complete details.

bash

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

Both steps are indispensable - only after getting the details can you display meaningful to-do content to the user.

Step 3 (Conditional execution): Check the
```
has_more
```
field returned in the first step. If it is
```
true
```
, you must remind the user when displaying the results: "The above are part of the to-dos, there are more to-dos not displayed, do you need me to continue checking?" - If you don't remind, users will think this is all.

按时间范围查询

Query by Time Range

用户问："这个月创建的待办有哪些？"

bash

wecom-cli todo get_todo_list '{"create_begin_time": "2025-03-01 00:00:00", "create_end_time": "2025-03-31 23:59:59"}'

User asks: "What are the to-dos created this month?"

bash

wecom-cli todo get_todo_list '{"create_begin_time": "2025-03-01 00:00:00", "create_end_time": "2025-03-31 23:59:59"}'

分页获取大量待办

Pagination to Get a Large Number of To-dos

当待办数量超过单页上限时，通过

cursor

循环分页拉取：

首次请求（不传 cursor）：

bash

wecom-cli todo get_todo_list '{"limit": 20}'

，如果没有拉取完，还有更多的待办，会返回 has_more=true, next_cursor="CURSOR_1"

第二次请求（传入上次的 next_cursor）：

bash

wecom-cli todo get_todo_list '{"limit": 20, "cursor": "CURSOR_1"}'

，返回 has_more=false，拉取完毕

分页规则：

首次请求不传
```
cursor
```
```
has_more
```
为
```
true
```
时，将
```
next_cursor
```
作为下次请求的
```
cursor
```
传入
```
has_more
```
为
```
false
```
时停止请求
分页过程中时间过滤参数保持不变
如果选择不继续翻页（比如当前页数据已经够用），必须告诉用户还有更多待办未显示，问用户是否需要继续查看

When the number of to-dos exceeds the single-page limit, pull pages cyclically through

cursor

First request (no cursor passed):

bash

wecom-cli todo get_todo_list '{"limit": 20}'

If the pulling is not completed and there are more to-dos, it will return has_more=true, next_cursor="CURSOR_1"

Second request (pass the next_cursor from the last time):

bash

wecom-cli todo get_todo_list '{"limit": 20, "cursor": "CURSOR_1"}'

Return has_more=false, pulling completed

Pagination rules:

Do not pass
```
cursor
```
for the first request
When
```
has_more
```
is
```
true
```
, pass
```
next_cursor
```
as the
```
cursor
```
of the next request
Stop the request when
```
has_more
```
is
```
false
```
The time filter parameters remain unchanged during pagination
If you choose not to continue turning pages (for example, the current page data is enough), you must tell the user that there are more to-dos not displayed, and ask the user if they need to continue viewing

注意事项

Notes

时间格式：所有时间参数使用
```
YYYY-MM-DD HH:mm:ss
```
格式，用户说"明天"、"下周一"等相对时间时，根据当前日期推算具体日期
状态值含义
- 待办状态（
```
todo_status
```
  ）：
```
0
```
  -已完成，
```
1
```
  -进行中，
```
2
```
  -已删除
- 用户状态（
```
user_status
```
  ）：
```
0
```
  -拒绝，
```
1
```
  -接受，
```
2
```
  -已完成
错误处理：若
```
errcode
```
不为
```
0
```
，告知用户
```
errmsg
```
中的错误信息
必须查详情：本接口返回的是概要信息（不含内容和分派人），拿到列表后必须紧接着调用
```
wecomcli-get-todo-detail
```
获取完整内容再展示给用户，不要只展示列表概要
分页未拉完必须提醒：如果返回的
```
has_more
```
为
```
true
```
，在向用户展示结果时必须明确说明"还有更多待办未显示"并询问用户是否需要继续查看。用户不知道后面还有数据，不提醒会导致遗漏

Time format: All time parameters use the
```
YYYY-MM-DD HH:mm:ss
```
format. When users say relative times such as "tomorrow", "next Monday", calculate the specific date according to the current date
Status value meaning
- To-do status (
```
todo_status
```
  ):
```
0
```
  -Completed,
```
1
```
  -In progress,
```
2
```
  -Deleted
- User status (
```
user_status
```
  ):
```
0
```
  -Rejected,
```
1
```
  -Accepted,
```
2
```
  -Completed
Error handling: If
```
errcode
```
is not
```
0
```
, inform the user of the error information in
```
errmsg
```
Must query details: This interface returns summary information (excluding content and assignees). After getting the list, you must immediately call
```
wecomcli-get-todo-detail
```
to get the complete content before displaying it to the user, do not only display the list summary
Must remind when pagination is not fully pulled: If the returned
```
has_more
```
is
```
true
```
, when displaying the results to the user, you must clearly state "There are more to-dos not displayed" and ask the user if they need to continue viewing. Users do not know that there is more data later, and not reminding will lead to omissions