Telegram Bot 接入
把 Multica AI 代理接入你自己的 Telegram Bot，支援私聊、群聊 @、forum topic 和 /issue。
Multica 使用你透過 Telegram 官方 @BotFather 建立的 Bot。一個 Bot 對應一個 Multica AI 代理；需要多個獨立 Bot 身份時，為每個 AI 代理分別建立。
開始前
- 連線操作需要工作區 owner 或 admin 權限。
- API 伺服器必須能夠訪問
https://api.telegram.org。 - 你需要 @BotFather 簽發的 Bot token；它等同於密碼。
連線 Bot
建立 Bot
- 開啟 @BotFather，傳送
/newbot。 - 設定顯示名稱和一個以
bot結尾的使用者名稱。 - 複製 HTTP API token。
- 預設保持 Group Privacy 開啟，這是可見範圍最小的配置：Telegram 只會把命令、明確的 @ 和對 Bot 訊息的回覆投遞給 Bot。也可以關閉它，讓 Bot 把群裡周圍的討論作為上下文，代價是 Bot 會收到群裡的每一條訊息，詳見Group Privacy 決定 Bot 能看到哪些訊息。
不要把 token 發到任務、聊天、日誌或程式碼倉庫。若已洩露，請在 @BotFather 中撤銷，再用替換後的 token 重新連線。
連線到 AI 代理
- 在 Multica 開啟 AI 代理，選擇目標 AI 代理並進入 整合。
- 點選 連線 Telegram。
- 貼上 Bot token，然後點選 連線。
Multica 會實時請求 Telegram 驗證 Bot，檢查是否存在與長輪詢衝突的 webhook，加密儲存 token，並啟動一條受監督的 getUpdates 連線。一個 Bot 若已連線到其他 AI 代理或工作區，必須先在原處斷開。
第一次使用
成員第一次向 Bot 發訊息時，會收到一次性 Multica 帳號繫結連結。開啟連結，登入同一工作區的 Multica 帳號，再回到 Telegram 重新傳送訊息。連結 15 分鐘後過期；再私聊 Bot 即可獲取新連結。
在群裡，Bot 不會公開傳送帶憑據性質的繫結連結，只會讓傳送者先私聊 Bot。
只有當前工作區成員能使用 Bot；每條訊息都會重新校驗成員身份。
在 Telegram 中交代工作
私聊
直接開啟 Bot 傳送文字，不需要 @。
群聊與 forum topic
把 Bot 加入群後，@ 它，或直接回復它發過的訊息。被接受的訊息會保留在持續的 Multica 對話中：普通群聊各自延續一段對話，forum 的每個 topic 分別隔離。
命令
/new建立一個新的空 Multica Chat，並把該 Telegram 對話的後續訊息路由到新 Chat；/new <訊息>會把訊息作為新 Chat 的第一輪。回覆其他成員並明確 @ Bot 時，被選中的引用內容仍會附在第一輪中。/clear保留當前 Multica Chat，把新的 AI 代理可見上下文應用到下一條非空訊息；/clear <訊息>會把訊息作為上下文邊界後的第一輪，明確選擇的回覆引用仍會保留。/issue <標題>建立 Multica 任務，後續行作為可選描述；不帶標題時返回用法提示。- 群聊支援
/issue@your_bot這種 Telegram 命令字尾。
回覆與內容範圍
Bot 透過傳送並編輯 Telegram 訊息來流式展示文字回覆，引用觸發訊息、保留 forum topic，並按 Telegram 長度限制自動分段。
圖片、檔案、影片、語音和音訊訊息會作為同一對話的附件交給 AI 代理，caption 作為訊息正文；AI 代理生成的檔案會在回覆之後發回聊天。這兩個方向都需要服務端配置物件儲存（見下文自託管部分）。
管理連線
在 設定 → 訊息渠道 → Telegram 檢視所有已連線 Bot。owner 和 admin 可以斷開。斷開會停止長輪詢和後續回覆，但保留 Multica 對話與審計記錄。
自託管配置
啟動 API 伺服器前配置一個長期穩定的 32 位元組加密金鑰：
MULTICA_TELEGRAM_SECRET_KEY=<base64 編碼的 32 位元組金鑰>可用 openssl rand -base64 32 生成。丟失或輪換此金鑰後，已有 Bot token 無法解密，需要逐個重新連線。
繫結連結使用 MULTICA_APP_URL，未設定時回退到 FRONTEND_ORIGIN；生成的地址必須能被成員訪問。伺服器網路或代理還必須允許 HTTPS 訪問 api.telegram.org；Go 會讀取標準的 HTTPS_PROXY 和 NO_PROXY 環境變數。
常見問題
- 無法驗證 Bot：先檢查伺服器網路和代理。只有 Telegram 明確拒絕 token 時才需要重新生成。
- webhook 衝突：連線前移除這個 Bot 已有的 webhook；Telegram 不允許 webhook 與
getUpdates同時使用。 - 409 輪詢衝突：另一個 Multica 例項或程序正在輪詢同一個 Bot。停止另一個消費者，或為不同環境使用不同 Bot。
- 群裡不回覆：確認 Bot 已入群，並且訊息 @ 了它或回覆了它的訊息。
- 繫結連結過期：重新私聊 Bot，並使用最新連結。
- Bot 不執行：檢查 AI 代理是否已歸檔，以及它使用的執行時是否線上。