wecomcli-lookup-contact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

通讯录成员查询技能

Address Book Member Query Skill

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

获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。

wecom-cli
is a command-line program provided by WeCom (WeChat Work). All operations are completed by executing the
wecom-cli
command.

Obtain address book members within the visible range of the current user, and perform local filtering and matching by name/alias.

操作

Operations

1. 获取全量通讯录成员

1. Get full list of address book members

获取当前用户可见范围内的所有企业成员信息：

调用示例：

bash

wecom-cli contact get_userlist '{}'

返回格式：

json

{
    "errcode": 0,
    "errmsg": "ok",
    "userlist": [
        {
            "userid": "zhangsan",
            "name": "张三",
            "alias": "Sam"
        },
        {
            "userid": "lisi",
            "name": "李四",
            "alias": ""
        }
    ]
}

返回字段说明：

字段	类型	说明
`errcode`	integer	返回码， `0` 表示成功
`errmsg`	string	错误信息
`userlist`	array	用户列表
`userlist[].userid`	string	用户唯一 ID
`userlist[].name`	string	用户姓名
`userlist[].alias`	string	用户别名，可能为空

Obtain information of all enterprise members within the visible range of the current user:

Call example:

bash

wecom-cli contact get_userlist '{}'

Return format:

json

{
    "errcode": 0,
    "errmsg": "ok",
    "userlist": [
        {
            "userid": "zhangsan",
            "name": "张三",
            "alias": "Sam"
        },
        {
            "userid": "lisi",
            "name": "李四",
            "alias": ""
        }
    ]
}

Return field description:

Field	Type	Description
`errcode`	integer	Return code, `0` means success
`errmsg`	string	Error message
`userlist`	array	User list
`userlist[].userid`	string	Unique user ID
`userlist[].name`	string	User name
`userlist[].alias`	string	User alias, may be empty

2. 按姓名/别名搜索人员

2. Search personnel by name/alias

get_userlist

返回全量成员后，在本地对结果进行筛选匹配：

精确匹配：
```
name
```
或
```
alias
```
与关键词完全一致，直接使用
模糊匹配：
```
name
```
或
```
alias
```
包含关键词，返回所有匹配结果
无结果：告知用户未找到对应人员

搜索示例：

用户问："帮我找一下张三是谁？"

调用
```
get_userlist
```
获取全量成员
在
```
userlist
```
中筛选
```
name
```
或
```
alias
```
包含"张三"的成员
返回匹配结果

After

get_userlist

returns the full list of members, filter and match the results locally:

Exact match: If
```
name
```
or
```
alias
```
is exactly the same as the keyword, use it directly
Fuzzy match: If
```
name
```
or
```
alias
```
contains the keyword, return all matching results
No results: Inform the user that no corresponding personnel is found

Search example:

User query: "Can you help me find who Zhang San is?"

Call
```
get_userlist
```
to get the full list of members
Filter members in
```
userlist
```
whose
```
name
```
or
```
alias
```
contains "张三"
Return matching results

注意事项

Notes

```
get_userlist
```
返回的是当前用户可见范围内的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含
```
userid
```
、
```
name
```
（姓名）和
```
alias
```
（别名）
⚠️ 超过 10 人时接口将报错：若
```
userlist
```
返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
当前通讯录可见成员数量超过了本技能支持的上限（10 人）。本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。建议缩小可见范围后重试，或通过其他方式查询目标人员。
```
userid
```
是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段
```
alias
```
字段可能为空字符串，搜索时需做空值判断
若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定
若
```
errcode
```
不为
```
0
```
，说明接口调用失败，需告知用户错误信息（
```
errmsg
```
）

The members returned by
```
get_userlist
```
are those within the visible range of the current user, which need to be filtered by visibility rules, and are not necessarily all personnel of the entire company; the returned fields only include
```
userid
```
,
```
name
```
and
```
alias
```
⚠️ The interface will report an error when there are more than 10 people: If the number of members returned by
```
userlist
```
exceeds 10, it is regarded as an exception, and the processing should be stopped immediately and the user should be informed:
The number of visible members in the current address book exceeds the upper limit supported by this skill (10 people). This skill is only applicable to scenarios with a small visible range, and cannot be used in a large-scale address book. It is recommended to reduce the visible range and try again, or query the target personnel through other methods.
```
userid
```
is the unique identifier of the user, which is used when the user ID needs to be passed to other interfaces
The
```
alias
```
field may be an empty string, so null value judgment is required during search
If there are multiple personnel with the same name in the search results, all candidates should be displayed to the user for selection, and no self-determination is allowed
If
```
errcode
```
is not
```
0
```
, it means the interface call failed, and the user needs to be informed of the error message (
```
errmsg
```
)

典型工作流

Typical Workflows

工作流 1：查询人员信息

Workflow 1: Query personnel information

用户问："帮我查一下 Sam 是谁？"

bash

wecom-cli contact get_userlist '{}'

获取全量成员列表

在结果中筛选
```
alias
```
为
```
Sam
```
或
```
name
```
包含
```
Sam
```
的成员
若找到唯一匹配，直接展示结果：

📇 找到成员：
- 姓名：张三
- 别名：Sam
- 用户ID：zhangsan

若找到多个匹配，展示候选列表请用户确认：

🔍 找到多个匹配成员，请确认您要查询的是哪位：

1. 张三（别名：Sam，ID：zhangsan）
2. 张三丰（别名：Sam2，ID：zhangsan2）

请问您要查询的是哪一位？

User query: "Can you help me find who Sam is?"

bash

wecom-cli contact get_userlist '{}'

Obtain the full list of members

Filter members whose
```
alias
```
is
```
Sam
```
or
```
name
```
contains
```
Sam
```
in the results
If a unique match is found, display the result directly:

📇 Found member:
- Name: 张三
- Alias: Sam
- User ID: zhangsan

If multiple matches are found, display the candidate list and ask the user to confirm:

🔍 Multiple matching members found, please confirm which one you want to query:

1. 张三（Alias: Sam, ID: zhangsan）
2. 张三丰（Alias: Sam2, ID: zhangsan2）

Which one do you want to query?

工作流 2：为其他功能提供 userid 转换

Workflow 2: Provide userid conversion for other functions

用户问："帮我发消息给张三"

bash

wecom-cli contact get_userlist '{}'

获取全量成员

筛选
```
name
```
为"张三"的成员，确认
```
userid
```
将
```
userid
```
传递给消息发送接口

User query: "Help me send a message to Zhang San"

bash

wecom-cli contact get_userlist '{}'

Obtain the full list of members

Filter members whose
```
name
```
is "张三" and confirm the
```
userid
```
Pass the
```
userid
```
to the message sending interface

工作流 3：批量查询多个人员

Workflow 3: Batch query multiple personnel

用户问："帮我查一下张三和李四分别是谁？"

bash

wecom-cli contact get_userlist '{}'

获取全量成员列表

分别筛选"张三"和"李四"的匹配结果
汇总后一并展示

注意：只需调用一次
get_userlist
，在本地对结果进行多次筛选，避免重复调用接口。

User query: "Help me check who Zhang San and Li Si are respectively?"

bash

wecom-cli contact get_userlist '{}'

Obtain the full list of members

Filter the matching results of "张三" and "李四" respectively
Summarize and display together

Note: You only need to call
get_userlist
once, and filter the results multiple times locally to avoid repeated calls to the interface.

快速参考

Quick Reference

接口说明

Interface Description

接口	用途	输入	返回
`get_userlist`	获取可见范围内全量通讯录成员	无	用户列表（userid、name、alias）

Interface	Purpose	Input	Return
`get_userlist`	Get all address book members within the visible range	None	User list (userid, name, alias)

本地筛选策略

Local Filtering Strategy

场景	策略
精确匹配（name 或 alias 完全一致）	直接使用，无需用户确认
模糊匹配（name 或 alias 包含关键词），唯一结果	直接使用，向用户展示结果
模糊匹配，多个结果	展示候选列表，请用户选择
无匹配结果	告知用户未找到对应人员

Scenario	Strategy
Exact match (name or alias is completely consistent)	Use directly, no user confirmation required
Fuzzy match (name or alias contains keywords), unique result	Use directly, display the result to the user
Fuzzy match, multiple results	Display the candidate list, ask the user to choose
No matching result	Inform the user that no corresponding personnel is found