A skill for calling the DingTalk Open Platform API, supporting user search/details/query, department management (search/details/sub-departments/user list/parent department), bot message sending, group bot query, resignation record query, OA approval management (query/initiate/approve/transfer/comment) and other functions.
Prerequisites
- Environment variable set
DINGTALK_APP_KEYandDINGTALK_APP_SECRET - The DingTalk application has been created and has the corresponding API permissions
Environment Variable Configuration
export DINGTALK_APP_KEY="<your-app-key>"
export DINGTALK_APP_SECRET="<your-app-secret>"
Feature List
1. Search User (search-user)
Search for users by name and return the list of matching UserIds.
npx ts-node scripts/search-user.ts "<搜索关键词>"
Output:
{
"success": true,
"keyword": "张三",
"totalCount": 3,
"hasMore": false,
"userIds": ["123456789", "987654321"]
}
2. Search Department (search-department)
Search for departments by name and return the list of matching department IDs.
npx ts-node scripts/search-department.ts "<搜索关键词>" [--debug]
Output:
{
"success": true,
"keyword": "技术部",
"totalCount": 2,
"hasMore": false,
"departmentIds": [12345, 67890]
}
3. Get Department Details (get-department)
Get the detailed information of the specified department.
npx ts-node scripts/get-department.ts <deptId> [--debug]
Output:
{
"success": true,
"department": {
"deptId": 12345,
"name": "技术部",
"parentId": 1
}
}
4. Get Sub-department List (list-sub-departments)
Get the list of sub-department IDs under the specified department. The root department deptId is 1.
npx ts-node scripts/list-sub-departments.ts <deptId> [--debug]
Output:
{
"success": true,
"deptId": 1,
"subDepartmentIds": [12345, 67890, 11111]
}
5. Get Department User List (list-department-users)
Get the user list under the specified department (userId + name), automatically paginating to retrieve all users.
npx ts-node scripts/list-department-users.ts <deptId> [--debug]
Output:
{
"success": true,
"deptId": 12345,
"users": [
{ "userId": "user001", "name": "张三" },
{ "userId": "user002", "name": "李四" }
]
}
6. Send Single-Chat Message (send-user-message)
Send a single-chat message to the specified user via the bot.
npx ts-node scripts/send-user-message.ts "<userId>" "<robotCode>" "<消息内容>" [--debug]
Output:
{
"success": true,
"userId": "123456",
"robotCode": "robot_code",
"processQueryKey": "query_key",
"flowControlledStaffIdList": [],
"invalidStaffIdList": [],
"message": "消息内容"
}
7. Send Group Chat Message (send-group-message)
Send a message to the specified group conversation via the bot.
npx ts-node scripts/send-group-message.ts "<openConversationId>" "<robotCode>" "<消息内容>" [--debug]
Output:
{
"success": true,
"openConversationId": "cid",
"robotCode": "robot_code",
"processQueryKey": "query_key",
"message": "消息内容"
}
8. Get Group Bot List (get-bot-list)
Query the list of bots already configured in the group.
npx ts-node scripts/get-bot-list.ts "<openConversationId>" [--debug]
Output:
{
"success": true,
"openConversationId": "cid",
"botList": [
{
"robotCode": "code",
"robotName": "name",
"robotAvatar": "url",
"openRobotType": 1
}
]
}
9. Query User Details (get-user)
Get the detailed information of the specified user, including name, mobile number, email, department list, etc.
npx ts-node scripts/get-user.ts "<userId>" [--debug]
Output:
{
"success": true,
"user": {
"userid": "user001",
"name": "张三",
"mobile": "138****1234",
"email": "zhangsan@example.com",
"dept_id_list": [12345, 67890]
}
}
10. Get User Parent Department List (list-user-parent-departments)
Get the list of all parent departments to which the specified user belongs, from the direct department to the root department.
npx ts-node scripts/list-user-parent-departments.ts "<userId>" [--debug]
Output:
{
"success": true,
"userId": "user001",
"parentIdList": [12345, 67890, 1]
}
11. Get Department Parent List (list-department-parents)
Get the list of all parent departments of the specified department; the first is itself and the last is the root department.
npx ts-node scripts/list-department-parents.ts <deptId> [--debug]
Output:
{
"success": true,
"deptId": 12345,
"parentIdList": [12345, 67890, 1]
}
12. Get Department User ID List (list-department-user-ids)
Get the list of userids of all users under the specified department.
npx ts-node scripts/list-department-user-ids.ts <deptId> [--debug]
Output:
{
"success": true,
"deptId": 12345,
"userIds": ["user001", "user002", "user003"]
}
13. Get Department User Details Paginated Version (list-department-user-details)
Get department user detailed information in pages, supporting custom cursor and size.
npx ts-node scripts/list-department-user-details.ts <deptId> [--cursor <cursor>] [--size <size>] [--debug]
Output:
{
"success": true,
"deptId": 12345,
"users": [
{ "userid": "user001", "name": "张三" },
{ "userid": "user002", "name": "李四" }
],
"hasMore": true,
"nextCursor": 100
}
14. Get Employee Count (get-user-count)
Get the total number of enterprise employees, with the option of counting only activated employees.
npx ts-node scripts/get-user-count.ts [--onlyActive] [--debug]
Output:
{
"success": true,
"onlyActive": false,
"count": 150
}
15. Query User by Mobile Number (get-user-by-mobile)
Query the user userid by mobile number. Available only for internal enterprise applications, and only for querying active employees.
npx ts-node scripts/get-user-by-mobile.ts "<mobile>" [--debug]
Output:
{
"success": true,
"mobile": "13800138000",
"userId": "user001"
}
16. Query user by unionid (get-user-by-unionid)
Get the user userid by unionid.
npx ts-node scripts/get-user-by-unionid.ts "<unionid>" [--debug]
Output:
{
"success": true,
"unionid": "xxxxx",
"userId": "user001"
}
17. Get list of inactive users (list-inactive-users)
Get the list of DingTalk employees who have not logged in on the specified date. Only data within one month can be queried, and it must be called after 9 AM each day to ensure obtaining the previous day's data.
npx ts-node scripts/list-inactive-users.ts "<queryDate>" [--deptIds "id1,id2"] [--offset <offset>] [--size <size>] [--debug]
Output:
{
"success": true,
"queryDate": "20240115",
"userIds": ["user001", "user002"],
"hasMore": false
}
18. Query list of resignation records (list-resigned-users)
Query resignation records of employees within the specified time range. Only available for internal enterprise applications.
npx ts-node scripts/list-resigned-users.ts "<startTime>" ["<endTime>"] [--nextToken <token>] [--maxResults <max>] [--debug]
Output:
{
"success": true,
"startTime": "2024-01-01T00:00:00+08:00",
"endTime": "2024-02-01T00:00:00+08:00",
"records": [
{
"userId": "user001",
"name": "张三",
"leaveTime": "2024-01-15T10:00:00Z",
"leaveReason": "个人原因"
}
]
}
19. Get list of approval instance IDs (list-approval-instance-ids)
Get the list of approval instance IDs for the specified approval template within a time period.
npx ts-node scripts/list-approval-instance-ids.ts <processCode> --startTime <timestamp> --endTime <timestamp> [--size <size>] [--nextToken <token>] [--debug]
Output:
{
"success": true,
"processCode": "PROC-XXX",
"instanceIds": ["xxx-123", "xxx-456"],
"totalCount": 2,
"hasMore": false,
"nextToken": null
}
20. Get approval instance details (get-approval-instance)
Get detailed information of a single approval instance, including form data, approval records, task list, etc.
npx ts-node scripts/get-approval-instance.ts <instanceId> [--debug]
Output:
{
"success": true,
"instanceId": "xxx-123",
"instance": {
"processInstanceId": "xxx-123",
"title": "请假申请",
"createTimeGMT": "2024-01-01T00:00:00Z",
"finishTimeGMT": "2024-01-01T12:00:00Z",
"originatorUserId": "user001",
"originatorDeptId": "1",
"status": "COMPLETED",
"processCode": "PROC-XXX",
"formComponentValues": [...],
"operationRecords": [...],
"tasks": [...]
}
}
21. Get list of approvals initiated by user (list-user-initiated-approvals)
Get the list of approval instances initiated by the user.
npx ts-node scripts/list-user-initiated-approvals.ts <userId> [--startTime <timestamp>] [--endTime <timestamp>] [--maxResults <max>] [--nextToken <token>] [--debug]
Output:
{
"success": true,
"userId": "user001",
"instances": [...],
"totalCount": 5,
"hasMore": false,
"nextToken": null
}
22. Get list of approvals CC'd to user (list-user-cc-approvals)
Get the list of approval instances CC'd to the user.
npx ts-node scripts/list-user-cc-approvals.ts <userId> [--startTime <timestamp>] [--endTime <timestamp>] [--maxResults <max>] [--nextToken <token>] [--debug]
23. Get list of pending approvals (list-user-todo-approvals)
Get the list of approval tasks pending for the user.
npx ts-node scripts/list-user-todo-approvals.ts <userId> [--maxResults <max>] [--nextToken <token>] [--debug]
Output:
{
"success": true,
"userId": "user001",
"instances": [...],
"totalCount": 3,
"hasMore": false,
"nextToken": null
}
24. Get list of processed approvals (list-user-done-approvals)
Get the list of approval instances processed by the user.
npx ts-node scripts/list-user-done-approvals.ts <userId> [--startTime <timestamp>] [--endTime <timestamp>] [--maxResults <max>] [--nextToken <token>] [--debug]
25. Get pending approval count (get-user-todo-count)
Get the number of approval tasks pending for the user.
npx ts-node scripts/get-user-todo-count.ts <userId> [--debug]
Output:
{
"success": true,
"userId": "user001",
"count": 5
}
26. Initiate approval instance (create-approval-instance)
Create a new approval instance.
npx ts-node scripts/create-approval-instance.ts <processCode> <originatorUserId> <deptId> '<formValuesJson>' [--ccList "user1,user2"] [--debug]
Example:
npx ts-node scripts/create-approval-instance.ts "PROC-XXX" "user001" "1" '[{"name":"标题","value":"请假申请"},{"name":"请假天数","value":"3"}]'
Output:
{
"success": true,
"processCode": "PROC-XXX",
"originatorUserId": "user001",
"instanceId": "xxx-new"
}
27. Terminate approval instance (terminate-approval-instance)
Cancel/terminate the specified approval instance.
npx ts-node scripts/terminate-approval-instance.ts <instanceId> <operatingUserId> [--remark "撤销原因"] [--debug]
Output:
{
"success": true,
"instanceId": "xxx-123",
"message": "审批实例已终止"
}
28. Execute approval task (execute-approval-task)
Approve or reject an approval task.
npx ts-node scripts/execute-approval-task.ts <instanceId> <userId> <agree|refuse> [--taskId <taskId>] [--remark "审批意见"] [--debug]
Example:
npx ts-node scripts/execute-approval-task.ts "xxx-123" "user001" "agree" --remark "同意申请"
npx ts-node scripts/execute-approval-task.ts "xxx-123" "user001" "refuse" --remark "条件不符"
Output:
{
"success": true,
"instanceId": "xxx-123",
"userId": "user001",
"action": "agree",
"message": "已同意审批"
}
29. Transfer approval task (transfer-approval-task)
Transfer the approval task to another user for processing.
npx ts-node scripts/transfer-approval-task.ts <instanceId> <userId> <transferToUserId> [--taskId <taskId>] [--remark "转交原因"] [--debug]
Output:
{
"success": true,
"instanceId": "xxx-123",
"userId": "user001",
"transferToUserId": "user002",
"message": "审批任务已转交"
}
30. Add approval comment (add-approval-comment)
Add a comment to an approval instance.
npx ts-node scripts/add-approval-comment.ts <instanceId> <userId> "<comment>" [--debug]
Output:
{
"success": true,
"instanceId": "xxx-123",
"userId": "user001",
"message": "评论已添加"
}
Error handling
All scripts return a unified format on error:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误描述"
}
}
Common error codes:
MISSING_CREDENTIALS- Environment variable not setINVALID_ARGUMENTS- Insufficient parametersAUTH_FAILED- Failed to obtain access_tokenUNKNOWN_ERROR- API call exception