wecomcli-contact

WeCom Contact Search

Before executing any wecom-cli command, you must first read and complete the wecomcli-shared skill's common prerequisite check.

Use wecom-cli to search for people in the WeCom contacts by keyword.

API

Perform batch fuzzy search for people by keyword, up to 10 keywords at a time, returning hit users arrays (name / English name / position / department). Fields that keywords can match include: name (username), name pinyin, English name, and alias, not limited to Chinese names and aliases.

Command

wecom-cli contact users search --json '<JSON 参数>'

Parameters

Field	Type	Required	Default Value	Meaning
keywords	string[]	Yes	—	List of search keywords, can match by name (username) / pinyin / English name / alias, up to 10; multiple keywords are in an OR relationship
search_mode	string	No	—	Search mode, by default this parameter is not passed; only when you need to get the complete list of people should you explicitly pass "list"

• Default (do not pass search_mode): returns the most relevant candidate results, used for regular scenarios of looking up a single person by name / pinyin, etc. The vast majority of scenarios go through this branch.
• Pass search_mode = "list": returns the full list of hits. Only pass it when the user explicitly wants the "complete list", typical phrases such as "how many Zhang Sans are there / all people named Li Si / list all with the same name / all people with the same name", etc., indicating counting or exhaustive intent; in this case it is not subject to the "top 5" display limit.

Returns

Field	Type	Description
users	array	List of matched users
users[].userid	string	User unique identifier
users[].name	string	Chinese name
users[].alias	string	English name / alias (may be empty)
users[].email	string	Email (may be empty)
users[].position	string	Management position (such as "person in charge"),not"job title" (may be empty)
users[].matched_keywords	string[]	The request keyword that this user matched
users[].departments	string[]	List of department paths where the user belongs (from largest to smallest), with the primary department first
hint	string	Result limit hint (may be empty): when the matched results for a keyword are not fully returned due to limits, the API will provide an explanation in this field
users_count	integer	users Number of array elements

Usage Rules

• Ambiguity display limit: when there are more than 5 candidates under the same keyword, only the first 5 are displayed (with distinguishing information such as name / English name / position), and the user is told "if the target is not among them, you can request 'view more'"; only expand the next batch when the user explicitly requests it;
• Display order: must strictly follow the original order of the users array returned by the API, and must not randomly sort, rearrange, or shuffle the order on your own.
• Result limit hint: when the hint field in the return is non-empty, you must tell the user in the reply that "the current returned content is limited, and only partial results were returned", and you may explain the reason for the limitation based on the hint content.

Missing parameter

When required parameters are missing (no search keyword provided) and the context cannot infer it, ask the user for the missing information in concise natural language; do not guess default values.