API 參考

渠道說明

Telegram 接入授權

你可以透過驗證碼、掃碼或現有工作階段連接 Telegram。先選擇一種方式,再依步驟完成授權。

選擇授權方式

code

驗證碼流程:平台發起驗證碼請求,使用者經 SMS 或者 App 內收到再回傳返。

  1. 1. POST /v1/accounts,指定 provider=telegram、auth_mode=code 同 provider_data.phone。provider_data 入面嘅 api_id、api_hash 可選;唔傳就用平台預設應用程式憑證。
  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. 授權成功後先檢查 runtime_status,只有仍需啟動時先呼叫 POST /v1/accounts/{account_id}/runtime/start。
  • provider_data.api_id — 可選,喺 my.telegram.org 取得嘅 Telegram App ID。唔傳就用平台預設應用程式憑證;使用自有應用程式時,請將同一應用程式嘅 api_id 同 api_hash 以字串成對提供。
  • provider_data.api_hash — 可選,喺 my.telegram.org 取得嘅 Telegram App Hash。唔傳就用平台預設應用程式憑證;使用自有應用程式時,請將同一應用程式嘅 api_id 同 api_hash 以字串成對提供。
  • 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. 授權成功後先檢查 runtime_status,只有仍需啟動時先呼叫 POST /v1/accounts/{account_id}/runtime/start。
  • provider_data.api_id — 可選,喺 my.telegram.org 取得嘅 Telegram App ID。唔傳就用平台預設應用程式憑證;使用自有應用程式時,請將同一應用程式嘅 api_id 同 api_hash 以字串成對提供。
  • provider_data.api_hash — 可選,喺 my.telegram.org 取得嘅 Telegram App Hash。唔傳就用平台預設應用程式憑證;使用自有應用程式時,請將同一應用程式嘅 api_id 同 api_hash 以字串成對提供。

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. 授權成功後先檢查 runtime_status,只有仍需啟動時先呼叫 POST /v1/accounts/{account_id}/runtime/start。
  • params.session_url — 已有 Telegram 會話嘅 URL 或參考。

備註

  • Telegram 嘅 code、qrcode、session 三種授權模式都唔需要呼叫方自行提供 api_id 同 api_hash,唔傳就用平台預設應用程式憑證。使用自有應用程式時,請喺 provider_data 將同一 Telegram 應用程式嘅兩項憑證以字串成對提供。
  • 二階段密碼每次試都係無狀態。打錯密碼就先 cancel,再重新行 /auth/qr/start 或 /auth/start。
  • QR token 大概 30 秒就過期。過期再叫一次 qr/start 就更新到 — 前端記住重新畫 QR。
  • 帳號設定階段就會自動 inject 個 webhook URL,授權狀態變化同登入事件會同入站訊息行同一個 webhook 端點。