API 参考

渠道说明

Telegram 接入授权

你可以通过验证码、扫码或已有会话连接 Telegram。先选择一种方式,再按对应步骤完成授权。

选择授权方式

code

验证码流程:平台发起验证码请求,用户通过短信或 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. 若账号开启了两步验证,状态会变成 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 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。
  • 账号配置阶段就会自动注入 webhook URL,授权状态变化和登录事件会与入站消息走同一个 webhook 端点。