Telegram

🟢 運行就緒：網關內置流式編輯能力（暫無生產調用者接入，詳見下文），是大多數 Minara 運營者首選的提供商。無需外部二進制文件，無需商業賬戶審批，只需一個 bot token 和一個 chat id。

功能概覽

• 流式編輯（網關就緒）：TelegramGateway 先發送一條佔位消息，隨後在文本到達時以 750 ms 節流間隔持續編輯該消息。可通過 apps/agent/src/messaging/stream-helpers.ts 中的 createStreamSink 驅動；send_message 工具本身為一次性發送。
• 富文本（默認開啟）：Markdown 回覆會渲染為 Telegram 格式（加粗、標題、表格、任務列表、代碼塊）。設置 TELEGRAM_RICH_TEXT=false 可改為純文本。
• 附件：圖片（sendPhoto）、文件（sendDocument）、語音（sendVoice，需 OGG/Opus 格式）、音頻（sendAudio）。來源必須是 Agent 在沙盒內生成的文件（詳見概覽頁面）。
• 群聊與私聊：兩種場景流程相同；群聊的 chat id 為負數。
• 每條消息上限 4096 字符。send_message 在工具邊界拒絕超長文本；流式接收器會在中途截斷並附加 … (truncated) 標記。

配置步驟

1. 創建 bot

1. 打開 Telegram，找到 @BotFather
2. 發送 /newbot，按提示填寫名稱和用戶名
3. 保存 BotFather 返回的 token（格式類似 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11）

2. 獲取 chat id

1. 與新建的 bot 開始對話併發送任意消息。若聊天未由用戶主動發起，Telegram 會屏蔽 bot 發出的消息
2. 在瀏覽器中訪問 https://api.telegram.org/bot<TOKEN>/getUpdates，在返回結果中找到 "chat":{"id":...}

如需在群組中使用：將 bot 添加到群組，在群組中發送一條消息，再通過 getUpdates 查詢。群組 id 為負數（例如 -1001234567890）。

3. 配置 Minara

簡易方式：在對話中直接告知 Agent：

"set up Telegram notifications"

Minara 會提示輸入 token 和 chat id，寫入 ~/.minara/credentials.json（messaging 槽），併發送測試 ping。

手動方式：

minara auth messaging add telegram

或直接在項目根目錄的 .env 文件中設置環境變量：

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_CHAT_ID=-1001234567890

4. 測試

minara auth messaging test telegram

正常情況下，測試消息會在一兩秒內到達。

流式傳輸行為

Telegram 的 editMessageText 接口在不觸發頻率限制的情況下，每條消息最多支持約 30 次編輯。TelegramGateway 提供 startStream() 會話，先發送佔位消息，隨後在新文本到達時持續編輯；createStreamSink 將編輯節流設置為 750 ms，既能保持實時感，又能充分控制在單聊頻率限制以內。累計文本超過 4096 字符時，會在中途截斷並附加 … (truncated) 標記。

節流間隔和長度上限通過 createStreamSink(gw, msg, { intervalMs, maxLength }) 在調用方設置，而非 send_message 的參數。工具路徑本身為一次性發送，LLM 發送完整消息；流式傳輸存在於工作流/Autopilot 代碼中（生產環境暫未接入）。

富文本

回覆默認渲染為 Telegram 富文本。Agent 生成 Markdown，網關在發送前將其轉換為 Telegram 支持的 HTML 子集：

• 標題變為加粗，列表保留項目符號，任務列表顯示 ☐ / ☑，表格渲染為等寬對齊文本，代碼塊保留語言標籤。
• 如果 Telegram 拒絕該 HTML（極少發生），網關會用相同內容重試 MarkdownV2，再退回純文本。消息不會因為格式錯誤而丟失。
• 流式輸出時，每次編輯只顯示已閉合的格式，因此不會在解析完成前閃現半截的 **bold。

關閉後會原樣發送 Agent 的文本：

TELEGRAM_RICH_TEXT=false

可識別的"關閉"取值為 0、false、no、off；未設置即為開啟。該設置在啟動時讀取一次，修改後需重啟網關。也可以在 Web UI 的 設置 → 消息平臺 → Telegram 富文本 中切換。

附件

附件引用的是 Agent 已在沙盒內生成的文件（通過 image_generate、audio_generate、write_file、代碼執行等方式）。LLM 傳入沙盒相對路徑：

send_message({
  provider: "telegram",
  text: "BTC/USD daily — key levels marked",
  attachments: [
    { kind: "image", sandbox_path: "images/btc-2026-04-19.png" },
  ],
})

類型路由：

多個附件按順序逐條發送；若第一條的 msg.text 足夠短（不超過 1024 字符），則作為 caption 附在第一條消息上，否則文本單獨作為引導消息先行發送，附件隨後跟上。詳見 apps/agent/src/messaging/telegram.ts。

覆蓋通道

將緊急提醒路由到不同聊天，同時保持常規通知走默認通道：

send_message({
  provider: "telegram",
  channel: "-1009876543210",
  text: "Critical: position liquidation imminent",
})

故障排查

"測試消息未收到"

• 是否已主動向 bot 發送過消息？Telegram 會屏蔽未經用戶發起的聊天中 bot 發出的消息
• 檢查 TELEGRAM_CHAT_ID 的符號，群聊 id 為負數
• 確認 bot 仍在群組中：BotFather → 你的 bot → Bot Settings → Group Privacy

"流式傳輸感覺慢或卡頓"

• 屬於正常現象：TelegramGateway 內置 750 ms 基準節流。調用方可通過 createStreamSink(gw, msg, { intervalMs: 500 }) 覆蓋此值，這是調用方參數，不是 send_message 工具的參數
• 超長響應會在 4096 字符處截斷，可考慮將工作流拆分為多條消息

"Chat not found (400)"

• bot 已被移出群組，或 chat id 有誤
• 在目標聊天中發送一條新消息後，重新執行 getUpdates 步驟

參考資料

• 環境變量：TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID、TELEGRAM_RICH_TEXT
• 源碼：apps/agent/src/messaging/telegram.ts
• Bot API 文檔：core.telegram.org/bots/api