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

​
前置条件

钉钉渠道依赖 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

发布应用

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

​
启动智能体服务

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

​
添加渠道

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

新建渠道并选择钉钉

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

填入凭据

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

配置路由规则

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

保存并启用

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

​
平台配置

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

​
自定义卡片

钉钉渠道会下发两种卡片：智能体调用需要审批的工具时下发审批卡片，回复过程中逐步更新的内容承载在流式卡片上。两者都使用钉钉内置的公共模板，接入时不需要做任何卡片相关的配置。 内置模板的外观是固定的：排版、按钮的配色与宽度都无法调整，也去不掉卡片自带的反馈区。想改这些，就到卡片平台建一个自己的模板，把模板 ID 填进渠道配置对应的字段： 换成自己的模板后渠道代码无需改动，但模板需要声明渠道会填充的变量，两种卡片各自的要求见下。

​
审批卡片

渠道下发审批卡片时填充以下变量，模板按需绑定： name、input、created_at 直接取自智能体的工具调用记录（ToolCallBlock 的同名字段），因此模板作者不需要学习一套新的字段名。status 是卡片自身的状态：下发时为 pending，用户做出决定后渠道把它更新为 approved 或 denied，模板可以用它控制按钮与结果文案的显示。 模板中放置”同意”与”拒绝”两个回传按钮，在按钮的回传参数（cardPrivateData.params）里带上 action： 按钮只需要回传 action，不必携带任何路由信息。渠道用建卡时指定的 outTrackId 定位对应的工具调用，用回调自带的会话信息定位聊天。
仓库里提供了一份可直接导入的模板：assets/dingtalk/tool_approval_card.json。在卡片平台新建模板时导入该文件，发布后把模板 ID 填入 approval_card_template_id。忘记发布会导致建卡失败并返回 param.templateUnpublished。
把 approval_card_template_id 置空会关闭审批卡片。此时需要确认的工具调用无法在钉钉里得到答复，渠道会在聊天中提示模板为空，会话停在等待确认的状态。

​
流式卡片

流式卡片的模板里要有一个 AI 卡片流式组件，渠道把逐步生成的 Markdown 写进它。把该组件的变量名填到渠道配置的 streaming_card_key，使用内置模板时这个名字是 content。

​
智能体工具

渠道会向智能体额外提供一组钉钉工具，用于把消息发到当前会话之外的用户或群。发送目标由查询类工具返回，形如 user:<staffId> 或 group:<openConversationId>，智能体原样传给发送类工具即可。
钉钉的企业内部机器人无法枚举自己加入的全部群聊，而且回答这次调用的进程并不是持有机器人连接的那个，因此在分离部署下 ListConversations 的结果始终为空。请把空结果当作常态，直接向用户询问目标。

​
验证与排查

  • 在管理界面查看渠道状态，或调用 GET /channels/{id}/status 确认 Stream 连接已建立。
  • 若机器人在群里不响应，先确认 only_at_reply 与 @ 行为是否符合预期，再检查发送消息权限是否已申请并随版本发布。
  • 若机器人完全不上线，检查 Client ID / Client Secret 是否正确、消息接收模式是否设为 Stream。
  • 若点击卡片按钮没有反应，检查按钮是否配成了回传请求，以及回传参数里的 action 取值是否在上表中。
  • 若群聊正常而私聊发送失败并返回 chatbotId.notAllow.sendOTO，说明机器人的单聊消息能力未启用，在开发者后台启用机器人并发布应用版本。
  • 若附件发送失败，检查文件是否超过 max_media_bytes，以及扩展名是否在钉钉支持的范围内。

​
延伸阅读

会话路由

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

飞书

用同一套流程接入飞书。