將 Telegram 個人帳號接上 Webhook：驗證碼與 QR Code 設定

要將既有 Telegram 個人帳號接上 Webhook，請先取得自己應用程式的 api_id 與 api_hash，在授權前註冊 Webhook，再於 UnifyPort 建立 Telegram 訊息帳號，最後完成驗證碼或 QR Code 流程。驗證碼登入還需要帳號電話號碼，並可能要求兩步驟驗證；QR Code 登入仍需要 API 憑證，但由帳號持有人在已登入的 Telegram App 中確認。

重點整理

• 個人帳號授權使用 api_id 與 api_hash，不是 BotFather 發出的 bot token。
• 先建立 Webhook，授權狀態與新訊息才有可投遞的接收端。
• 可以輸入 Telegram 登入碼時選 auth_mode: "code"；方便由既有 App 掃描確認時選 auth_mode: "qrcode"。
• api_hash、登入碼、兩步驟驗證密碼、QR 內容、API key 與 signing_secret 都是機密資料。
• 授權後只處理簽章驗證成功，而且方向為 inbound 的 message.received。

若仍在判斷憑證類型，先閱讀 Telegram API ID、API hash 與 bot token 比較。

Telegram 個人帳號 Webhook 的完整設定流程

整體可分為 Telegram 應用程式憑證、你控制的接收端、UnifyPort 訊息帳號，以及使用者參與的授權步驟。將四個邊界分開，發生錯誤時會更容易定位。

1. 取得自己的 Telegram 應用程式憑證

Telegram 的官方應用程式設定文件指出，使用者授權需要 api_id 與 api_hash。請從 my.telegram.org 的 API development tools 建立自己的憑證，並將 hash 放在密鑰管理服務，不要寫入程式碼版本庫或日誌。

這和 Bot API 是不同的身份模型。Telegram 將官方 Bot API描述為供 bot 身份使用的 HTTP 介面。若你需要獨立 bot 身份與 bot 專屬功能，應採用官方路徑；若要連接既有個人帳號，或讓它和其他通訊平台共用入站處理器，則可使用本文的非官方介面流程。

若專案承接了範例或已公開的應用程式 ID，請先確認來源。API_ID_PUBLISHED_FLOOD 復原清單說明如何更換不適合的憑證，同時保護新的值。

2. 登入前先註冊簽章 Webhook

UnifyPort 沒有提供讀取訊息歷史的 REST API，也不保證重送遺漏的訊息 payload，因此接收端必須先就緒，並在事件抵達時保存必要資料。

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"$PUBLIC_WEBHOOK_URL\",
    \"status\": \"active\",
    \"subscribed_events\": [\"message.received\", \"account.auth.required\", \"account.auth.succeeded\", \"account.auth.failed\", \"account.status.updated\"],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\"
  }"

完整欄位請查看建立 Webhook endpoint。啟用簽章後，必須用原始 request body 驗證 X-Device-Signature。其值是 X-Device-Timestamp、一個句點與原始 body 的 HMAC-SHA256 十六進位結果。Webhook HMAC、重送與重播防護進一步說明時間戳記、冪等與重試處理。

3A. 驗證碼授權

建立帳號時帶入 provider_data.api_id、provider_data.api_hash 與 provider_data.phone：

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Telegram Support\",
    \"provider\": \"telegram\",
    \"region\": \"global\",
    \"status\": \"active\",
    \"auth_mode\": \"code\",
    \"capabilities\": [\"send_message\", \"receive_message\"],
    \"provider_data\": {
      \"api_id\": $TELEGRAM_API_ID,
      \"api_hash\": \"$TELEGRAM_API_HASH\",
      \"phone\": \"$TELEGRAM_PHONE\"
    }
  }"

保存回應中的帳號 id，啟動流程後再提交 Telegram 傳來的登入碼：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/code" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"code\": \"$TELEGRAM_LOGIN_CODE\"}"

Telegram 的官方使用者授權文件包含兩步驟驗證分支。只有狀態成為 awaiting_password 時，才將密碼送到 /v1/accounts/{account_id}/auth/password，而且不得記錄密碼。

3B. QR Code 授權

QR 模式建立帳號時使用 auth_mode: "qrcode"，保留 provider_data.api_id 與 provider_data.api_hash，不需要 phone 欄位。啟動流程：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

使用 GET /v1/accounts/{account_id}/auth 讀取狀態，或用 POST /v1/accounts/{account_id}/auth/qr/check 檢查結果。只向帳號持有人顯示 auth_payload.qr_code。Telegram 的官方 QR 登入規格要求由已登入的 Telegram App 掃描並接受，而且過期 token 必須重新產生；API 若提供較新的 payload，前端也應更新 QR Code。

所有分支都可在 Telegram 授權 API Reference查看。

4. 確認授權並接收訊息

收到 account.auth.succeeded 後，以 GET /v1/accounts/{account_id} 核對帳號。授權成功通常會自動啟動 runtime，但應讀取實際 runtime_status，不要假設連線已可用。

收到 Telegram 訊息時，Webhook 會送出統一 envelope：

{
  "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",
      "text": "Can you check my order?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z"
    },
    "event": { "kind": "message_received" }
  }
}

先驗證簽章，再要求 type 為 message.received、data.message.direction 為 inbound。以事件 ID 實作冪等，對合法投遞回覆 2xx，並保存工作流程需要的欄位。

限制與取捨

個人帳號連線不適合取代所有 bot 情境。需要 bot 身份、bot 指令與 Telegram 的 bot 專屬介面時，官方 Bot API 更合適；需要既有個人帳號，或希望同一接收器日後加入 WhatsApp、LINE、TikTok、Zalo、X，則 UnifyPort 流程更符合需求。

UnifyPort 是非官方介面，上游行為與可用性可能因帳號而不同。使用時仍須遵守 Telegram API Terms of Service，以及自身的資安與隱私義務。憑證、QR 內容與 session 資料只能交給正在完成登入的帳號持有人。

常見問題

需要 Telegram bot token 嗎？

不需要。個人帳號使用 api_id 與 api_hash；bot token 屬於官方 Bot API。

QR Code 登入還需要 API ID 和 API hash 嗎？

需要。UnifyPort QR 授權仍要求 provider_data.api_id 與 provider_data.api_hash，只是確認登入的方法不同。

被要求兩步驟驗證時怎麼辦？

等待狀態成為 awaiting_password，再送到 /v1/accounts/{account_id}/auth/password。不要寫入日誌，完成後不要保留明文。

Webhook 要在連線前還是連線後建立？

連線前。授權狀態與訊息都透過事件送達，遺漏的訊息 payload 不保證重送。

哪個事件應啟動入站流程？

使用 message.received，並確認 data.message.direction 是 inbound。解析前先完成 HMAC 驗證。

下一步

開啟 Telegram 授權指南，選擇驗證碼或 QR Code。先保護 Webhook，再建立訊息帳號並完成授權。

資料來源

官方資料核對日期：2026-08-13。

• Telegram：建立應用程式
• Telegram：QR Code 登入
• Telegram：使用者授權
• Telegram Bot API