Dingtalk Api — Dingtalk API

DingTalk API 技能

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

核心功能模块 用户与组织管理 用户搜索、详情查询、手机号/unionid查询 部门管理（搜索、详情、子部门、用户列表、父部门） 企业员工统计、组织架构映射 离职记录查询、未登录用户列表 消息与机器人 机器人单聊消息发送 机器人群聊消息发送 群内机器人列表查询 消息内容格式化与发送 流模式事件推送（推荐） 实时消息接收：通过网页Socket长连接接收钉钉事件 多会话隔离：为每个用户/群聊成员创建独立的AI会话 上下文保持：每个会话保持完整的对话历史和个性化记忆 自动回复路由：AI生成的回复直接通过钉钉API发送，避免多通道冲突 OA审批管理 审批实例查询、详情获取 发起、终止、执行、转交审批任务 审批评论管理、待办数量统计 API版本支持 传统服务端API (兼容) 用户管理：用户查询、部门管理 消息发送：机器人消息 特点：稳定可靠、广泛使用、向后兼容 流模式API (推荐) 事件推送：实时接收钉钉消息和事件 长连接：基于网页Socket的持久连接 高并发：支持大量用户同时对话 低延迟：消息处理延迟毫秒级 权限说明 企业内部应用 支持所有功能：用户管理、消息、流模式、OA审批 权限配置：在钉钉开发者后台申请相应权限 认证方式：使用应用Key/应用Secret获取访问_令牌 流配置：需在开发者后台配置事件订阅和回调URL 第三方企业应用 部分功能支持：用户管理、消息 认证方式：OAuth2.0授权流程 流模式：不支持 第三方个人应用 功能受限：仅支持基础用户查询 不支持：消息发送、流模式 前置要求 传统API模式 已设置环境变量 DINGTALK_应用_KEY 和 DINGTALK_应用_SECRET 钉钉应用已创建并拥有相应 API 权限 对于企业内部应用，确保在钉钉管理后台已授权所需权限 流模式（推荐） 企业内部应用（必须） 公网可访问的HTTPS服务器（用于事件回调） 钉钉开发者后台已配置流模式事件订阅 Python 3.8+ 环境（用于运行流 Bridge） 环境变量配置 # 传统API和流模式都需要 导出 DINGTALK_应用_KEY="" 导出 DINGTALK_应用_SECRET=""

# 流模式额外配置（可选） 导出 DINGTALK_流_记录_LEVEL="信息" 导出 DINGTALK_会话_MEMORY_DIR="./memory"

使用示例

• 传统API调用

查询用户详情 npx ts-node scripts/获取-user.ts "" [--调试]

发送单聊消息 npx ts-node scripts/发送-user-message.ts "" "" "<消息内容>" [--调试]

获取部门用户列表 npx ts-node scripts/列出-department-users.ts "" [--调试]

搜索用户 npx ts-node scripts/搜索-user.ts "" [--调试]

• 流模式部署（推荐）

启动流 Bridge # 创建虚拟环境 python3 -m venv dingtalk_venv source dingtalk_venv/bin/activate pip 安装 dingtalk-流

# 启动流服务 ./启动_dingtalk_流.sh

会话管理特性 私聊会话：dingtalk_private_{user_id} - 每个用户独立会话 群聊会话：dingtalk_group_{group_id}_{user_id} - 群聊中每个用户独立会话 记忆持久化：会话记忆保存在 memory/ 目录下 自动清理：24小时无活动的会话自动清理 错误处理

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

{ "成功": false, "error": { "code": "ERROR_CODE", "message": "错误描述" } }

常见错误码：

MISSING_凭证S - 未设置环境变量 INVALID_ARGUMENTS - 参数不足 AUTH_FAILED - 访问_令牌 获取失败 权限_DENIED - 权限不足 UNKNOWN_ERROR - API 调用异常 流_CONNECTION_FAILED - 流连接失败 最佳实践 权限最小化：只申请必要的API权限 错误处理：始终检查API响应的errcode 调试模式：使用--调试参数查看详细请求/响应 批量操作：对于大量数据，使用批量API接口 流模式优先：实时交互场景优先使用流模式 会话隔离：确保不同用户的对话上下文完全隔离 频率控制：遵守钉钉API调用频率限制 安全注意事项 不要在代码中硬编码应用Key/应用Secret 使用环境变量或安全的配置管理 敏感操作（如删除、修改）需要二次确认 遵循钉钉的安全最佳实践指南 流模式安全：确保回调URL使用HTTPS，验证事件签名 数据隔离：不同用户的会话数据完全隔离，符合企业安全要求 架构优势 多会话隔离架构 用户识别：准确识别私聊和群聊中的不同用户 上下文保持：每个会话保持完整的对话历史 个性化记忆：支持用户偏好和历史记录的持久化 资源管理：自动清理过期会话，避免资源泄露 回复路由优化 通道隔离：钉钉回复只通过钉钉API，避免触发其他通道 性能优化：异步处理，支持高并发 可靠性：结果文件机制确保消息不丢失 错误恢复：网络错误自动重试，保证消息送达 项目结构 dingtalk-API/ ├── scripts/ # 传统API脚本 │ ├── .ts # 各类API调用脚本 ├── 流/ # 流模式相关文件 │ ├── dingtalk_流_bridge.py # 流 Bridge主程序 │ ├── dingtalk_会话_管理器.py # 会话管理器 │ ├── dingtalk_reply_工具.py # 钉钉回复工具 │ └── .sh # 启动/停止脚本 ├── memory/ # 会话记忆文件（运行时生成） ├── types/ # TypeScript类型定义 ├── 技能.md # 技能文档 ├── README.md # 详细使用说明 └── package.json # 依赖配置