@hitheo/telegram 包可将 Theo 作为机器人接入 Telegram。用户向你的机器人发送消息,Theo 通过完整的编排流程处理响应,适配器再通过 Bot API 回复。
Theo 从不托管你的机器人。你需要通过 @BotFather 创建机器人并持有令牌,并将本适配器部署在你自己的基础设施上;Theo 只处理适配器转发过来的补全流量。这样一来,每一条消息、Webhook URL 和凭证都始终掌握在你手中。
前提条件
- 从 @BotFather 获取的 Telegram 机器人令牌
- 一个 Theo API 密钥(
theo_sk_...)
安装
快速设置
createTelegramHandler 返回一个异步函数,用于处理单条 Telegram Webhook 更新。你可以将它接入任意 HTTP 框架——Express、Next.js 路由处理器、Cloudflare Workers、AWS Lambda 等。
工作原理
- 用户向你的 Telegram 机器人发送一条消息
- Telegram 将该更新以 POST 方式推送到你的 Webhook URL
- 适配器校验
X-Telegram-Bot-Api-Secret-Token请求头(当配置了secretToken时) - 适配器将文本(以及任何图片/文档附件)转发至
POST /api/v1/completions,并复用与该会话关联的conversation_id - Theo 通过完整流程(分类、技能、代理循环)处理该请求
- 响应被发回该 Telegram 聊天,如有需要会拆分为多条消息发送
处理器配置
内置命令
适配器会自行处理以下三个命令(不会调用 Theo):
其他任何
/foo 命令都会返回一条简短的“未知命令”回复。
附件
消息中附带的照片(以及图片类文档)会在适配器内部下载,并以 base64 图片数据的形式转发给 Theo——适配器绝不会把 Telegram 的文件 URL 传给 Theo。这样可以确保机器人令牌始终留在你的部署环境内。 语音和音频消息默认会被忽略,除非你设置了enableVoice: true。启用后,适配器会下载语音片段,通过 Theo 语音转文本进行处理,并将转录文本以文字形式附加到提示词中。语音不会作为附件发送——Theo 的补全端点只接受图片附件。
设置 Webhook
向 Telegram 注册你的 Webhook URL,并附上secret_token:
跨实例保持会话持久化
默认的ConversationStore 是一个进程内的 Map——这对单个长期运行的服务器没问题,但不适用于无服务器场景(每次调用都是全新进程)。请提供你自己的存储实现:
部署
可以部署为任意 Node.js HTTP 服务器。生产环境建议:- Railway / Render / Fly.io —— 对基于 Webhook 的机器人来说最简单
- Vercel / Cloudflare Workers —— 无服务器(每条消息对应一次调用);请配合远程
conversationStore使用 - Docker + PM2 —— 自托管
