通讯录成员查询技能,获取当前用户可见范围内的通讯录成员,支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员,非全量成员。
wecom-cli是企业微信提供的命令行程序,所有操作通过执行wecom-cli命令完成。
获取当前用户可见范围内的通讯录成员,并在本地按姓名/别名进行筛选匹配。
获取当前用户可见范围内的所有企业成员信息:
调用示例:
wecom-cli contact get_userlist '{}'
返回格式:
{
"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 | 用户别名,可能为空 |
get_userlist 返回全量成员后,在本地对结果进行筛选匹配:
name 或 alias 与关键词完全一致,直接使用name 或 alias 包含关键词,返回所有匹配结果搜索示例:
用户问:"帮我找一下张三是谁?"
get_userlist 获取全量成员userlist 中筛选 name 或 alias 包含"张三"的成员get_userlist 返回的是当前用户可见范围内的成员,需经过可见性规则过滤,不一定是全公司所有人员;返回字段仅包含 userid、name(姓名)和 alias(别名)
⚠️ 超过 10 人时接口将报错:若 userlist 返回成员数量超过 10 人,视为异常,应立即停止处理并向用户说明:
当前通讯录可见成员数量超过了本技能支持的上限(10 人)。 本技能仅适用于可见范围较小的场景,无法在大范围通讯录中使用。 建议缩小可见范围后重试,或通过其他方式查询目标人员。
userid 是用户的唯一标识,在需要传递用户 ID 给其他接口时使用此字段
alias 字段可能为空字符串,搜索时需做空值判断
若搜索结果有多个同名人员,需将所有候选人展示给用户选择,不得自行决定
若 errcode 不为 0,说明接口调用失败,需告知用户错误信息(errmsg)
用户问:"帮我查一下 Sam 是谁?"
wecom-cli contact get_userlist '{}'
获取全量成员列表
alias 为 Sam 或 name 包含 Sam 的成员📇 找到成员:
- 姓名:张三
- 别名:Sam
- 用户ID:zhangsan
🔍 找到多个匹配成员,请确认您要查询的是哪位:
1. 张三(别名:Sam,ID:zhangsan)
2. 张三丰(别名:Sam2,ID:zhangsan2)
请问您要查询的是哪一位?
用户问:"帮我发消息给张三"
wecom-cli contact get_userlist '{}'
获取全量成员
name 为"张三"的成员,确认 useriduserid 传递给消息发送接口用户问:"帮我查一下张三和李四分别是谁?"
wecom-cli contact get_userlist '{}'
获取全量成员列表
注意:只需调用一次
get_userlist,在本地对结果进行多次筛选,避免重复调用接口。
| 接口 | 用途 | 输入 | 返回 |
|---|---|---|---|
get_userlist | 获取可见范围内全量通讯录成员 | 无 | 用户列表(userid、name、alias) |
| 场景 | 策略 |
|---|---|
| 精确匹配(name 或 alias 完全一致) | 直接使用,无需用户确认 |
| 模糊匹配(name 或 alias 包含关键词),唯一结果 | 直接使用,向用户展示结果 |
| 模糊匹配,多个结果 | 展示候选列表,请用户选择 |
| 无匹配结果 | 告知用户未找到对应人员 |