Skip to main content
@hitheo/telegram 包可将 Theo 作为机器人接入 Telegram。用户向你的机器人发送消息,Theo 通过完整的编排流程处理响应,适配器再通过 Bot API 回复。
Theo 从不托管你的机器人。你需要通过 @BotFather 创建机器人并持有令牌,并将本适配器部署在你自己的基础设施上;Theo 只处理适配器转发过来的补全流量。这样一来,每一条消息、Webhook URL 和凭证都始终掌握在你手中。

前提条件

  1. 从 @BotFather 获取的 Telegram 机器人令牌
  2. 一个 Theo API 密钥(theo_sk_...)

安装

快速设置

createTelegramHandler 返回一个异步函数,用于处理单条 Telegram Webhook 更新。你可以将它接入任意 HTTP 框架——Express、Next.js 路由处理器、Cloudflare Workers、AWS Lambda 等。

工作原理

  1. 用户向你的 Telegram 机器人发送一条消息
  2. Telegram 将该更新以 POST 方式推送到你的 Webhook URL
  3. 适配器校验 X-Telegram-Bot-Api-Secret-Token 请求头(当配置了 secretToken 时)
  4. 适配器将文本(以及任何图片/文档附件)转发至 POST /api/v1/completions,并复用与该会话关联的 conversation_id
  5. Theo 通过完整流程(分类、技能、代理循环)处理该请求
  6. 响应被发回该 Telegram 聊天,如有需要会拆分为多条消息发送

处理器配置

内置命令

适配器会自行处理以下三个命令(不会调用 Theo): 其他任何 /foo 命令都会返回一条简短的“未知命令”回复。

附件

消息中附带的照片(以及图片类文档)会在适配器内部下载,并以 base64 图片数据的形式转发给 Theo——适配器绝不会把 Telegram 的文件 URL 传给 Theo。这样可以确保机器人令牌始终留在你的部署环境内。
请始终使用最新版本的 @hitheo/telegram。如果你还在使用 ≤0.1.3 版本,请升级到 ^0.1.4,并在升级过程中通过 @BotFather 轮换机器人令牌。
语音和音频消息默认会被忽略,除非你设置了 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 —— 自托管
开发阶段请使用 theo_sk_test_ 密钥,以避免产生计费。