dingtalk-contact

DingTalk Contacts Skill

Prerequisites — must-read before performing operations

**CRITICAL — before performing any dws operation, you MUST first use the Read tool to fully read dingtalk-shared.** This lightweight file contains the global execution contract, security bottom lines, and on-demand loading navigation for shared references; do not preload all of its references.

Command reference:contact.md; playbook:08-directory.md。

Shortcuts (preferred when there is no dedicated script/recipe)

The following shortcuts enter both the public catalog and the Runtime Schema. Route according to this skill/recipe; when matched, Shortcuts take precedence over atomic commands. For parameters, only check dws schema --cli-path "contact +<shortcut>" --compact --jq '{cli_path,parameters,constraints,confirmation}' -f json; when only and already-published result is needed, check --jq '{cli_path,outcomes:.result.outcomes,pagination}', and for field-level details check data_schema; do not infer from Help/examples when missing. Only read a known leaf Help once if the Schema is unavailable;unknown flag use the same leaf Help to correct once.unknown command Help is prohibited: on an erroneous suggestion → use the already-loaded Skill/reference explicit entry point; if neither exists, report drift. Full Catalog/root/parent/product Help is prohibited; omit --compactonly for mapping, interface, or provenance audits. Only when neither the existing routing nor references can locate a low-frequency capability, use dws shortcut list --service contact --format json for discovery.

Shortcut	Risk	Applicable scenarios
dws contact +by-mobile	read	Look up a person's full profile by mobile number (automatically resolve userId, then fetch details)
dws contact +dept-members	read	List department members by department name (automatically resolve deptId)
dws contact +friend-list	read	Query the current user's friend list
dws contact +friend-remove	high-risk-write	Delete a specified friend
dws contact +friend-request-accept	write	Accept a friend request sent by a specified user
dws contact +friend-request-list	read	Query the list of friend requests received by the current user
dws contact +friend-request-reject	write	Delete (ignore) a friend request sent by a specified user
dws contact +friend-request-send	write	Initiate a friend request to a specified user
dws contact +list-dept-members	read	View department members (current department only, excluding subordinates)
dws contact +list-followings	read	Get the current user's special attention list
dws contact +list-role-members	read	Query the member list under a role
dws contact +list-sub-depts	read	View the sub-departments of a specified department
dws contact +lookup	read	Look up a person's full profile by name (automatically resolve userId, then fetch details)
dws contact +me	read	View your own contacts profile (name/userId/mobile/department/organization, clean projection)
dws contact +org	read	Look up the details of the department a person belongs to by name (automatically resolve userId and deptId)
dws contact +resolve-dept	read	Search for departments by name and resolve a unique deptId (read-only)
dws contact +search-mobile	read	Search contacts users by mobile number
dws contact +search-user	read	Search contacts users by keyword
dws contact +team	read	List the members of the department a person belongs to by name (automatically resolve userId and deptId)

Intent table

User says	Command
"Look up my own information"	dws contact user get-self
"Look up details by userId"	dws contact user get --ids <userId1>,<userId2>,...(multiple in parallel)
"Reverse-look-up a user by full mobile number"	dws contact user search-mobile --mobile <手机号>
"Get userId by open DingTalk ID (openDingTalkId)"	dws contact user get-by-open-dingtalk-id --id <openDingTalkId>
"My friends / friend list / which friends do I have"	dws contact +friend-list
"Friend requests / Who added me / pending friend requests"	dws contact +friend-request-list
"Add friend / Send friend request / Add someone as a friend"	dws contact +friend-request-send --to <openDingTalkId>
"Approve friend request / Accept friend request"	dws contact +friend-request-accept --from <openDingTalkId>
"Reject friend request / Ignore friend request"	dws contact +friend-request-reject --from <openDingTalkId>
"Delete friend / Remove friend"	dws contact +friend-remove --friend <openDingTalkId>(high risk, requires user confirmation)
"Pull members by department name"	python scripts/contact_dept_members.py --query "<部门名>"
"Search department"	dws contact dept search --query "<关键词>"
"Department member list"	dws contact dept list-members --ids <deptId>
"List enterprise roles / What roles are there"	dws contact label list
"Look up role ID by role name"	dws contact label get --names "<角色名>"
"Check which members are under a certain role"	dws contact label list-members --id <labelId>

Standard SOP (mandatory process)

When the following intents are matchedmustexecute in the corresponding SOP order;forbiddento skip steps, replace commands, or fabricate userId. Each command must include --format json. Fuzzy name search, employee ID, responsibilities, and superiors/subordinates go through dingtalk-aisearch; complete mobile number exact reverse lookup goes through contact; after obtaining the userId, contact fills in the details.

SOP-1 Search person (search-person)

Trigger: Find people by name/employee ID/department/responsibilities/superiors and subordinates, or use mobile number clues for semantic search.

1. Switch to aisearch (mandatory)：dws aisearch person --query "<关键词>" --dimension <维度> --format json(name→name, employee ID→jobNumber, mobile number semantic clue→phone, person in charge→duty, department→department, superiors/subordinates→supervisor/subordinate）。
2. Parse (mandatory): Take from the results userId、title；When multiple people share the same name, do not default to selecting the first one, must batch dws contact user get --ids <id1,id2,...> --format json to get department/position and then have the user confirm.
3. Fill in details (mandatory): When complete department/position/email/supervisor is needed dws contact user get --ids <userId> --format json。

Forbidden: Use contact user search for name or employee ID search, default to taking the first candidate, fabricate personnel fields. Complete mobile number exact reverse lookup is search-mobile the only search exception.

SOP-1A Complete mobile number exact reverse lookup (search-person-by-mobile)

Trigger: The user provides a complete mobile number and requests confirmation of who it is or to obtain the userId.

1. Execute (mandatory)：dws contact user search-mobile --mobile "<完整手机号>" --format json。
2. Fill in details (as needed): Take from the results userId, when department, position, or email is needed continue dws contact user get --ids <userId> --format json。

Forbidden: Change the complete mobile number exact reverse lookup to name search, or guess the person when userId is not returned.

SOP-2 Exact person lookup/fill in details (search-user)

Trigger: Already have a userId and need to look up complete details, or need to obtain the userId for downstream use (send message/create to-do/schedule appointment).

1. Get userId (mandatory)：dws aisearch person --query "<姓名>" --dimension name --format json → userId; when multiple matches occur, must list candidates and ask the user to confirm.
2. Look up details (mandatory)：dws contact user get --ids <userId> --format json, reply according to the returned fields (orgEmployeeModel department/position/email under).

Forbidden: Use fuzzy keywords to directly call contact user search to make up numbers, fabricate fields that were not returned.

SOP-3 Look up self (get-contact-self)

Trigger: My information/my userId/my department.

1. Execute (mandatory)：dws contact user get-self --format json, take orgEmployeeModel.userId / orgUserName / depts[].deptName / supervisor, etc.

Prohibited: Hardcoding or guessing your own userId.

SOP-4 Query department / role (dept-and-relation)

Trigger: Department list/department members/roles/role members.

1. Execute (required): Search department dws contact dept search --query "<部门名>" --format json; sub-departments under a department dws contact dept list-children --dept <父部门ID> --format json; department members dws contact dept list-members --ids <部门ID>[,<部门ID2>...] --format json; department details dws contact dept get-info --dept <部门ID> --format json. Role:dws contact label list / dws contact label get --names "<角色名>" / dws contact label list-members --id <labelId>. When searching the enterprise root department, the server may return deptId=-1 sentinel, subsequently list-children / list-members / get-info must be normalized to the real root department deptId=1。
2. Supplement details (required): After obtaining the userId, use contact user get --ids to supplement department/position; superior-subordinate relationships should preferably go through dingtalk-aisearch 's supervisor/subordinate dimension.

Prohibited: Using non-existent contact dept list(deprecated/ambiguous), fabricating deptId/labelId, skipping the aisearch dimension and directly guessing superior-subordinate relationships.

SOP-5 Friend relationship (friend)

Trigger: Friend list, friend requests, adding friends, accepting/rejecting requests, deleting friends.

1. Obtain openDingTalkId (required): All friend commands use Open DingTalk ID (openDingTalkId) as the identity key. Sources of openDingTalkId: ① Data from the friend domain itself——dws contact +friend-list --format json / dws contact +friend-request-list --format json returned item's openDingTalkId field, or the friend event message body (user_contact_friend_request_received 's src/dest_open_dingtalk_id、user_contact_friend_added 's friend_open_dingtalk_id); ② Search for people by name and other keywords——dws contact user search --query "<姓名>" --format json(search_contact_by_key_word) results return both userId and openDingTalkId. Note:aisearch person and contact user get-by-dingtalk-id only return userId,openDingTalkId cannot be obtained; after obtaining openDingTalkId , if userId is needed, call dws contact user get-by-open-dingtalk-id --id <openDingTalkId> --format json。
2. Query friends (required)：dws contact +friend-list --format json returns the friend list of the currently logged-in user (including nickname nick, alias alias), friend status and pagination information;dws contact +friend-request-list --format json returns received friend requests (including requester nickname nick, request message, status) and the pending count. When displaying the list to the user, preferably use nick / alias to identify friends, and do not display openDingTalkId unless necessary; when reporting the request status, it must be translated into a Chinese status (1=pending acceptance, 3=already friends), do not directly display numbers.
3. Write operations (required): Send request dws contact +friend-request-send --to <openDingTalkId> --remark "<验证留言>" --format json; accept dws contact +friend-request-accept --from <openDingTalkId> --format json; reject dws contact +friend-request-reject --from <openDingTalkId> --format json; delete friend dws contact +friend-remove --friend <openDingTalkId> --format json(the last one is an irreversible high-risk write operation,must first obtain explicit user confirmation）。

Prohibited: Mixing up DingTalk ID (dingtalkId) and Open DingTalk ID (openDingTalkId); directly executing write operations when openDingTalkId is missing; deleting a friend without confirmation.

High-frequency hard constraints

• Contacts questions must call dws contact or dws aisearch to obtain real-time results; it is strictly prohibited to only read USER.md, environment identity or static context and then answer directly.
• To query yourself use dws contact user get-self --format json, do not treat me/self/current as userId and pass it to user get。
• Fuzzy name search, employee ID reverse lookup, responsibility or superior-subordinate search go through dws aisearch person; complete mobile number exact reverse lookup goes through dws contact user search-mobile --mobile "<手机号>" --format json. After obtaining userId , as needed dws contact user get --ids <userId> --format json Fill in department/position/email.
• When querying the direct supervisor/subordinates or superiors, if contact user get does not return an explicit supervisor field, you must continue with dws aisearch person --query "<完整姓名或工号>" --dimension supervisor --format json, and do not stop at "may require further querying".
• When there are multiple candidates with the same name, batch contact user get --ids id1,id2,... --format json to get department/position before disambiguating; do not default to taking the first one.
• When the user queries enterprise roles, role IDs, role members, or personnel in role types such as "administrator/finance/HR/supervisor", use contact label list/get/list-members; do not use dept list-members to filter fields as a substitute.
• Friend commands (+friend-*) all use openDingTalkId as the identity key, not userId and not the DingTalk number; openDingTalkId can be obtained from the +friend-list / +friend-request-list response, the friend event message body, or contact user search(search people by keyword, returning both userId and openDingTalkId);aisearch person / get-by-dingtalk-id only returns userId and cannot obtain openDingTalkId.
• +friend-remove is an irreversible high-risk write operation; before executing,mustshow the target openDingTalkId to the user and obtain explicit confirmation; only after confirmation may you add --yes。

Cross-product collaboration

• Fuzzy name search, superiors/subordinates, who is responsible, reverse lookup by employee ID, semantic phone number search → dingtalk-aisearch
• Exact reverse lookup by full phone number → dws contact user search-mobile
• Get email and send email → switch to dingtalk-mail
• Get userId and send message → switch to dingtalk-chat

Local intents and short flows

• Local intent disambiguation；short flow。