IM 接入

IM 接入把设备智能体连接到飞书、钉钉、Slack、Discord 或 Telegram，用户可向机器人查询状态、下发命令或询问设备能力；各通道共用同一路径：先创建机器人或应用，再到 设置 → IM 通道 填写凭证并启用。

适合场景

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

接入流程

1. 在第三方平台创建机器人或应用。
2. 开启消息接收能力，并记录平台分配的凭证。
3. 打开设备智能体控制台的 设置 → IM 通道。
4. 选择对应平台，填写凭证，按需配置白名单，然后启用通道。
5. 保存配置并重启服务。
6. 在第三方平台中私聊机器人，或在群聊中 @ 机器人发起对话。

保存后的 IM 配置会写入本地配置；.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 通道都会把平台消息转换为一次设备智能体会话。消息中的文本会进入设备智能体；平台用户 ID、会话 ID、群聊或频道信息会用于回复原会话和检查白名单。

不同平台的多媒体能力不完全一致。飞书当前支持文本、富文本、图片和语音转文字；其他通道以文本消息为主，图片、语音和文件消息不会自动等同于完整的视觉或语音接入。需要设备端语音、摄像头或模拟显示器能力时，请参考 语音交互、摄像头与视觉识别 和 模拟显示器。

和其他对话入口的区别

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