將 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，授權狀態和新訊息才有接收端。
• 可以輸入登入碼時選 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 放入密鑰管理服務，切勿寫入程式碼 repository 或 log。

這與 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 訊息會使用統一 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 command 和 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，只是確認方式不同。

Telegram 要求兩步驗證時怎樣處理？

等待狀態成為 awaiting_password，再提交至 /v1/accounts/{account_id}/auth/password。不要寫入 log，完成後不要保留明文。

Webhook 應在連接帳戶前還是之後建立？

之前。授權狀態和訊息都經事件送達，遺漏的訊息 payload 不保證重送。

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

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

下一步

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

資料來源

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

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