Developer Docs

One Port, Every Channel.

Connect every messaging route through one unified API, with standard Webhook events for inbound traffic.

Provider Guide

Telegram authorization

Telegram supports code, QR code, and session import. All three flows go through /v1/accounts and then /v1/accounts/{id}/auth/session/*.

code

auth_mode

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

Steps

  1. 1POST /v1/accounts with provider=telegram, auth_mode=code, and provider_data containing api_id, api_hash, and phone.
  2. 2POST /v1/accounts/{account_id}/auth/session/start to ask Telegram to dispatch the verification code.
  3. 3Once the user receives the code, POST /v1/accounts/{account_id}/auth/session/code with the code value.
  4. 4If the account has 2FA, the response status becomes awaiting_password — POST /v1/accounts/{account_id}/auth/session/password to submit it.
  5. 5On success, POST /v1/accounts/{account_id}/runtime/start to bring the account online.

Required fields

  • provider_data.api_idrequired

    Telegram App ID from my.telegram.org. Required for every Telegram flow.

  • provider_data.api_hashrequired

    Telegram App Hash from my.telegram.org. Required for every Telegram flow.

  • provider_data.phonerequired

    E.164 phone number for the account. Required only for the code flow.

qrcode

auth_mode

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

Steps

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

Required fields

  • provider_data.api_idrequired

    Telegram App ID from my.telegram.org. Required for every Telegram flow.

  • provider_data.api_hashrequired

    Telegram App Hash from my.telegram.org. Required for every Telegram flow.

session

auth_mode

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

Steps

  1. 1POST /v1/accounts with provider=telegram, auth_mode=session.
  2. 2POST /v1/accounts/{account_id}/auth/session/import with params.session_url pointing to the downloadable .session file.
  3. 3Once the import response confirms the session is valid, POST /v1/accounts/{account_id}/runtime/start.

Required fields

  • params.session_urlrequired

    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 qr/start or session/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.