Channels

Telegram authorization

Connect Telegram using a verification code, a QR scan or an existing session. Choose a method below and follow its authorization steps.

Choose an authorization method

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

1. POST /v1/accounts with provider=telegram, auth_mode=code, and provider_data.phone. The api_id and api_hash fields in provider_data are optional; if omitted, the platform uses its default app credentials.
2. POST /v1/accounts/{account_id}/auth/start to ask Telegram to dispatch the verification code.
3. Once the user receives the code, POST /v1/accounts/{account_id}/auth/code with the code value.
4. If the account has 2FA, the response status becomes awaiting_password — POST /v1/accounts/{account_id}/auth/password to submit it.
5. After authorization succeeds, check runtime_status first. Call POST /v1/accounts/{account_id}/runtime/start only if a start is still needed.

provider_data.api_id — Optional Telegram App ID from my.telegram.org. If omitted, the platform uses its default app credentials. To use your own app, provide api_id and api_hash together as strings from the same app.
provider_data.api_hash — Optional Telegram App Hash from my.telegram.org. If omitted, the platform uses its default app credentials. To use your own app, provide api_id and api_hash together as strings from the same app.
provider_data.phone — E.164 phone number for the account. Required only for the code flow.

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

1. POST /v1/accounts with provider=telegram and auth_mode=qrcode. The api_id and api_hash fields in provider_data are optional; if omitted, the platform uses its default app credentials.
2. POST /v1/accounts/{account_id}/auth/qr/start — the response contains the QR token to render.
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. After authorization succeeds, check runtime_status first. Call POST /v1/accounts/{account_id}/runtime/start only if a start is still needed.

provider_data.api_id — Optional Telegram App ID from my.telegram.org. If omitted, the platform uses its default app credentials. To use your own app, provide api_id and api_hash together as strings from the same app.
provider_data.api_hash — Optional Telegram App Hash from my.telegram.org. If omitted, the platform uses its default app credentials. To use your own app, provide api_id and api_hash together as strings from the same app.

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

1. POST /v1/accounts with provider=telegram, auth_mode=session.
2. POST /v1/accounts/{account_id}/auth/session with params.session_url pointing to the downloadable .session file.
3. After authorization succeeds, check runtime_status first. Call POST /v1/accounts/{account_id}/runtime/start only if a start is still needed.

params.session_url — URL or reference for an existing Telegram session export.

For all three Telegram auth modes (code, qrcode, and session), you can omit api_id and api_hash to use the platform default app credentials. To use your own app, provide both fields in provider_data as strings from the same Telegram app.
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.