點樣喺群組聊天室傳送 Telegram 私密短暫機械人訊息

Telegram 機械人而家可以喺群組或超級群組內傳送一則短暫訊息，只有指定用戶同機械人本身睇得到。一般機械人必須喺符合資格嘅 callback 或短暫訊息出現後 15 秒內回覆；如果機械人係聊天管理員，就可以隨時向任何非機械人成員主動傳送。訊息唔保證一定送達，收件人離線時尤其如此。

重點摘要

• Bot API 10.2 喺 2026 年 7 月 14 日加入咗按用戶顯示嘅私密機械人訊息同短暫指令。
• 如果用戶輸入嘅指令唔應該畀其他成員同機械人見到，請將指令嘅 is_ephemeral 欄位設為 true。
• 非管理員機械人需要近期嘅 callback_query_id 或 reply_parameters.ephemeral_message_id，而且必須喺 15 秒內回應。
• 管理員機械人唔需要上述觸發識別碼，都可以向任何非機械人成員傳送訊息，但送達仍然只屬盡力而為。
• 短暫訊息適合做介面回饋，唔係持久稽核紀錄，亦唔係跨平台訊息類型。

乜嘢係 Telegram 私密短暫機械人訊息？

短暫機械人訊息係顯示喺群組或超級群組訊息串內、但只畀一位用戶睇到嘅私密回應。其他群組成員同其他機械人都睇唔到。Telegram 列出嘅合適例子包括歡迎訊息、私密 AI 摘要、錯誤提示、確認訊息、情境提示同按鈕選單。

呢個功能同 Telegram Guest Mode 唔一樣。Guest Mode 決定機械人點樣喺未加入嘅聊天中被叫出嚟；短暫訊息就決定某個指令或機械人回覆由邊個睇到。佢亦有別於 Bot API 10.1 富文本訊息，後者改變嘅係格式，而唔係可見範圍。

Telegram 表示，呢類互動可能會喺一段時間後自動消失，亦可能喺應用程式重新啟動時消失。官方文件冇公布固定保留時間，所以唔好將畫面上見到嘅訊息當成審批、付款狀態、支援決定或其他持久業務事件嘅唯一紀錄。

邊類機械人可以喺群組傳送私密回覆？

權限路徑有兩種。設計 handler 之前應該先揀定路徑，因為兩者所需嘅識別碼同傳送行為並唔相同。

機械人情境	可以傳送嘅時機	必需觸發資料	傳送範圍
任何機械人	符合資格嘅入站動作發生後 15 秒內	callback_query_id 或 reply_parameters.ephemeral_message_id	觸發該動作嘅客戶端應用程式
聊天管理員機械人	隨時向非機械人成員傳送	唔需要任何一個觸發識別碼	可能送到多個活躍客戶端，但唔保證送達

兩條路徑都以 receiver_user_id 指定邊位用戶可以睇到。外送短暫訊息只限群組同超級群組，唔可以取代私訊對話。

送達限制非常重要：Telegram 明確表示訊息唔保證會送達，尤其係用戶離線嗰陣。應該將呢類訊息設計成方便嘅 UI 回饋。如果操作會改變伺服器狀態，先持久保存狀態，再畀用戶日後重新查閱。

步驟 1：宣告短暫指令

使用 setMyCommands，並將應該保持私密嘅指令設為 is_ephemeral: true。以下假設性指令會令用戶嘅 /summary 請求唔畀其他群組成員同機械人睇到：

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {
        "command": "summary",
        "description": "Summarize this discussion for me",
        "is_ephemeral": true
      }
    ],
    "scope": {
      "type": "all_group_chats"
    }
  }'

is_ephemeral 影響嘅係用戶送出嘅指令。佢本身唔會指定其後每一則機械人訊息嘅收件人。傳送請求仍然需要正確嘅聊天、可見用戶，以及符合資格嘅觸發資料——除非機械人係管理員。

步驟 2：傳送私密群組回覆

如果回應由 callback 觸發，請呼叫支援嘅傳送方法，並提供 chat_id、receiver_user_id 同 callback_query_id。Bot API 10.2 為 sendMessage，以及支援嘅媒體、檔案、聯絡人同位置方法加入咗兩個短暫訊息參數。

以下假設性請求會向超級群組內其中一位成員傳送確認訊息：

curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": -1001234567890,
    "receiver_user_id": 424242424,
    "callback_query_id": "4382bfdwdsb323b2d9",
    "text": "Your report is ready. Only you can see this confirmation."
  }'

請喺 15 秒時限內送出請求。如果觸發來源係入站短暫訊息，而唔係 callback query，就改用 reply_parameters.ephemeral_message_id 回覆。唔好用一般 message_id 代替；Bot API 10.2 特別規定，提供短暫訊息識別碼時，message_id 可以省略。

如果管理員機械人唔依賴近期動作而主動傳送訊息，可以省略 callback_query_id 同短暫回覆目標，但仍然要提供群組嘅 chat_id，以及非機械人成員嘅 receiver_user_id。

步驟 3：用短暫訊息識別碼編輯或刪除

將 Telegram Message 物件回傳嘅 ephemeral_message_id，連同 chat_id 同 receiver_user_id 一齊儲存。一般訊息嘅編輯同刪除方法唔適用於呢種訊息嘅生命週期。

請使用以下專用方法：

• editEphemeralMessageText
• editEphemeralMessageMedia
• editEphemeralMessageCaption
• editEphemeralMessageReplyMarkup
• deleteEphemeralMessage

例如，編輯文字時需要齊備三個識別欄位：

{
  "chat_id": -1001234567890,
  "receiver_user_id": 424242424,
  "ephemeral_message_id": 781,
  "text": "The report is ready to download."
}

Telegram 亦提醒，編輯同刪除事件未必會送到離線用戶。應該將生命週期呼叫視為盡力而為嘅 UI 更新，而唔係某人已經睇過——或者已經無法再睇到——敏感資料嘅證明。

實作清單

1. 先分類回應。 私人回饋如果需要保留群組情境，可以用短暫訊息；團隊必須保留嘅紀錄就唔適合。
2. 即時擷取觸發資料。 callback_query_id 或入站 ephemeral_message_id 只保留到足以完成 15 秒回應路徑。
3. 喺伺服器授權。 隱藏可見範圍唔等於授權。產生摘要、選單或執行操作之前，先確認呼叫者有權提出要求。
4. 另外持久保存重要狀態。 審批、工作狀態同支援操作要先儲存到自家資料庫，再透過 UI 確認。
5. 使用專用生命週期方法。 將 chat_id、receiver_user_id 同 ephemeral_message_id 作為同一組查詢 key 儲存，供編輯同刪除使用。
6. 預先處理未送達情況。 如果用戶必須可以重新取得結果，就提供一般私訊、dashboard 或重試路徑。
7. 測試角色同客戶端。 覆蓋一般機械人、管理員機械人、群組同超級群組、多部活躍裝置，以及離線收件人。

UnifyPort 適用嘅位置——同唔適用嘅位置

Telegram 短暫訊息係 Telegram Bot API 功能。現時 UnifyPort API Reference 並冇記載 POST /v1/messages 支援 receiver_user_id、callback_query_id 或短暫訊息編輯／刪除方法。如果產品依賴呢種按用戶顯示嘅群組介面，請使用 Telegram 官方 Bot API。

UnifyPort 解決嘅係另一個層次：支援帳戶收到嘅一般入站訊息，可以透過標準化嘅 message.received 事件 到達；支援嘅標準回覆則可以跨供應商使用同一個訊息 API。當團隊需要一個橫跨 Telegram、WhatsApp、LINE、Zalo、TikTok 同 X 嘅持久佇列，呢個方式就有幫助。佢唔會將其他平台嘅訊息變成 Telegram 短暫回覆，亦唔會保留 Telegram 專屬嘅可見範圍語意。

如果真正需求係多渠道支援，而唔係 Telegram 專屬機械人介面，可以參考跨渠道 Telegram 自動化指南，了解架構邊界。

限制同取捨

如果機械人需要喺唔帶用戶離開群組嘅情況下，顯示私密確認、錯誤、選單或摘要，就應該選用官方 Bot API 功能。佢提供 Telegram 客戶端原生嘅按用戶可見性，亦支援文字、多種媒體同實用訊息類型。

如果用途係保證送達嘅警示、合規紀錄、持久支援歷史，或者必須確實撤回嘅秘密，就唔應該選用。離線用戶嘅訊息送達、編輯同刪除都冇保證；訊息可能會消失；官方文件亦冇承諾固定保留時間。非官方介面無法改變平台嘅呢啲保證，亦無法為其他渠道加入短暫訊息行為。

常見問題

Telegram 機械人可唔可以傳送只畀一位群組成員睇到嘅訊息？

可以。喺群組或超級群組提供 receiver_user_id，並符合 15 秒有效觸發路徑或者聊天管理員路徑。只有指定用戶同機械人睇得到短暫訊息。

機械人一定要係群組管理員嗎？

唔一定。任何機械人只要有相關 callback_query_id 或入站短暫回覆識別碼，都可以喺 15 秒內回應。管理員機械人就唔需要呢啲觸發識別碼，都可以向任何非機械人成員主動傳送短暫訊息。

Telegram 短暫機械人訊息會保留幾耐？

Telegram 冇公布固定保留時間。官方文件表示，互動可能會喺一段時間後自動消失，亦可能喺應用程式重新啟動時消失，所以應用程式唔應該將佢當成持久儲存空間。

離線用戶收唔收到短暫訊息？

唔保證送達，尤其係用戶離線嗰陣。編輯同刪除事件亦有同樣限制。重要結果應該提供可以重新取得嘅路徑。

短暫訊息同 Telegram Guest Mode 係咪一樣？

唔一樣。Guest Mode 控制機械人點樣喺未加入聊天嘅情況下參與；短暫訊息控制群組內某個指令或回覆嘅可見範圍。兩者可以配合使用，但解決嘅係唔同問題。

下一步

按照官方 Bot API 短暫訊息參考文件實作 Telegram 專用路徑。如果工作流程其餘部分需要跨多個供應商保留持久訊息，設計共用 handler 前，先查看 UnifyPort 供應商訊息支援矩陣。

資料來源

官方來源核對日期：2026 年 7 月 20 日。

• Telegram Bot API 10.2 變更同 API Reference
• Telegram Bot 功能：短暫訊息
• Telegram 公告：Ephemeral Bot Messages