dingtalk-contact

DingTalk Contacts Skill

Responsible for all query operations of DingTalk contacts. This file isstrategy guide, containing only decision logic and workflows. For the complete API request format, see the "references/api.md lookup index" at the end of this document.

dt_helper.sh is located in this SKILL.md sibling directory's scripts/dt_helper.sh。

Workflow (before each execution)

First identify the task type for this run → e.g.: search users, look up user details, search departments, list department members, look up department path, count employees
Validate the required configuration for this task → via bash scripts/dt_helper.sh --get KEY read; only validate the items required for this task
Collect only the missing configuration → if something is missing,ask the user in one gofor all missing values, use bash scripts/dt_helper.sh --set KEY=VALUE to write
Obtain Token → directly call bash scripts/dt_helper.sh
Execute the operation → for complex ones, create a temporary file and then execute; for simple ones, execute directly; heredoc is prohibited

Validate configuration per task (must be done first)

Common required for all tasks：DINGTALK_APP_KEY、DINGTALK_APP_SECRET
Tasks that need "using the current operator as the starting point" or "directly reading one's own identity information": must have DINGTALK_MY_USER_ID

Rule: before passing the "configuration validation for this task", you must not enter the API call step.

Credentials are prohibited from being printed in full in the output; when confirming, show only the first 4 characters + ****

Required configuration

Configuration key	Required	Description	How to obtain
`DINGTALK_APP_KEY`	✅	Application AppKey	DingTalk Open Platform → Application Management → Credential Information
`DINGTALK_APP_SECRET`	✅	Application AppSecret	Same as above
`DINGTALK_MY_USER_ID`	❌	Current operating user's userId (i.e., the person running this skill themselves); only needed when querying with oneself as the starting point	Admin console → Contacts → Member Management → click the name to view

Identity Identifier Description

Identifier	Description
`userId`（= `staffId`）	Enterprise internal employee ID, which can be viewed via Admin Console -> Contacts -> Member Management -> click the name
`unionId`	Cross-enterprise/cross-application unique identifier, which can be obtained via `bash scripts/dt_helper.sh --to-unionid <userid>` obtained

Execution Script Template

#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
NEW_TOKEN=$(bash "$HELPER" --token)       # api.dingtalk.com 接口用
OLD_TOKEN=$(bash "$HELPER" --old-token)   # oapi.dingtalk.com 接口用
# USER_ID=$(bash "$HELPER" --get DINGTALK_MY_USER_ID)  # 以当前操作用户为起点时启用

# 在此追加具体 API 调用，例如按姓名搜索用户并获取详情：
KEYWORD="张三"
SEARCH=$(curl -s -X POST https://api.dingtalk.com/v1.0/contact/users/search \
  -H "x-acs-dingtalk-access-token: $NEW_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"queryWord\":\"$KEYWORD\",\"offset\":0,\"size\":20}")
echo "搜索结果: $SEARCH"

TARGET_UID=$(echo "$SEARCH" | grep -o '"list":\["[^"]*"' | grep -o '"[^"]*"$' | tr -d '"')
DETAIL=$(curl -s -X POST "https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${OLD_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{\"userid\":\"$TARGET_UID\",\"language\":\"zh_CN\"}")
echo "用户详情: $DETAIL"

Token expiration handling: dt_helper only caches by time and cannot detect that a token has been revoked early. If the API returns errcode 40001/40014(token invalid/expired), use --nocache to skip the cache and force re-obtaining:
OLD_TOKEN=$(bash "$HELPER" --old-token --nocache)  # 强制重新获取旧版 token
NEW_TOKEN=$(bash "$HELPER" --token --nocache)       # 强制重新获取新版 token

references/api.md lookup index

After determining what to do, use the following command to extract the complete API details of the corresponding section from references/api.md (request format, parameter descriptions, return value examples):

grep -A 30 "^## 1. 按关键词搜索用户" references/api.md
grep -A 50 "^## 2. 获取用户完整详情" references/api.md
grep -A 20 "^## 3. unionId → userId 转换" references/api.md
grep -A 18 "^## 4. 企业员工总人数" references/api.md
grep -A 25 "^## 5. 按关键词搜索部门" references/api.md
grep -A 25 "^## 6. 获取子部门列表" references/api.md
grep -A 20 "^## 7. 获取子部门 ID 列表" references/api.md
grep -A 25 "^## 8. 获取部门详情" references/api.md
grep -A 40 "^## 9. 获取部门成员完整列表" references/api.md
grep -A 18 "^## 10. 获取部门成员 userId 列表" references/api.md
grep -A 20 "^## 11. 获取用户所在部门路径" references/api.md
grep -A 12 "^## 错误码" references/api.md
grep -A 6 "^## 所需应用权限" references/api.md