Telegram

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

使用方式

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

在 Telegram 中创建机器人

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

群聊默认启用隐私模式，可先用回复机器人消息验证接入。若需要普通 @bot_username 文本触发，在 @BotFather 中通过 /setprivacy 关闭隐私模式，再重新将机器人加入群。关闭后机器人会收到更多群消息，Device Agent 仍只处理 @ 或回复机器人的文本。

在控制台填写配置

打开 设置 → 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。