DingTalk API 技能

用于调用钉钉开放平台 API 的技能，提供完整的钉钉企业级集成功能，包括传统API调用和Stream模式事件推送。

核心功能模块

用户与组织管理

- 用户搜索、详情查询、手机号/unionid查询
部门管理（搜索、详情、子部门、用户列表、父部门）
企业员工统计、组织架构映射
离职记录查询、未登录用户列表

消息与机器人

- 机器人单聊消息发送
机器人群聊消息发送
群内机器人列表查询
消息内容格式化与发送

Stream模式事件推送（推荐）

- 实时消息接收：通过WebSocket长连接接收钉钉事件
多会话隔离：为每个用户/群聊成员创建独立的AI会话
上下文保持：每个会话保持完整的对话历史和个性化记忆
自动回复路由：AI生成的回复直接通过钉钉API发送，避免多通道冲突

OA审批管理

- 审批实例查询、详情获取
发起、终止、执行、转交审批任务
审批评论管理、待办数量统计

API版本支持

传统服务端API (兼容)

- 用户管理：用户查询、部门管理
消息发送：机器人消息
特点：稳定可靠、广泛使用、向后兼容

Stream模式API (推荐)

- 事件推送：实时接收钉钉消息和事件
长连接：基于WebSocket的持久连接
高并发：支持大量用户同时对话
低延迟：消息处理延迟毫秒级

权限说明

企业内部应用

- 支持所有功能：用户管理、消息、Stream模式、OA审批
权限配置：在钉钉开发者后台申请相应权限
认证方式：使用AppKey/AppSecret获取access_token
Stream配置：需在开发者后台配置事件订阅和回调URL

第三方企业应用

- 部分功能支持：用户管理、消息
认证方式：OAuth2.0授权流程
Stream模式：不支持

第三方个人应用

- 功能受限：仅支持基础用户查询
不支持：消息发送、Stream模式

前置要求

传统API模式

- 已设置环境变量 DINGTALKAPPKEY 和 DINGTALKAPPSECRET
钉钉应用已创建并拥有相应 API 权限
对于企业内部应用，确保在钉钉管理后台已授权所需权限

Stream模式（推荐）

- 企业内部应用（必须）
公网可访问的HTTPS服务器（用于事件回调）
钉钉开发者后台已配置Stream模式事件订阅
Python 3.8+ 环境（用于运行Stream Bridge）

环境变量配置

bash

传统API和Stream模式都需要

export DINGTALKAPPKEY=
export DINGTALKAPPSECRET=

Stream模式额外配置（可选）

export DINGTALKSTREAMLOG_LEVEL=INFO export DINGTALKSESSIONMEMORY_DIR=./memory

使用示例

1. 传统API调用

查询用户详情

bash npx ts-node scripts/get-user.ts [--debug]

发送单聊消息

bash npx ts-node scripts/send-user-message.ts <消息内容> [--debug]

获取部门用户列表

bash npx ts-node scripts/list-department-users.ts [--debug]

搜索用户

bash npx ts-node scripts/search-user.ts [--debug]

2. Stream模式部署（推荐）

启动Stream Bridge

bash

创建虚拟环境

python3 -m venv dingtalk_venv source dingtalk_venv/bin/activate pip install dingtalk-stream

启动Stream服务

./startdingtalkstream.sh

会话管理特性

- 私聊会话：dingtalkprivate{userid} - 每个用户独立会话
群聊会话：dingtalkgroup{groupid}{userid} - 群聊中每个用户独立会话
记忆持久化：会话记忆保存在 memory/ 目录下
自动清理：24小时无活动的会话自动清理

错误处理

所有脚本在错误时返回统一格式：

json
{
success: false,
error: {
code: ERROR_CODE,
message: 错误描述
}
}

常见错误码：

- MISSINGCREDENTIALS - 未设置环境变量
INVALIDARGUMENTS - 参数不足
AUTHFAILED - accesstoken 获取失败
PERMISSIONDENIED - 权限不足
UNKNOWNERROR - API 调用异常
STREAMCONNECTIONFAILED - Stream连接失败

最佳实践

1. 权限最小化：只申请必要的API权限
错误处理：始终检查API响应的errcode
调试模式：使用--debug参数查看详细请求/响应
批量操作：对于大量数据，使用批量API接口
Stream模式优先：实时交互场景优先使用Stream模式
会话隔离：确保不同用户的对话上下文完全隔离
频率控制：遵守钉钉API调用频率限制

安全注意事项

- 不要在代码中硬编码AppKey/AppSecret
使用环境变量或安全的配置管理
敏感操作（如删除、修改）需要二次确认
遵循钉钉的安全最佳实践指南
Stream模式安全：确保回调URL使用HTTPS，验证事件签名
数据隔离：不同用户的会话数据完全隔离，符合企业安全要求

架构优势

多会话隔离架构

- 用户识别：准确识别私聊和群聊中的不同用户
上下文保持：每个会话保持完整的对话历史
个性化记忆：支持用户偏好和历史记录的持久化
资源管理：自动清理过期会话，避免资源泄露

回复路由优化

- 通道隔离：钉钉回复只通过钉钉API，避免触发其他通道
性能优化：异步处理，支持高并发
可靠性：结果文件机制确保消息不丢失
错误恢复：网络错误自动重试，保证消息送达

项目结构

dingtalk-api/
├── scripts/ # 传统API脚本
│ ├── *.ts # 各类API调用脚本
├── stream/ # Stream模式相关文件
│ ├── dingtalkstreambridge.py # Stream Bridge主程序
│ ├── dingtalksessionmanager.py # 会话管理器
│ ├── dingtalkreplytool.py # 钉钉回复工具
│ └── *.sh # 启动/停止脚本
├── memory/ # 会话记忆文件（运行时生成）
├── types/ # TypeScript类型定义
├── SKILL.md # 技能文档
├── README.md # 详细使用说明
└── package.json # 依赖配置

dingtalk-api钉钉API

dingtalk-api

DingTalk API Skill

核心功能模块

用户与组织管理

消息与机器人

Stream模式事件推送（推荐）

OA审批管理

API版本支持

传统服务端API (兼容)

Stream模式API (推荐)

权限说明

企业内部应用

第三方企业应用

第三方个人应用

前置要求

传统API模式

Stream模式（推荐）

环境变量配置

使用示例

1. 传统API调用

查询用户详情

发送单聊消息

获取部门用户列表

搜索用户

2. Stream模式部署（推荐）

启动Stream Bridge

会话管理特性

错误处理

最佳实践

安全注意事项

架构优势

多会话隔离架构

回复路由优化

项目结构

DingTalk API 技能

核心功能模块

用户与组织管理

消息与机器人

Stream模式事件推送（推荐）

OA审批管理

API版本支持

传统服务端API (兼容)

Stream模式API (推荐)

权限说明

企业内部应用

第三方企业应用

第三方个人应用

前置要求

传统API模式

Stream模式（推荐）

环境变量配置

传统API和Stream模式都需要

Stream模式额外配置（可选）

使用示例

1. 传统API调用

查询用户详情

发送单聊消息

获取部门用户列表

搜索用户

2. Stream模式部署（推荐）

启动Stream Bridge

创建虚拟环境

启动Stream服务

会话管理特性

错误处理

最佳实践

安全注意事项

架构优势

多会话隔离架构

回复路由优化

项目结构

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement