wecomcli-lookup-contact

Address Book Member Query Skill

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

Retrieve address book members within the current user's visible scope, and filter and match locally by name/alias.

Operations

1. Retrieve all address book members

Retrieve information for all enterprise members within the current user's visible scope:

Call example:

wecom-cli contact get_userlist '{}'

Return format:

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

Return field descriptions:

Field	Type	Description
errcode	integer	Return code,0 indicates 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. Search personnel by name/alias

get_userlist After returning all members, filter and match the results locally:

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

Search example:

User asks: "Help me find out who Zhang San is?"

1. Call get_userlist to retrieve all members
2. In userlist , filter for name or alias members containing "Zhang San"
3. Return matching results

---

Notes

• get_userlist returns members within the current user'svisible scope, subject to filtering by visibility rules, and not necessarily all personnel in the entire company; the returned fields only include userid、name(name) and alias(alias)

• ⚠️ The API will return an error when there are more than 10 people: If userlist returns more than 10 members, it is considered abnormal, and processing should be stopped immediately and the user should be informed:

  The current number of visible members in the address book exceeds the upper limit supported by this skill (10 people). This skill is only suitable for scenarios with a small visible scope and cannot be used in a large-scale address book. It is recommended to narrow the visible scope and try again, or query the target personnel through other means.

• userid is the user's unique identifier, use this field when the user ID needs to be passed to other APIs

• alias field may be an empty string, so null value checking is required during search

• If the search results include multiple people with the same name, all candidates must be shown to the user for selection, and you must not decide on your own

• If errcode is not 0, it indicates that the API call failed, and the user must be informed of the error message (errmsg）

---

Typical workflows

Workflow 1: Query personnel information

User asks: "Help me check who Sam is?"

wecom-cli contact get_userlist '{}'

Retrieve the full member list

1. In the results, filter for alias as Sam or name contains Sam members
2. If a unique match is found, display the result directly:

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

1. If multiple matches are found, display a candidate list for the user to confirm:

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

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

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

---

Workflow 2: Provide userid conversion for other features

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

wecom-cli contact get_userlist '{}'

Retrieve all members

1. Filter members whose name is "Zhang San", confirm userid
2. Pass userid to the message sending API

---

Workflow 3: Batch query multiple people

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

wecom-cli contact get_userlist '{}'

Retrieve the full member list

1. Filter the match results for "Zhang San" and "Li Si" respectively
2. Summarize and display together

Note: Only call get_userlistonce, and filter the results multiple times locally to avoid repeated API calls.

---

Quick Reference

API Description

API	Purpose	Input	Return
get_userlist	Retrieve all contacts members within the visible scope	None	User list (userid, name, alias)

Local Filtering Strategy

Scenario	Strategy
Exact match (name or alias exactly the same)	Use directly, no user confirmation needed
Fuzzy match (name or alias contains the keyword), unique result	Use directly, display the result to the user
Fuzzy match, multiple results	Display candidate list, ask the user to choose
No matching results	Inform the user that the corresponding person was not found