← 所有文章
對比選型

Telegram Bot API Webhook 同統一入站 Webhook：應該點揀？

如果你正在比較 Telegram Bot API 輪詢、Telegram setWebhook 同統一入站 webhook，第一步係確認「身份」。Telegram Bot API 接收嘅係 bot token 代表嘅機械人 updates，唔會將一般 Telegram 帳戶變成客服收件箱。機械人係正確身份時，可以用 setWebhook 做 HTTPS 推送，或者用 getUpdates 做輪詢；如果你要接收現有 Telegram 帳戶訊息，或者將 Telegram 同 WhatsApp、LINE、TikTok、Zalo、X 放入同一個客服隊列，就更適合用 UnifyPort 統一入站 webhook。

重點

  • Telegram 官方 Bot API token 用嚟認證機械人，唔係認證個人或團隊帳戶。Telegram 官方教學亦說明，token 由 @BotFather 產生，用嚟識別機械人。
  • Telegram 官方文件將 Bot API updates 接收方式分成 getUpdates 拉取同 setWebhook 推送；兩者都係機械人模型入面嘅選擇。
  • UnifyPort 統一入站 webhook 係另一層：連接一個 messaging account 後，以同一套簽名 message.received 事件流接收多平台訊息。
  • 如果你嘅查詢較接近 telegram bot api authorizing your bot token，可以先睇 Telegram API ID、API hash 同 Bot Token 差異，再用本文揀接收方式。
  • 想睇實作，可以參考 用 Cursor 建 Telegram 到 Slack 轉發器 呢篇 build log。

Telegram 官方 Bot API 實際接收咩？

Telegram 官方 Bot API 文件講明，機械人透過唯一 token 授權；建立機械人時會得到 token，之後呼叫 Bot API 就用佢認證。Telegram 官方教學更加直接：呢個 token 認證嘅係機械人，唔係你嘅 Telegram 帳戶。

好多團隊搜尋「Telegram login API」或者「authorizing your bot token」時，其實混合咗三種需求：

  1. 建立 Telegram 機械人，俾用戶主動同機械人對話。
  2. 連接一般 Telegram 帳戶，接收該帳戶已參與聊天入面嘅訊息。
  3. 建立跨渠道客服隊列，Telegram 只係 WhatsApp、LINE、Zalo、TikTok、X 旁邊其中一個來源。

Bot API 好適合第一種需求，但唔係第二、第三種需求嘅架構。第二種通常會涉及 Telegram core API 應用憑證，例如 api_id 同 api_hash；UnifyPort Telegram 授權文件入面，對應欄位係 provider_data.api_id、provider_data.api_hash，code login 亦需要 provider_data.phone。

Telegram Bot API webhook vs getUpdates

Telegram 官方 webhook 指南說明，處理 bot updates 有兩種方式：getUpdates 同 setWebhook。可以咁比較：

選項傳遞模型適合情境主要取捨
getUpdates你嘅程式主動輪詢 Telegram本地原型、簡單機械人、低流量工具要管理輪詢、offset 同空回應
setWebhookTelegram 向你嘅 HTTPS 網址發 POST有穩定公開 endpoint 嘅正式機械人要維護可連線 HTTPS receiver 同交付處理
UnifyPort 統一 webhookUnifyPort 向你推送標準化簽名事件現有 messaging account 同跨渠道隊列對接 UnifyPort 事件契約，而唔係 Telegram Update 物件

如果只係 Telegram 機械人，setWebhook 通常更似正式環境方案，因為 updates 會被推送到你服務端；內部工具或早期原型則可以先用 getUpdates。但兩者仍然都係 Bot API 模型：bot token、Telegram 專用 update JSON、Telegram 專用處理邏輯。

當「機械人身份」唔係正確身份

接收身份應該配合客戶原本使用嘅入口。如果客戶一直向某個 Telegram 帳戶發訊息，要佢哋改搵新機械人，可能會增加溝通成本。如果客服同時處理 WhatsApp、LINE 或 Zalo，將 Telegram 放喺架構中心亦會產生另一個問題：每個平台都有自己事件格式。

更好嘅問題係：入站客服嘅事實來源應該係咩？ 如果答案係「訊息到達時嘅事件」，就應該先將簽名事件流放喺隊列前面，並盡早標準化。

所以 Telegram 原生聊天自動化亦唔等於跨渠道收件箱。呢個邊界可以繼續睇 Telegram 聊天自動化同跨渠道入站隊列。

UnifyPort 放喺邊一層

UnifyPort 接收各平台事件，然後向你嘅 endpoint 交付統一 webhook envelope。欄位細節見 Standard event types and payload；交付 headers、HMAC-SHA256 驗證同重試行為見 Webhook delivery and signature verification。

一條 Telegram 入站文字訊息會保持同其他平台一致嘅頂層結構：

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z",
      "text": "Can you check my order?"
    },
    "event": { "kind": "message_received" }
  }
}

如啟用 signing_secret，receiver 應驗證 X-Device-Signature，並用原始 request body 計算簽名；由於交付係 at-least-once，亦要用 event id 做冪等去重。建立 receiver 時，用 POST /v1/webhook-endpoints，設定公開 HTTPS url、subscribed_events（例如 ["message.received"] 或 ["*"]）同可選 signing_secret。

小團隊點樣揀

選官方 Bot API，如果：

  • 客戶本來就應該同機械人互動；
  • 工作流只喺 Telegram；
  • 你願意用 Telegram Update 物件做內部模型；
  • 你已有 setWebhook 所需公開 HTTPS endpoint，或 getUpdates 輪詢已夠用。

選 UnifyPort 統一入站 webhook，如果：

  • 收件箱已經喺現有 Telegram 帳戶入面；
  • 你希望 Telegram 同 WhatsApp、LINE、TikTok、Zalo 或 X 入同一個隊列；
  • 你嘅應用想用一套 schema 處理 message.received、message.updated、回執、反應同帳戶狀態；
  • 你希望用同一套 HMAC-SHA256 驗證方式，而唔係為每個平台寫唔同 receiver。

限制同取捨

UnifyPort 唔係所有 Telegram Bot API 功能嘅替代品。如果產品依賴 inline keyboard、bot command、BotFather 設定或者其他機械人專屬能力，官方 Bot API 仍然係正確選擇。如果你要發布公開 Telegram 機械人，bot token 就係正確憑證。

統一 webhook 最適合入站接收同路由。佢提供穩定事件契約，但你仍然需要儲存事件、冪等處理重試，並按各平台授權方式維護 messaging account。

FAQ

Telegram bot token 同 Telegram API ID / API hash 係咪一樣？

唔一樣。bot token 認證 Bot API 入面嘅機械人；api_id 同 api_hash 係 Telegram core API 場景嘅應用憑證。如主要困惑係呢點，先睇 Telegram API ID、API hash 同 Bot Token 差異。

Telegram 機械人應該用 getUpdates 定 setWebhook？

想快速開始、接受輪詢模型時，用 getUpdates。已有穩定 HTTPS endpoint、希望 Telegram 主動推送 updates 時，用 setWebhook。兩者都係官方 Bot API 嘅機械人接收方式。

Telegram Bot API webhook 可以接收一般 Telegram 帳戶收到嘅訊息嗎？

唔可以。Bot API webhook 接收嘅係 bot token 所代表機械人嘅 updates。一般帳戶或跨渠道客服隊列，應使用帳戶層級入站路徑，例如 UnifyPort 統一 webhook。

選擇統一 webhook 後第一步係咩？

先註冊 receiver，再連接帳戶。Create webhook endpoint 文件列出 url、status、subscribed_events、signing_secret 同 retry_policy.max_attempts。

下一步

如果你做純 Telegram 機械人產品，繼續用 Telegram Bot API 文件即可。如果你做客服或自動化隊列，先從 UnifyPort webhook events reference 開始，完成一個 message.received handler，再加入更多渠道。

來源核對於 2026-08-28

UnifyPort API

令訊息接入變成一條穩定嘅產品管線。

先用統一嘅 API 跑通發送，再用標準事件將所有入站訊息接返去業務系統。

攞 API Key睇 API 參考