# IM 接入

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

## 适合场景

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

## 接入流程

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

保存后的 IM 配置会写入本地配置；`.env` 中的同名变量会在启动时覆盖它。完整配置入口见 [配置](../operate-reference/configuration.md)。

## 第三方平台需要准备什么

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

## 在控制台填写配置

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

![IM 通道配置](../images/docs/integrations/im/zh/01-im-channel-config.png)

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

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

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

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

## 验证接入

重启服务后，先在平台中发送一条简单消息：

```text
当前有哪些设备在线？
```

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

```text
查看 thermostat-01 的当前状态。
```

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

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

## 消息如何进入设备智能体

每个 IM 通道都会把平台消息转换为一次设备智能体会话。消息中的文本会进入设备智能体；平台用户 ID、会话 ID、群聊或频道信息会用于回复原会话和检查白名单。

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

## 和其他对话入口的区别

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