← API 參考
渠道方對比

Telegram 接入授權

Telegram 支援 code（驗證碼）、qrcode（QR Code）與 session（會話匯入）三種 auth_mode，統一走 /v1/accounts 與標準授權介面：/auth/start、/auth/code、/auth/password、/auth/qr/start、/auth/qr/check、/auth/session。

code

驗證碼流程：平台發起驗證碼請求，使用者經由 SMS 或 App 內收到後回傳。

  1. 1. POST /v1/accounts，provider=telegram、auth_mode=code，provider_data 內含 api_id、api_hash、phone。
  2. 2. POST /v1/accounts/{account_id}/auth/start，請 Telegram 下發驗證碼。
  3. 3. 使用者拿到驗證碼後 POST /v1/accounts/{account_id}/auth/code 送出驗證碼。
  4. 4. 若帳號啟用二階段驗證，status 會變為 awaiting_password — 呼叫 POST /v1/accounts/{account_id}/auth/password 送出密碼。
  5. 5. 成功後呼叫 POST /v1/accounts/{account_id}/runtime/start 讓帳號上線。
  • provider_data.api_id — 從 my.telegram.org 申請到的 Telegram App ID。Telegram 三種流程都必填。
  • provider_data.api_hash — 從 my.telegram.org 申請到的 Telegram App Hash。Telegram 三種流程都必填。
  • provider_data.phone — 帳號綁定的 E.164 手機號。只有 code 流程需要。

qrcode

QR Code 流程：取得 QR token，請使用者於 Telegram App 內掃碼。

  1. 1. POST /v1/accounts，provider=telegram、auth_mode=qrcode，provider_data 提供 api_id / api_hash。
  2. 2. POST /v1/accounts/{account_id}/auth/qr/start，回應中提供要顯示的 QR token。
  3. 3. 輪詢 POST /v1/accounts/{account_id}/auth/qr/check 直到 status=authorized。QR 約 30 秒會過期，過期再呼叫一次 qr/start 即可更新。
  4. 4. 成功後呼叫 POST /v1/accounts/{account_id}/runtime/start。
  • provider_data.api_id — 從 my.telegram.org 申請到的 Telegram App ID。Telegram 三種流程都必填。
  • provider_data.api_hash — 從 my.telegram.org 申請到的 Telegram App Hash。Telegram 三種流程都必填。

session

會話匯入流程：將既有授權會話匯入 UnifyPort。

  1. 1. POST /v1/accounts，provider=telegram、auth_mode=session。
  2. 2. POST /v1/accounts/{account_id}/auth/session，params.session_url 指向可下載的 .session 檔。
  3. 3. import 回應確認 session 有效後，POST /v1/accounts/{account_id}/runtime/start。
  • params.session_url — 既有 Telegram 會話的 URL 或參考。

備註

  • 二階段密碼每次嘗試都是無狀態。輸錯密碼時請先 cancel，再重新走 /auth/qr/start 或 /auth/start。
  • QR token 約 30 秒就過期。過期後再呼叫一次 qr/start 即可更新 — 前端需重新繪製 QR。
  • 帳號設定階段就會自動注入 webhook URL，授權狀態變化與登入事件會與入站訊息走同一個 webhook 端點。