# Telegram

Telegram 接入使用 Bot API 长轮询，用户可私聊机器人、在群聊中 @ 机器人或回复机器人消息来查询和控制设备；图片、语音和文件消息会作为提示接收，但不会替代完整的视觉或语音接入。

## 使用方式

| 方式 | 触发方式 | 说明 |
| --- | --- | --- |
| 私聊机器人 | 直接向机器人发送文本 | 适合个人远程查询设备状态、下发控制命令。 |
| 群聊 @ 机器人 | 在群里输入 `@bot_username` 加消息 | 适合多人协作场景。没有 @ 机器人时，群消息不会触发设备智能体。 |
| 回复机器人消息 | 直接回复机器人上一条消息 | 适合在群聊里继续同一个话题，不需要每次都 @。 |
| 图片、语音和文件 | 发送媒体消息，可附带说明文字 | 当前会作为带提示的消息进入通道；完整视觉、语音交互请使用对应设备接入能力。 |

## 在 Telegram 中创建机器人

1. 在 Telegram 中打开官方 `@BotFather`。
2. 发送 `/newbot` 创建机器人。
3. 按提示设置 bot name 和 username。
4. 复制 Bot Token。
5. 如果需要在群里使用，把机器人加入目标群。

## 在控制台填写配置

打开 **设置 → IM 通道 → Telegram**，填写以下字段：

| 字段 | `.env` | 说明 |
| --- | --- | --- |
| 启用 | `TELEGRAM_ENABLED` | 是否启动 Telegram 通道 |
| Bot Token | `TELEGRAM_BOT_TOKEN` | `@BotFather` 生成的 token |
| 白名单 | `TELEGRAM_ALLOW_FROM` | 可选，允许访问的 Telegram 用户数字 ID |

也可以在 `.env` 中配置：

```bash
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=123456:ABC-...
TELEGRAM_ALLOW_FROM=123456789,987654321
```

保存后重启服务，配置才会生效。

## 验证接入

1. 确认服务已重启。
2. 日志中出现 `Telegram: enabled` 和 `Bot started (long polling)`。
3. 私聊机器人发送消息。
4. 在群里 @ 机器人，或回复机器人消息。
5. 如果启用了白名单，确认发送者数字 ID 已写入白名单。

群聊中如果没有 @ 机器人，也没有回复机器人消息，设备智能体不会处理这条消息。

## 常见检查项

- 私聊无响应：确认 Bot Token 正确，且服务能访问 Telegram Bot API。
- 群聊无响应：确认 @ 了机器人，或直接回复机器人消息。
- 白名单后无响应：确认填写的是 Telegram 用户数字 ID。