使用 grammY 整合 Telegram Bot API

開發機器人最煩人的地方，通常不是邏輯本身，而是要處理各種底層細節。像是手動封裝 fetch 和 FormData 來傳送媒體檔案，或是為了處理 long-polling 和 webhook 的切換搞到頭大。如果你也遇過 API 限制或連線不穩定的問題，你一定知道維護這些程式碼有多累。

我們現在將 Telegram 的整合全面轉向 grammY。這是一個以 TypeScript 為核心的框架，內建了處理媒體、錯誤和流量限制的工具，讓你不用再自己造輪子，直接使用高品質的 Bot API 客戶端。

需要準備的東西

在開始之前，請確保你擁有以下設定參數（依你的環境需求而定）：

• channels.telegram.botToken: 你的 Telegram Bot Token
• channels.telegram.dmPolicy: 私訊處理政策
• channels.telegram.groups: 群組設定（包含白名單與提及預設值）
• channels.telegram.allowFrom 與 channels.telegram.groupAllowFrom: 允許的使用者或群組
• channels.telegram.mediaMaxMb: 媒體檔案大小上限
• channels.telegram.proxy: 代理伺服器位址
• channels.telegram.webhookUrl 與 channels.telegram.webhookSecret: Webhook 模式必備設定
• channels.telegram.streamMode: 是否啟用 Bot API 9.3+ 的草稿串流功能

快速開始

跟著以下步驟，在 5 分鐘內完成 grammY 的配置：

1. 填入 Bot Token: 在你的設定檔案中貼上 botToken。這是啟動 Gateway 的唯一必要條件。
2. 啟動 Gateway: 系統會透過 monitorTelegramProvider 自動建立一個 grammY Bot 實例。它會處理訊息過濾，並透過 getFile 與 download 幫你處理好媒體檔案下載。
3. 設定連線模式:
   • 如果你填寫了 webhookUrl 和 webhookSecret，系統會啟動 Webhook 模式並透過 webhook.ts 處理回傳。
   • 若未設定 Webhook 資訊，系統會自動降級為 long-poll 模式，適合本地開發。
4. 檢查 Session 路由: 系統會自動管理對話。私訊會導向 Agent 的主 Session (agent:<agentId>:<mainKey>)，而群組訊息則會路由至獨立的群組路徑。

疑難排解

• 遇到 Bot API 429 錯誤: 系統預設啟用了 grammY throttler 插件。如果你仍然遇到流量限制問題，請檢查是否有短時間內大量發送訊息的行為。
• Webhook 無法正常運作: 請確認你的伺服器可以接收外部請求。目前 Webhook 的監聽連接埠固定為 8787，除非你自行修改 Gateway 的底層串接。
• 代理伺服器連線失敗: 如果你設定了 channels.telegram.proxy，系統會透過 undici.ProxyAgent 進行連線，請確保你的代理伺服器支援此協定。
• 串流模式沒反應: channels.telegram.streamMode 僅支援 Bot API 9.3+ 版本，且目前僅在私訊的主題聊天中生效。

如果你在設定過程中遇到任何問題，可以詢問 AI Setup Assistant。

下一步

• 了解 webhook-set.ts 如何包裝 setWebhook 與 deleteWebhook API
• 深入查看 Gateway 如何透過 sendMessage 與 sendPhoto 等方法 deliver 訊息助器