渠道說明
Telegram 接入授權
你可以透過驗證碼、掃碼或現有工作階段連接 Telegram。先選擇一種方式,再依步驟完成授權。
選擇授權方式
code
驗證碼流程:平台發起驗證碼請求,使用者經 SMS 或者 App 內收到再回傳返。
- 1. POST /v1/accounts,指定 provider=telegram、auth_mode=code 同 provider_data.phone。provider_data 入面嘅 api_id、api_hash 可選;唔傳就用平台預設應用程式憑證。
- 2. POST /v1/accounts/{account_id}/auth/start,叫 Telegram 落驗證碼。
- 3. 使用者收到驗證碼後,POST /v1/accounts/{account_id}/auth/code 把驗證碼送返。
- 4. 帳號開咗二階段驗證嘅話,status 會變 awaiting_password — 叫 POST /v1/accounts/{account_id}/auth/password 送密碼。
- 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. POST /v1/accounts,指定 provider=telegram、auth_mode=qrcode。provider_data 入面嘅 api_id、api_hash 可選;唔傳就用平台預設應用程式憑證。
- 2. POST /v1/accounts/{account_id}/auth/qr/start,回應入面就會有要顯示嘅 QR token。
- 3. 輪詢 POST /v1/accounts/{account_id}/auth/qr/check,等到 status=authorized。QR 大概 30 秒過期,過期再叫一次 qr/start 就更新。
- 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. POST /v1/accounts,provider=telegram、auth_mode=session。
- 2. POST /v1/accounts/{account_id}/auth/session,params.session_url 指去個可以下載嘅 .session 檔。
- 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 端點。