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_ 密鑰,以避免產生計費。