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 中配置：

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。