@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 —— 自託管
