渠道说明
Telegram 接入授权
你可以通过验证码、扫码或已有会话连接 Telegram。先选择一种方式,再按对应步骤完成授权。
选择授权方式
code
验证码流程:平台发起验证码请求,用户通过短信或 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. 若账号开启了两步验证,状态会变成 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 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。
- 账号配置阶段就会自动注入 webhook URL,授权状态变化和登录事件会与入站消息走同一个 webhook 端点。