← All posts
Comparison

Telegram API ID and API Hash vs Bot Token: Which Credentials Do You Need?

A Telegram bot token authenticates one bot to the HTTP Bot API; it does not sign in a personal Telegram account. An API ID and API hash identify a client application and are required when authorizing a user account through Telegram’s MTProto API, including code and QR login. Choose the credential by the identity you need to control: bot identity → bot token; existing user account → API ID and API hash.

Key takeaways

  • Get a bot token from @BotFather when your integration should act as a separate Telegram bot.
  • Get an API ID and API hash from my.telegram.org when your application needs to authorize an existing Telegram user account.
  • A bot token cannot replace an API ID/API hash, and scanning a QR code does not remove the app-credential requirement.
  • Keep bot tokens, API hashes, login codes, and authorized session material out of source control and logs.
  • For a regular Telegram account in UnifyPort, follow the Telegram authorization guide with your API ID and API hash; do not paste a BotFather token into that flow.

Telegram API ID and API hash vs bot token

The names are easy to mix up because all three values grant some kind of Telegram access. They belong to different API surfaces and authenticate different identities.

What you are buildingCredentialWhere it comes fromIdentity after authorization
An HTTP Bot API integrationBot token@BotFatherA separate bot account
A client that signs in a Telegram userAPI ID + API hash, then code, QR, or another supported user-login stepmy.telegram.org → API development toolsThe authorized user account
A user-account connection in UnifyPortAPI ID + API hash for code or QR authorizationmy.telegram.orgThe Telegram account that approves the login

Telegram’s official bot tutorial is explicit: a bot token authenticates the bot, not your account. The token is sent to endpoints such as https://api.telegram.org/bot<TOKEN>/getMe, and it can be revoked in @BotFather.

The API ID and API hash belong to a Telegram client application instead. Telegram issues them after you sign in at my.telegram.org and complete the API development tools form. Its user-authorization methods then combine those app credentials with a user-controlled login step. For example, auth.sendCode accepts the phone number, api_id, and api_hash; a successful authorization binds the resulting client session to the user.

That is the decisive distinction: the bot token selects a bot identity, while the API ID/API hash identify the client participating in a user-account login.

Which credential should you choose?

Start with the identity that must receive or send the messages.

Choose a bot token when the bot identity is acceptable

Use the official Bot API when users will intentionally chat with a bot username, add that bot to groups, or use bot-specific features. Create the bot with @BotFather, store its token like a password, and use Bot API updates through polling or a Telegram webhook.

This is usually the cleanest path for a Telegram-only product designed around a bot. Telegram owns the bot lifecycle, the API is official, and you do not need to authorize a personal user session. Our comparison of Telegram native chat automation and a cross-channel inbound queue explains where that official model fits well.

Choose an API ID and API hash when the user account is the identity

Use Telegram’s client API path when the product must authorize an existing Telegram account rather than create a new bot identity. The application first identifies itself with the API ID and API hash. The account owner then completes the user-login step, such as a verification code, QR approval, and 2FA when enabled.

Do not interpret the API ID/API hash as a logged-in account by themselves. They identify the application; the user-controlled authorization produces the account session. Likewise, a phone number or QR image is not a replacement for the app credentials.

If your end goal is to route messages from an existing Telegram account into another system, the Telegram-to-Slack relay build log shows the downstream webhook architecture after the account is connected.

How to get an API ID and API hash from my.telegram.org

Telegram’s official process is short, but the page names matter:

  1. Register and keep an active phone number in an official Telegram app.
  2. Open my.telegram.org and complete the account sign-in at /auth.
  3. Choose API development tools.
  4. Complete the application form.
  5. Store the resulting api_id and api_hash in your server-side credential store.

Telegram currently allows one API ID per phone number and warns that client libraries are monitored for abuse. Use your own application credentials for a released application, follow Telegram’s API Terms of Service, and never copy the limited sample API ID from Telegram’s open-source clients into production.

Does QR login still require the API ID and API hash?

Yes. QR changes how the user approves the login; it does not change which client application is requesting it.

Telegram’s official QR flow starts with auth.exportLoginToken, whose parameters include api_id and api_hash. The client renders the returned token as a tg://login QR code, and an already signed-in Telegram app scans and accepts it. Telegram says that login token usually expires after about 30 seconds, so an expired QR must be refreshed.

This is why “QR or API credentials?” is the wrong decision. For user authorization, QR is an approval method used with the application credentials.

Where UnifyPort fits

UnifyPort connects an ordinary Telegram account through an unofficial interface; it does not create a Telegram bot. Its code and QR authorization flows therefore use the user-account credential path.

For code authorization, create the account with provider: "telegram", auth_mode: "code", and these real fields:

{
  "provider": "telegram",
  "auth_mode": "code",
  "provider_data": {
    "api_id": 12345678,
    "api_hash": "0123456789abcdef0123456789abcdef",
    "phone": "+886912345678"
  }
}

For QR authorization, provider_data.api_id and provider_data.api_hash are still required, while the account owner approves the short-lived QR in Telegram. The Telegram authorization API reference lists the exact code, QR, 2FA, and session steps.

After authorization, inbound Telegram messages can arrive as the same signed message.received event used by other connected providers. The BotFather token is not an input to this regular-account flow.

Limitations and trade-offs

Use Telegram’s official Bot API when a separate bot identity meets the product requirement. It is purpose-built for bots and avoids maintaining a user-account session.

Use a client/user-account flow only when an existing account is genuinely required. Authorization creates sensitive session material, the account remains subject to Telegram’s rules, and API access does not grant permission for spam or other prohibited behavior. UnifyPort does not turn a bot token into a user session, create an API ID on your behalf, or remove Telegram’s platform controls.

Also keep Telegram Login for websites separate from this decision. Telegram’s current web-login system is an OpenID Connect flow with its own client configuration; it is not a substitute for either a Bot API token or MTProto user-account authorization.

FAQ

Is a Telegram API ID the same as a bot token?

No. An API ID identifies a client application participating in Telegram API authorization. A bot token authenticates one bot to the Bot API. They are issued in different places and control different identities.

Do I need an API ID and API hash if I already have a bot token?

Not for normal HTTP Bot API calls. You need the bot token for that bot. You need an API ID and API hash when your integration authorizes a Telegram user through the client API; a bot token cannot sign in that user.

Where do I find my.telegram.org/auth?

Open https://my.telegram.org/ and sign in with your Telegram phone number. After authentication, choose API development tools to create or view the API ID and API hash associated with the number.

Can I use QR login without an API hash?

No. Telegram’s auth.exportLoginToken request includes both api_id and api_hash. The QR is the user’s approval step, not a replacement for the application credentials.

Can UnifyPort connect Telegram with a BotFather token?

Not in its regular Telegram account authorization flow. Code and QR modes use provider_data.api_id and provider_data.api_hash; code mode also uses the account phone number. Use the official Bot API directly when your target identity is a bot.

Next step

If you need to connect an existing Telegram account, open the Telegram authorization guide and choose the code or QR flow. If you only need a bot identity, stay with @BotFather and the official Bot API.

Sources

Sources and product documentation verified on 2026-07-19.