Skip to main content
钉钉渠道通过官方 Stream 模式建立长连接接入，无需公网回调地址，本地或内网部署也能直接使用。目前钉钉渠道的实现支持：
  • 交互式卡片确认：智能体调用需要审批的工具时，在钉钉里以卡片形式请求确认，点击按钮即可批准或拒绝；
  • 流式回复：配置 AI 卡片模板后，回答在同一张卡片内逐步更新；未配置时回复以普通 Markdown 消息发出；
  • 多模态输入：接收用户发来的图片、文件、语音、视频与图文混排消息，交给智能体处理；
  • 主动发送：智能体可以查询通讯录与已知聊天，把消息、图片、文件发送到当前会话之外的用户或群。
接入分四步：在钉钉开放平台创建应用并拿到凭据，在卡片平台准备卡片模板，启动一个智能体服务承载渠道，最后在管理界面添加钉钉渠道。

​
前置条件

钉钉渠道依赖 dingtalk-stream，随 channel 可选依赖安装：
安装依赖

​
创建应用

在钉钉开放平台完成企业内部应用与机器人的创建配置。
1

创建企业内部应用

在开发者后台创建一个”企业内部应用”，填写名称与图标。
2

记录 Client ID 与 Client Secret

在应用的凭证与基础信息页，复制 Client ID（AppKey）与 Client Secret（AppSecret），稍后填入渠道配置。Client Secret 是机密，请妥善保管。
3

添加机器人能力

在”应用能力”中添加”机器人”，填写机器人名称与图标，机器人才能收发消息。
4

消息接收模式选择 Stream

在机器人配置页，把消息接收模式设为 Stream 模式，无需填写 HTTP 回调地址。
5

申请权限

在”权限管理”中申请：企业内机器人发送消息、卡片实例的创建与更新、媒体文件的上传与下载。若需要 ListUsers 工具按姓名搜索用户，再申请通讯录的用户搜索与个人信息读取权限。具体权限项以钉钉官方文档为准。
6

发布应用

发布应用版本，使其在企业内可用。之后即可把机器人加入群聊，或直接与它私聊。

​
准备卡片模板

钉钉的交互式卡片必须先在卡片平台建好模板，渠道运行时只负责填充模板变量。渠道用到两类模板，都是可选的，不配置则相应能力降级。 审批卡片模板用于工具确认。渠道下发卡片时填充以下变量： 模板中需要放置”同意”与”拒绝”两个回传按钮，并在按钮的回传参数（cardPrivateData.params）里带上 action 以及 toolCallId、chatId、agentId、sessionId、approverId。action 的取值：批准用 allow、approve、accept 或 agree，拒绝用 deny 或 reject。
未配置审批卡片模板时，需要确认的工具调用无法在钉钉里得到答复，SendMessage、SendImage、SendFile 三个主动发送工具也不会开放给智能体。
流式卡片模板用于流式回复，需要在模板中放置一个 AI 卡片流式组件，并把它的模板变量名填到渠道配置的 streaming_card_key（默认 content）。
钉钉对单次卡片更新的内容大小有限制。当回复增长到超出该限制时，渠道停止流式更新，改为把完整回答作为普通 Markdown 消息发出。

​
启动智能体服务

渠道运行在智能体服务之上。用 create_app 启动服务，并用 channels 参数声明允许接入的渠道类型。渠道依赖消息总线（message_bus），单机开发用 InMemoryMessageBus 即可，多进程或多节点部署再换成 RedisMessageBus。
启动承载渠道的智能体服务

​
添加渠道

在智能体服务的管理界面（参见示例前端 examples/web_ui）中，通过可视化表单添加渠道，无需手写配置。
1

新建渠道并选择钉钉

在渠道管理页新建一个渠道，平台类型选择”钉钉”。
2

填入凭据

把上一步拿到的 Client ID 与 Client Secret 填入凭据表单。
3

填入卡片模板 ID

把审批卡片与流式卡片的模板 ID 填入平台配置，二者都可留空。
4

配置路由规则

选择消息交给哪个智能体、会话如何划分。路由规则的含义见会话路由。
5

保存并启用

保存后启用渠道，服务立即建立与钉钉的 Stream 连接，机器人上线。把它加入群聊或发起私聊即可开始对话。
管理界面的操作对应一组 /channels 接口，需要以编程方式批量创建渠道时可直接调用，字段见本章 API 部分。

​
平台配置

钉钉渠道的平台专属字段：
路由匹配 chat_type 时，群聊的值为 group，私聊为 private。

​
智能体工具

配置好审批卡片模板后，渠道会向智能体额外提供一组钉钉工具，用于把消息发到当前会话之外的用户或群。发送目标由查询类工具返回，形如 user:<staffId> 或 group:<openConversationId>，智能体原样传给发送类工具即可。
钉钉的企业内部机器人无法枚举自己加入的全部群聊，因此 ListConversations 只能列出当前进程启动以来收到过消息的聊天。想让某个群出现在结果里，先在群内给机器人发一条消息。

​
验证与排查

  • 在管理界面查看渠道状态，或调用 GET /channels/{id}/status 确认 Stream 连接已建立。
  • 若机器人在群里不响应，先确认 only_at_reply 与 @ 行为是否符合预期，再检查发送消息权限是否已申请并随版本发布。
  • 若机器人完全不上线，检查 Client ID / Client Secret 是否正确、消息接收模式是否设为 Stream。
  • 若点击卡片按钮没有反应，检查按钮回传参数是否带上了 action 与上表中的各个标识字段。
  • 若附件发送失败，检查文件是否超过 max_media_bytes，以及扩展名是否在钉钉支持的范围内。

​
延伸阅读

会话路由

把不同的群路由到不同的智能体。

飞书

用同一套流程接入飞书。