IM 接入

IM 接入把设备智能体连接到飞书、钉钉、Slack、Discord 或 Telegram。用户可以向机器人查询状态、控制设备，也可以让设备智能体主动把告警、查询结果或业务报告发送到指定会话。先创建机器人或应用，再到 设置 → IM 通道 配置并启用。

适合场景

• 团队成员已经在飞书、钉钉或 Slack 中协作，希望直接在群里查询和控制设备。
• 设备需要一个远程操作入口，但不想为每个用户单独开发 App 或管理后台。
• 需要把设备告警、状态查询、控制命令放到同一个聊天上下文里。
• 希望设备异常或自动化完成后，主动通知负责处理的群组或频道。
• 希望通过白名单限制哪些平台用户可以访问设备智能体。

接入流程

1. 在第三方平台创建机器人或应用。
2. 开启消息接收能力，并记录平台分配的凭证。
3. 打开设备智能体控制台的 设置 → IM 通道。
4. 选择对应平台，配置凭证和来源白名单，然后启用通道。平台部署中的凭据由管理员配置，在页面确认配置状态。
5. 保存配置。本地部署重启服务后生效；平台部署联系管理员重启相关服务，再验证配置生效。
6. 在第三方平台中私聊机器人，或在群聊中 @ 机器人发起对话。

本地 .env 中的同名变量会在启动时覆盖页面配置；配置优先级和重启要求见配置生效规则。

第三方平台需要准备什么

平台	平台侧准备	控制台中填写	用户如何触发
飞书	企业自建应用、机器人能力、长连接事件订阅	App ID、App Secret，可选 Encrypt Key 和 Verification Token	私聊机器人，或在群聊中 @ 机器人
钉钉	钉钉应用、机器人能力、Stream 模式	Client ID、Client Secret	私聊机器人，或在群聊中 @ 机器人
Slack	Slack App、Socket Mode、Bot Token、App Token	Bot Token、App Token，可选 Signing Secret	在频道中 @ App，或给 App 发私信
Discord	Discord Application、Bot、Message Content Intent	Bot Token	私聊机器人，或在服务器频道中 @ 机器人
Telegram	通过 @BotFather 创建 Bot	Bot Token	私聊机器人、群聊 @ 机器人，或回复机器人消息

在控制台填写配置

打开 设置 → IM 通道，选择需要接入的平台。每个平台的凭证不同，但基础字段一致：

字段	用途
启用	是否启动当前 IM 通道
白名单	允许访问设备智能体的平台用户 ID，使用英文逗号分隔；留空表示不限制

白名单需要填写平台用户 ID，而不是昵称或显示名：

通道	用户 ID
飞书	open_id，例如 ou_xxx
钉钉	员工 ID 或 senderStaffId
Discord	用户 Snowflake ID
Telegram	用户数字 ID
Slack	用户 ID，例如 U01234567

如果暂时不知道用户 ID，可以先留空，发送一条测试消息后从服务日志中查看发送者 ID，再收紧白名单。

验证接入

配置生效后，先在第三方平台中发送一条简单消息：

当前有哪些设备在线？

如果已经有设备上线，可以继续测试查询和控制：

查看 thermostat-01 的当前状态。

把 thermostat-01 的目标温度设置为 24 度。

私聊机器人时通常可以直接发送消息；群聊或频道中通常需要 @ 机器人，或回复机器人消息。设备智能体处理完成后，会把回答发送回同一个会话。

主动发送通知

主动通知适合告警提醒、巡检结果和业务报告。可以在对话中明确要求发送，也可以把 发送 IM 消息 加入 工作流，在设备上报匹配条件后发送。

发送前确认：

1. 对应 IM 通道已启用，机器人拥有目标会话或频道的发送权限。
2. 机器人已加入目标群组或频道，或已与目标用户建立可用会话。
3. 请求或工作流中写明通道、发送目标和消息内容。

来源白名单 控制哪些用户可以向设备智能体发起请求；发送目标 决定消息送往哪里，两者的 ID 格式可能不同。例如飞书白名单使用用户 open_id，主动发送使用会话 chat_id。

通道	发送目标格式	示例
飞书	会话 chat_id	oc_xxx
钉钉	指定群聊或用户的 JSON；群聊使用 openConversationId，用户使用员工 ID	{"kind":"group","id":"群会话ID"} 或 {"kind":"user","id":"员工ID"}
Slack	包含频道 ID 的 JSON；回复指定话题时可加入 threadTs	{"channelId":"C01234567"}
Discord	目标频道 ID	123456789012345678
Telegram	目标聊天 ID；群聊 ID 可能为负数	-1001234567890

从平台管理界面或接收消息的日志中获取目标标识，勿使用群名称、昵称或白名单中的用户 ID。

例如，在已启用飞书通道并取得目标 chat_id 后：

查询当前设备智能体的在线设备，把在线数量和离线设备列表整理成简短报告，发送到飞书会话 oc_xxx。

把示例 ID 换成实际目标。如果出现发送确认，先核对目标和内容，再确认发送。执行完成后，到第三方平台检查消息是否到达。工作流发送失败时，检查运行结果、通道状态和目标发送权限。

对话与消息支持

在群聊中写明设备对象和操作目标，避免依赖其他会话的上下文。消息触发方式与来源限制见在控制台填写配置和验证接入。

飞书支持文本、富文本、图片和语音转文字，其他通道以文本消息为主。IM 消息支持与设备端多媒体接入不同；设备端接入见语音交互、摄像头与视觉识别和模拟显示器。

和其他对话入口的区别

入口	作用
控制台对话界面	内置入口，适合创建、调试、选择设备、查看状态和人工控制。详见 使用设备智能体。
HTTP 对话 API	面向自建 Web、App 或业务系统，适合把设备智能体嵌入已有产品。
IM 接入	面向第三方聊天平台，适合让用户在已有协作工具中使用设备智能体。
设备端语音和视觉	面向带麦克风、摄像头或屏幕的真实设备，通过设备 SDK 和多媒体能力接入。