對比選型 July 19, 2026

Telegram API ID、API hash 與 bot token 有什麼差別？該用哪一種憑證？

Telegram API ID、API hash 與 bot token 有什麼差別？bot token 用來讓一個 bot 透過 HTTP Bot API 完成身分驗證，不能登入個人 Telegram 帳號。API ID 和 API hash 用於識別用戶端應用程式；如果要透過 Telegram 的 MTProto API 授權使用者帳號，包含驗證碼或掃描 QR code 登入，就必須提供這兩個值。選擇憑證時，先看你要控制的身分：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 帳號時，請依照 Telegram 授權指南使用 API ID 和 API hash，不要把 BotFather token 貼到這個流程中。

Telegram API ID、API hash 與 bot token 有什麼差別？

這三個值都會授予某種 Telegram 存取能力，因此名稱很容易混淆，但它們屬於不同的 API，驗證的身分也不同。

你要建構的功能	所需憑證	取得位置	授權後的身分
HTTP Bot API 整合	Bot token	`@BotFather`	一個獨立的 bot 帳號
登入 Telegram 使用者的用戶端	API ID + API hash，再完成驗證碼、掃描 QR code 或其他支援的使用者登入步驟	`my.telegram.org` → API development tools	完成授權的使用者帳號
在 UnifyPort 中連接使用者帳號	API ID + API hash，用於驗證碼或 QR code 授權	`my.telegram.org`	核准登入的 Telegram 帳號

Telegram 官方 bot 教學說得很清楚：bot token 驗證的是 bot，而不是你的帳號。呼叫 https://api.telegram.org/bot<TOKEN>/getMe 等 endpoint 時需要帶上這個 token，也可以隨時在 @BotFather 中撤銷。

API ID 和 API hash 則屬於 Telegram 用戶端應用程式。登入 my.telegram.org 並填寫 API development tools 表單後，Telegram 才會核發這兩個值。使用者授權流程會把應用程式憑證與使用者掌控的登入步驟結合起來。例如，auth.sendCode 需要手機號碼、api_id 和 api_hash；授權成功後，產生的用戶端 session 會綁定該使用者。

最關鍵的差別就在這裡：bot token 選定的是 bot 身分，API ID/API hash 識別的則是參與使用者帳號登入的用戶端應用程式。

應該選擇哪一種憑證？

先確認真正需要收發訊息的是哪一種身分。

可以使用 bot 身分時，選擇 bot token

如果使用者會主動和某個 bot 使用者名稱聊天、把 bot 加入群組，或使用 bot 專屬功能，就應選擇官方 Bot API。透過 @BotFather 建立 bot，像保護密碼一樣保管 token，再透過輪詢或 Telegram webhook 接收 Bot API update。

對於以 bot 為核心、只服務 Telegram 的產品，這通常是最簡潔的方案。bot 的生命週期由 Telegram 管理，API 也是官方提供的，而且不需要授權個人使用者 session。我們的〈Telegram 原生聊天自動化與跨渠道入站佇列比較〉進一步說明了這套官方模式最適合哪些情境。

必須使用使用者帳號身分時，選擇 API ID 和 API hash

如果產品必須授權現有 Telegram 帳號，而不是建立新的 bot 身分，就需要採用 Telegram 用戶端 API 流程。應用程式先透過 API ID 和 API hash 識別自身，再由帳號擁有者完成使用者登入，例如輸入驗證碼、掃描 QR code 確認，以及在已啟用時完成 2FA。

不要把 API ID/API hash 本身視為一個已登入的帳號。它們識別的是應用程式，只有使用者完成授權後才會產生帳號 session。同樣地，手機號碼或 QR code 也不能取代應用程式憑證。

如果最終目標是把現有 Telegram 帳號的訊息轉送到其他系統，可以參考〈用 Cursor 建構 Telegram 到 Slack 訊息轉送〉，了解帳號連接完成後的下游 webhook 架構。

如何透過 my.telegram.org/auth 取得 API ID 和 API hash

Telegram 的官方流程不長，但頁面名稱必須選對：

在 Telegram 官方應用程式中註冊並保留一個有效的手機號碼。
開啟 my.telegram.org，在 /auth 完成帳號登入。
選擇 API development tools。
填寫應用程式資訊表單。
將取得的 api_id 和 api_hash 存入伺服器端的憑證庫。

Telegram 目前規定每個手機號碼只能申請一個 API ID，並明確提醒平台會監控用戶端程式庫的濫用行為。正式發布的應用程式應使用自己的應用程式憑證、遵守 Telegram API 服務條款，也不要把 Telegram 開放原始碼用戶端中用途受限的範例 API ID 用於正式環境。

掃描 QR code 登入仍需要 API ID 和 API hash 嗎？

需要。掃描 QR code 改變的是使用者核准登入的方式，不會改變是哪一個用戶端應用程式提出請求。

Telegram 官方 QR code 登入流程從 auth.exportLoginToken 開始，這個方法的參數就包含 api_id 和 api_hash。用戶端會把傳回的 token 轉成 tg://login QR code，再由已登入的 Telegram 應用程式掃描並確認。Telegram 說明該 login token 通常約 30 秒後到期，因此 QR code 過期後必須重新整理。

所以，「該用 QR code 還是應用程式憑證」並不是正確的問題。授權使用者帳號時，QR code 是搭配應用程式憑證使用的一種核准方式。

UnifyPort 在這個流程中的角色

UnifyPort 透過非官方接口連接一般 Telegram 帳號，不會建立 Telegram bot。因此，它的驗證碼和 QR code 授權都採用使用者帳號憑證流程。

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

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

使用 QR code 授權時，仍然必須提供 provider_data.api_id 和 provider_data.api_hash，再由帳號擁有者在 Telegram 中核准短時間有效的 QR code。Telegram 授權 API 參考列出了驗證碼、QR code、2FA 和 session 的完整步驟。

授權完成後，Telegram 入站訊息可以和其他已連接渠道一樣，以簽章的 message.received 事件送達。一般帳號授權流程不會接收 BotFather token 作為輸入。

限制與取捨

如果獨立 bot 身分可以滿足產品需求，請使用 Telegram 官方 Bot API。它專為 bot 設計，也不需要維護使用者帳號 session。

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

另外，不要把網站使用的 Telegram Login 與這裡的憑證選擇混為一談。Telegram 目前的網站登入系統採用 OpenID Connect，並有自己的用戶端設定；它既不能取代 Bot API token，也不能取代 MTProto 使用者帳號授權。

常見問題

Telegram API ID 和 bot token 是同一個東西嗎？

不是。API ID 用來識別參與 Telegram API 授權的用戶端應用程式，bot token 則讓某一個 bot 透過 Bot API 完成身分驗證。兩者的核發位置不同，控制的身分也不同。

已經有 bot token，還需要 API ID 和 API hash 嗎？

呼叫一般 HTTP Bot API 時不需要，只要使用該 bot 的 token。如果整合功能要透過用戶端 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 code 登入嗎？

不可以。Telegram 的 auth.exportLoginToken 請求同時包含 api_id 和 api_hash。QR code 是使用者核准登入的步驟，不能取代應用程式憑證。

UnifyPort 可以用 BotFather token 連接 Telegram 嗎？

一般 Telegram 帳號授權流程不可以。驗證碼和 QR code 模式都使用 provider_data.api_id 和 provider_data.api_hash，驗證碼模式還需要帳號手機號碼。如果目標身分是 bot，請直接使用官方 Bot API。

下一步

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

來源

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