← 所有文章
對比選型

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-only 機器人來說，setWebhook 通常更像正式環境方案，因為 updates 會被推送到你的服務；內部工具或早期原型則可以先用 getUpdates。但兩者仍然都在 Bot API 模型內：bot token、Telegram 專用 update JSON、Telegram 專用處理邏輯。

當「機器人身份」不是正確身份

接收身份應該符合客戶已經習慣的入口。若客戶本來就傳訊息給某個 Telegram 帳號，要他們改找新機器人，可能增加溝通成本。若支援團隊同時處理 WhatsApp、LINE 或 Zalo，把 Telegram 當成架構中心還會帶來另一個問題：每個平台都有不同事件格式。

更好的問題是：入站客服的事實來源應該是什麼？ 如果答案是「訊息抵達時的事件」，就應該把簽名事件流放在佇列前面，並在一開始就標準化。

這也是為什麼 Telegram 原生聊天自動化並不等於跨渠道收件匣。更多邊界說明可讀 Telegram 聊天自動化與跨渠道入站佇列。

UnifyPort 放在哪一層？

UnifyPort 接收各平台事件，然後向你的 endpoint 傳遞統一 webhook envelope。詳細欄位可看 標準事件類型與 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 keyboards、bot commands、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 參考