← 所有文章
對比選型

Telegram API ID 與 API Hash vs Bot Token：你需要哪種憑證？

Telegram bot token 用於向 HTTP Bot API 驗證一個 Bot 的身份，並不能登入個人 Telegram 帳戶。API ID 與 API hash 用於識別 client 應用程式；透過 Telegram 的 MTProto API 授權用戶帳戶時，包括驗證碼及 QR 登入，都需要這兩項憑證。應按需要控制的身份選擇憑證：Bot 身份 → bot token；現有用戶帳戶 → API ID 與 API hash。

重點整理

  • 如果整合需要以獨立 Telegram Bot 的身份運作，請向 @BotFather 取得 bot token。
  • 如果應用程式需要授權現有 Telegram 用戶帳戶，請從 my.telegram.org 取得 API ID 與 API hash。
  • Bot token 不能取代 API ID/API hash，掃描 QR code 也不會免除應用程式憑證要求。
  • 不要把 bot token、API hash、登入驗證碼及已授權的 session 資料放入版本控制系統或日誌。
  • 如要在 UnifyPort 連接一般 Telegram 帳戶，請使用 API ID 與 API hash，並依照 Telegram 授權指南操作；不要在該流程中貼上 BotFather token。

Telegram API ID、API hash 與 bot token 有何分別？

這三種資料都能提供某種 Telegram 存取權，因此名稱很容易混淆。不過，它們分屬不同的 API 體系，驗證的身份也不同。

你要建立的功能所需憑證取得位置授權後的身份
HTTP Bot API 整合Bot token@BotFather獨立的 Bot 帳戶
登入 Telegram 用戶的 clientAPI ID + API hash，再配合驗證碼、QR 或其他受支援的用戶登入步驟my.telegram.org → API development tools獲授權的用戶帳戶
UnifyPort 的用戶帳戶連接用於驗證碼或 QR 授權的 API ID + API hashmy.telegram.org批准登入的 Telegram 帳戶

Telegram 官方 Bot 教學清楚指出：bot token 驗證的是 Bot，而不是你的帳戶。這個 token 會傳送至 https://api.telegram.org/bot<TOKEN>/getMe 等 endpoint，也可以在 @BotFather 撤銷。

API ID 與 API hash 則屬於 Telegram client 應用程式。登入 my.telegram.org 並完成 API development tools 表格後，Telegram 便會發出這兩項憑證。用戶授權方法會把這些應用程式憑證與由用戶控制的登入步驟配合使用。例如，auth.sendCode 會接收電話號碼、api_id 及 api_hash；授權成功後，產生的 client session 會綁定該用戶。

關鍵差異就在這裏：bot token 選定的是 Bot 身份，而 API ID/API hash 識別的是參與用戶帳戶登入的 client。

應該選擇哪種憑證？

先確定哪個身份需要接收或發送訊息。

可以使用 Bot 身份時，選擇 bot token

如果用戶會主動與 Bot username 對話、把該 Bot 加入群組，或使用 Bot 專屬功能，便應使用官方 Bot API。透過 @BotFather 建立 Bot，把 token 當作密碼保管，並透過 polling 或 Telegram webhook 接收 Bot API update。

對於以 Bot 為核心設計、只支援 Telegram 的產品，這通常是最簡潔的做法。Telegram 負責 Bot lifecycle，API 也是官方提供，而且無需授權個人用戶 session。我們在 Telegram 原生聊天自動化與跨渠道 inbound queue 的比較 中，進一步說明了這種官方模式適合哪些情境。

需要使用用戶帳戶身份時，選擇 API ID 與 API hash

如果產品必須授權現有 Telegram 帳戶，而不是建立新的 Bot 身份，請使用 Telegram 的 client API 路徑。應用程式先以 API ID 與 API hash 識別自己，然後由帳戶擁有人完成用戶登入步驟，例如驗證碼、QR 批准，以及啟用 2FA 時的相關驗證。

不要把 API ID/API hash 本身理解為已登入帳戶。它們識別的是應用程式；經用戶控制的授權流程才會建立帳戶 session。同樣，電話號碼或 QR 圖像也不能取代應用程式憑證。

如果最終目標是把現有 Telegram 帳戶的訊息轉送至另一套系統，Telegram-to-Slack relay 建置記錄 展示了帳戶連接後的下游 webhook 架構。

如何從 my.telegram.org 取得 API ID 與 API hash

Telegram 的官方流程很簡短，但頁面名稱必須認清：

  1. 在官方 Telegram app 註冊並維持一個有效的電話號碼。
  2. 開啟 my.telegram.org，並在 /auth 完成帳戶登入。
  3. 選擇 API development tools。
  4. 填妥應用程式表格。
  5. 把取得的 api_id 與 api_hash 儲存在伺服器端的憑證儲存空間。

Telegram 目前每個電話號碼只允許一個 API ID，並提醒開發者，client library 會受到監察，以防遭到濫用。正式發佈的應用程式應使用自己的應用程式憑證、遵守 Telegram API Terms of Service，也不要把 Telegram 開源 client 中用途受限的示範 API ID 複製到 production。

QR 登入仍需要 API ID 與 API hash 嗎？

需要。QR 改變的是用戶批准登入的方式，不會改變提出請求的是哪個 client 應用程式。

Telegram 官方 QR 流程由 auth.exportLoginToken 開始，其參數包括 api_id 與 api_hash。Client 會把傳回的 token 顯示為 tg://login QR code，再由一個已登入的 Telegram app 掃描並接受。Telegram 表示，login token 通常約 30 秒後失效，因此過期的 QR 必須重新整理。

所以，「QR 還是 API 憑證？」並不是正確的選擇題。授權用戶時，QR 是與應用程式憑證一同使用的批准方法。

UnifyPort 的定位

UnifyPort 透過非官方接口連接一般 Telegram 帳戶，並不會建立 Telegram Bot。因此，驗證碼及 QR 授權流程都採用用戶帳戶憑證路徑。

使用驗證碼授權時，請以 provider: "telegram"、auth_mode: "code" 及以下真實欄位建立帳戶：

{
  "provider": "telegram",
  "auth_mode": "code",
  "provider_data": {
    "api_id": 12345678,
    "api_hash": "0123456789abcdef0123456789abcdef",
    "phone": "+886912345678"
  }
}

使用 QR 授權時，仍然需要 provider_data.api_id 與 provider_data.api_hash，並由帳戶擁有人在 Telegram 中批准短效 QR。Telegram 授權 API 參考 列出了驗證碼、QR、2FA 與 session 的確切步驟。

授權完成後，Telegram inbound 訊息可以像其他已連接 provider 一樣，以同一個經簽署的 message.received event 傳入。這個一般帳戶流程不會使用 BotFather token。

限制與取捨

如果獨立 Bot 身份已能滿足產品要求，請使用 Telegram 官方 Bot API。它專為 Bot 而設，也無需維護用戶帳戶 session。

只有在確實需要現有帳戶時，才應使用 client／用戶帳戶流程。授權會產生敏感的 session 資料，帳戶仍須遵守 Telegram 規則，而取得 API 存取權也不代表可以發送垃圾訊息或從事其他受禁止的行為。UnifyPort 不會把 bot token 轉成用戶 session、不會代你建立 API ID，也不會移除 Telegram 的平台管控。

此外，Telegram Login for websites 與這項憑證選擇是兩回事。Telegram 現行的網頁登入系統採用 OpenID Connect 流程，並有獨立的 client 設定；它既不能取代 Bot API token，也不能取代 MTProto 用戶帳戶授權。

常見問題

Telegram API ID 與 bot token 相同嗎？

不同。API ID 識別的是參與 Telegram API 授權的 client 應用程式；bot token 則向 Bot API 驗證一個 Bot。兩者在不同位置發出，控制的身份也不同。

已經有 bot token，仍需要 API ID 與 API hash 嗎？

進行一般 HTTP Bot API call 時不需要；你只需要該 Bot 的 bot token。當整合透過 client API 授權 Telegram 用戶時，才需要 API ID 與 API hash；bot token 不能登入該用戶帳戶。

在哪裏可以找到 my.telegram.org/auth？

開啟 https://my.telegram.org/，並使用 Telegram 電話號碼登入。完成驗證後，選擇 API development tools，即可建立或查看與該號碼關聯的 API ID 與 API hash。

沒有 API hash，可以使用 QR 登入嗎？

不可以。Telegram 的 auth.exportLoginToken request 同時包含 api_id 與 api_hash。QR 是用戶批准登入的步驟，不能取代應用程式憑證。

UnifyPort 可以使用 BotFather token 連接 Telegram 嗎？

一般 Telegram 帳戶授權流程不可以。驗證碼與 QR 模式都使用 provider_data.api_id 和 provider_data.api_hash；驗證碼模式還會使用帳戶電話號碼。如果目標身份是 Bot，請直接使用官方 Bot API。

下一步

如要連接現有 Telegram 帳戶，請開啟 Telegram 授權指南，再選擇驗證碼或 QR 流程。如果只需要 Bot 身份，請繼續使用 @BotFather 與官方 Bot API。

來源

來源與產品文件已於 2026-07-19 核實。