← API 参考
渠道方对比

Telegram 接入授权

Telegram 支持 code（验证码）、qrcode（二维码）和 session（会话导入）三种 auth_mode，统一走 /v1/accounts 与标准授权接口：/auth/start、/auth/code、/auth/password、/auth/qr/start、/auth/qr/check、/auth/session。

code

验证码流程：平台发起验证码请求，用户通过短信或 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. 若账号开启了两步验证，状态会变成 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 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. 导入返回会话有效后，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 端点。