DingTalk API Skill
钉钉开放平台 API 调用技能，支持用户搜索/详情/查询、部门管理（搜索/详情/子部门/用户列表/父部门）、机器人单聊/群聊消息发送、群内机器人列表查询、离职记录查询、OA审批管理（查询/发起/审批/转交/评论）等功能。
已发布到 ClawHub，可通过
clawhub install dingtalk-api一键安装。
功能特性
用户管理
- 用户搜索 - 根据姓名搜索用户，返回 UserId 列表
- 用户详情 - 获取指定用户的详细信息
- 用户所属部门 - 获取指定用户的所有父部门列表
- 手机号查用户 - 根据手机号查询用户 userid
- unionid查用户 - 根据 unionid 查询用户 userid
- 员工人数 - 获取企业员工总数（可选仅已激活）
- 未登录用户 - 获取未登录钉钉的员工列表
- 离职记录 - 查询离职员工记录列表
部门管理
- 部门搜索 - 根据名称搜索部门，返回部门 ID 列表
- 部门详情 - 获取指定部门的详细信息
- 父部门列表 - 获取指定部门的所有父部门列表
- 子部门列表 - 获取指定部门下的子部门 ID 列表
- 部门用户列表 - 获取指定部门下的用户列表
- 部门用户ID列表 - 获取指定部门下所有用户的 userid 列表
消息与机器人
- 单聊消息 - 通过机器人向指定用户发送单聊消息
- 群聊消息 - 通过机器人向指定群会话发送消息
- 机器人列表 - 查询群内已配置的机器人列表
OA审批管理
- 审批实例 ID 列表 - 获取指定审批模板在时间段内的实例 ID 列表
- 审批实例详情 - 获取单个审批实例的详细信息
- 用户发起审批 - 获取用户发起的审批列表
- 抄送用户审批 - 获取抄送用户的审批列表
- 待处理审批 - 获取用户待处理的审批列表
- 已处理审批 - 获取用户已处理的审批列表
- 待审批数量 - 获取用户待审批任务数量
- 发起审批 - 创建新的审批实例
- 终止审批 - 撤销/终止审批实例
- 执行任务 - 同意或拒绝审批任务
- 转交任务 - 将审批任务转交给其他用户
- 添加评论 - 为审批实例添加评论
技术特性
- 自动认证 - 自动获取 access_token，无需手动管理
- TypeScript - 类型安全，代码提示友好
安装方式
方式一：通过 ClawHub 安装（推荐）
npm install -g clawhub
clawhub install dingtalk-api
方式二：通过 Git 安装
git clone https://github.com/ogenes/dingtalk-api.git
cd dingtalk-api
npm install
配置环境变量
export DINGTALK_APP_KEY="<your-app-key>"
export DINGTALK_APP_SECRET="<your-app-secret>"
使用方法
1. 搜索用户
npm run search-user -- "张三"
输出：
{
"success": true,
"keyword": "张三",
"totalCount": 3,
"hasMore": false,
"userIds": ["123456789", "987654321", "456789123"]
}
2. 搜索部门
npm run search-department -- "技术部"
输出：
{
"success": true,
"keyword": "技术部",
"totalCount": 2,
"hasMore": false,
"departmentIds": [12345, 67890]
}
3. 获取部门详情
npm run get-department -- 12345
输出：
{
"success": true,
"department": {
"deptId": 12345,
"name": "技术部",
"parentId": 1
}
}
4. 获取子部门列表
npm run list-sub-departments -- 1
输出：
{
"success": true,
"deptId": 1,
"subDepartmentIds": [12345, 67890, 11111]
}
5. 获取部门用户列表
npm run list-department-users -- 12345
输出：
{
"success": true,
"deptId": 12345,
"users": [
{ "userId": "user001", "name": "张三" },
{ "userId": "user002", "name": "李四" }
]
}
6. 发送单聊消息
npm run send-user-message -- "<userId>" "<robotCode>" "你好"
输出：
{
"success": true,
"userId": "123456",
"robotCode": "robot_code",
"processQueryKey": "query_key",
"flowControlledStaffIdList": [],
"invalidStaffIdList": [],
"message": "你好"
}
7. 发送群聊消息
npm run send-group-message -- "<openConversationId>" "<robotCode>" "大家好"
输出：
{
"success": true,
"openConversationId": "cid",
"robotCode": "robot_code",
"processQueryKey": "query_key",
"message": "大家好"
}
8. 获取群内机器人列表
npm run get-bot-list -- "<openConversationId>"
输出：
{
"success": true,
"openConversationId": "cid",
"botList": [
{
"robotCode": "code",
"robotName": "name",
"robotAvatar": "url",
"openRobotType": 1
}
]
}
所有命令支持 --debug 参数查看完整 API 响应。
9. 获取审批实例 ID 列表
npm run list-approval-instance-ids -- "PROC-XXX" --startTime 1704067200000 --endTime 1706745600000
输出：
{
"success": true,
"processCode": "PROC-XXX",
"instanceIds": ["xxx-123", "xxx-456"],
"totalCount": 2,
"hasMore": false
}
10. 获取审批实例详情
npm run get-approval-instance -- "xxx-123"
输出：
{
"success": true,
"instanceId": "xxx-123",
"instance": {
"processInstanceId": "xxx-123",
"title": "请假申请",
"createTimeGMT": "2024-01-01T00:00:00Z",
"originatorUserId": "user001",
"status": "COMPLETED",
"formComponentValues": [...]
}
}
11. 获取用户发起的审批列表
npm run list-user-initiated-approvals -- "user001" --startTime 1704067200000 --endTime 1706745600000
输出：
{
"success": true,
"userId": "user001",
"instances": [...],
"totalCount": 5,
"hasMore": false
}
12. 获取用户待处理审批列表
npm run list-user-todo-approvals -- "user001"
输出：
{
"success": true,
"userId": "user001",
"instances": [...],
"totalCount": 3,
"hasMore": false
}
13. 获取用户待审批数量
npm run get-user-todo-count -- "user001"
输出：
{
"success": true,
"userId": "user001",
"count": 5
}
14. 发起审批实例
npm run create-approval-instance -- "PROC-XXX" "user001" "1" '[{"name":"标题","value":"测试审批"}]'
输出：
{
"success": true,
"processCode": "PROC-XXX",
"originatorUserId": "user001",
"instanceId": "xxx-new"
}
15. 终止审批实例
npm run terminate-approval-instance -- "xxx-123" "user001" --remark "撤销原因"
输出：
{
"success": true,
"instanceId": "xxx-123",
"message": "审批实例已终止"
}
16. 执行审批任务（同意/拒绝）
npm run execute-approval-task -- "xxx-123" "user001" "agree" --remark "同意"
npm run execute-approval-task -- "xxx-123" "user001" "refuse" --remark "拒绝原因"
输出：
{
"success": true,
"instanceId": "xxx-123",
"userId": "user001",
"action": "agree",
"message": "已同意审批"
}
17. 转交审批任务
npm run transfer-approval-task -- "xxx-123" "user001" "user002" --remark "转交给他人处理"
输出：
{
"success": true,
"instanceId": "xxx-123",
"userId": "user001",
"transferToUserId": "user002",
"message": "审批任务已转交"
}
18. 添加审批评论
npm run add-approval-comment -- "xxx-123" "user001" "这是一条评论"
输出：
{
"success": true,
"instanceId": "xxx-123",
"userId": "user001",
"message": "评论已添加"
}
19. 获取用户详情
npm run get-user -- "user001"
输出：
{
"success": true,
"user": {
"userid": "user001",
"name": "张三",
"mobile": "138****1234",
"email": "zhangsan@example.com",
"dept_id_list": [12345, 67890]
}
}
10. 获取用户父部门列表
npm run list-user-parent-departments -- "user001"
输出：
{
"success": true,
"userId": "user001",
"parentIdList": [12345, 67890, 1]
}
11. 获取部门父部门列表
npm run list-department-parents -- 12345
输出：
{
"success": true,
"deptId": 12345,
"parentIdList": [12345, 67890, 1]
}
12. 获取部门用户ID列表
npm run list-department-user-ids -- 12345
输出：
{
"success": true,
"deptId": 12345,
"userIds": ["user001", "user002", "user003"]
}
13. 获取部门用户详情（分页）
npm run list-department-user-details -- 12345 --cursor 0 --size 50
输出：
{
"success": true,
"deptId": 12345,
"users": [
{ "userid": "user001", "name": "张三" },
{ "userid": "user002", "name": "李四" }
],
"hasMore": true,
"nextCursor": 100
}
14. 获取员工人数
npm run get-user-count
npm run get-user-count -- --onlyActive
输出：
{
"success": true,
"onlyActive": false,
"count": 150
}
15. 根据手机号查询用户
npm run get-user-by-mobile -- "13800138000"
输出：
{
"success": true,
"mobile": "13800138000",
"userId": "user001"
}
16. 根据 unionid 查询用户
npm run get-user-by-unionid -- "xxxxx"
输出：
{
"success": true,
"unionid": "xxxxx",
"userId": "user001"
}
17. 获取未登录用户列表
npm run list-inactive-users -- "20240115" --deptIds "12345,67890" --offset 0 --size 100
输出：
{
"success": true,
"queryDate": "20240115",
"userIds": ["user001", "user002"],
"hasMore": false
}
18. 查询离职记录列表
npm run list-resigned-users -- "2024-01-01T00:00:00+08:00" "2024-02-01T00:00:00+08:00"
输出：
{
"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": "个人原因"
}
]
}
前置要求
-
钉钉应用
- 在 钉钉开放平台 创建企业内部应用
- 添加权限：通讯录搜索、通讯录部门信息读权限、机器人发送消息等
- 获取 AppKey 和 AppSecret
-
环境
- Node.js >= 16
项目结构
dingtalk-api/
├── scripts/
│ ├── search-user.ts # 用户搜索
│ ├── get-user.ts # 用户详情
│ ├── list-user-parent-departments.ts # 用户父部门列表
│ ├── get-user-by-mobile.ts # 手机号查用户
│ ├── get-user-by-unionid.ts # unionid查用户
│ ├── get-user-count.ts # 员工人数
│ ├── list-inactive-users.ts # 未登录用户列表
│ ├── list-resigned-users.ts # 离职记录列表
│ ├── search-department.ts # 部门搜索
│ ├── get-department.ts # 部门详情
│ ├── list-department-parents.ts # 部门父部门列表
│ ├── list-sub-departments.ts # 子部门列表
│ ├── list-department-users.ts # 部门用户列表
│ ├── list-department-user-ids.ts # 部门用户ID列表
│ ├── list-department-user-details.ts # 部门用户详情（分页）
│ ├── send-user-message.ts # 单聊消息发送
│ ├── send-group-message.ts # 群聊消息发送
│ ├── get-bot-list.ts # 群内机器人列表
│ ├── list-approval-instance-ids.ts # 审批实例 ID 列表
│ ├── get-approval-instance.ts # 审批实例详情
│ ├── list-user-initiated-approvals.ts # 用户发起审批列表
│ ├── list-user-cc-approvals.ts # 抄送用户审批列表
│ ├── list-user-todo-approvals.ts # 待处理审批列表
│ ├── list-user-done-approvals.ts # 已处理审批列表
│ ├── get-user-todo-count.ts # 待审批数量
│ ├── create-approval-instance.ts # 发起审批
│ ├── terminate-approval-instance.ts # 终止审批
│ ├── execute-approval-task.ts # 执行审批任务
│ ├── transfer-approval-task.ts # 转交审批任务
│ └── add-approval-comment.ts # 添加审批评论
├── types/
│ └── dingtalk.d.ts # 钉钉 SDK 类型定义
├── SKILL.md # Skill 文档
├── README.md
├── package.json
└── tsconfig.json
API 文档
用户管理
部门管理
消息与机器人
认证
OA审批
- 获取审批实例ID列表
- 获取单个审批实例详情
- 获取用户待审批数量
- 获取用户已发起审批列表
- 获取用户待处理审批列表
- 获取用户已处理审批列表
- 获取用户抄送审批列表
- 创建审批实例
- 撤销审批实例
- 执行审批操作
- 添加审批评论
许可证
MIT