← API Reference
Provider Guide

Telegram authorization

Telegram supports code, QR code, and session import. All three flows use /v1/accounts plus the standard auth endpoints: /auth/start, /auth/code, /auth/password, /auth/qr/start, /auth/qr/check, and /auth/session.

code

Verification code flow: server requests a code from Telegram, the user receives it via SMS or in-app, then submits it back.

  1. 1. POST /v1/accounts with provider=telegram, auth_mode=code, and provider_data containing api_id, api_hash, and phone.
  2. 2. POST /v1/accounts/{account_id}/auth/start to ask Telegram to dispatch the verification code.
  3. 3. Once the user receives the code, POST /v1/accounts/{account_id}/auth/code with the code value.
  4. 4. If the account has 2FA, the response status becomes awaiting_password — POST /v1/accounts/{account_id}/auth/password to submit it.
  5. 5. On success, POST /v1/accounts/{account_id}/runtime/start to bring the account online.
  • provider_data.api_id — Telegram App ID from my.telegram.org. Required for every Telegram flow.
  • provider_data.api_hash — Telegram App Hash from my.telegram.org. Required for every Telegram flow.
  • provider_data.phone — E.164 phone number for the account. Required only for the code flow.

qrcode

QR code flow: request a QR token and let the user scan it inside the Telegram app.

  1. 1. POST /v1/accounts with provider=telegram, auth_mode=qrcode, and provider_data.api_id / api_hash.
  2. 2. POST /v1/accounts/{account_id}/auth/qr/start — the response contains the QR token to render.
  3. 3. Poll POST /v1/accounts/{account_id}/auth/qr/check until status is authorized. QR tokens expire after about 30 seconds, so refresh by calling qr/start again on expiry.
  4. 4. On success, POST /v1/accounts/{account_id}/runtime/start.
  • provider_data.api_id — Telegram App ID from my.telegram.org. Required for every Telegram flow.
  • provider_data.api_hash — Telegram App Hash from my.telegram.org. Required for every Telegram flow.

session

Session import flow: bring an already-authenticated Telegram identity into UnifyPort by importing an existing session.

  1. 1. POST /v1/accounts with provider=telegram, auth_mode=session.
  2. 2. POST /v1/accounts/{account_id}/auth/session with params.session_url pointing to the downloadable .session file.
  3. 3. Once the import response confirms the session is valid, POST /v1/accounts/{account_id}/runtime/start.
  • params.session_url — URL or reference for an existing Telegram session export.

Notes

  • 2FA passwords are stateless per attempt. If submitting the wrong password, cancel the session and call /auth/qr/start or /auth/start again.
  • QR tokens expire after ~30 seconds. Call qr/start again to refresh — the UI should regenerate the displayed QR each time.
  • The webhook URL is injected automatically when the account is configured. Auth state transitions and login events arrive through the same webhook endpoint as inbound messages.