Telegram API: How to Get Your API Key and Bot Token

Table of Contents

Getting your credentials

01
Which Telegram API do you need

02
Get your api_id and api_hash

03
Get a bot token from BotFather

Authentication & comparison

04
Log in with a QR code (Devices flow)

05
Phone number sign-in and the 2FA wall

06
What each API lets you do

Limits & reliability

07
It's free, here's where it breaks

08
Sending limits, in numbers

09
Errors you need to know

Use cases & Unipile

10
CRM and ATS use cases

11
Choosing an MTProto library

12
Connect an existing accountBest

FAQ
Frequently Asked Questions

Telegram API guide

How to Get Telegram API Access: api_id, api_hash and Bot Tokens

The Telegram API is not one API, it is three: the Bot API, the Client API (MTProto), and the Gateway API. This guide shows you exactly where to get your credentials, what api_id, api_hash and a BotFather bot token each unlock, and the third option most guides skip: connecting an existing Telegram user account through Unipile without writing a single line of MTProto code.

Build with Unipile
See the docs

hosted-auth.js

// Connect an existing Telegram user account
// No api_id / api_hash to manage yourself
const link = await unipile.hostedAuth.create({
  providers: ["TELEGRAM"],
  expiresOn: "2026-12-31T23:59:59.000Z"
});

// User logs in with QR code or their session
// Account status becomes "connected"

account.status: "connected"

Getting started

The 3 Telegram APIs, and which one you need

Most guides talk about "the Telegram API" as if it were a single thing. It is not. Telegram ships three distinct APIs, each with its own credentials, its own rules and its own limits. Picking the wrong one is the fastest way to waste a week building against the wrong door.

Bot API

Do you need an automated bot that reacts to commands and messages?

Needs: a bot token from BotFather

HTTP API, no MTProto knowledge required
Acts as a bot account, not a human
Free to use

Client API (MTProto)

Do you need to build a full client that acts as a real Telegram user?

Needs: api_id + api_hash from my.telegram.org

Raw MTProto protocol, you implement the client
Acts as a real user account
Free, one api_id per phone number

Gateway API

Do you only need to send verification codes for phone number authentication?

Needs: a Gateway API account

OTP delivery only, not general messaging
Launched separately from Bot API and Client API
Out of scope for this guide

None of these fit
Skip building your own MTProto client
Unipile connects an existing Telegram user account through Telegram's own Devices feature, QR code login or Hosted Auth. No api_id, no api_hash, no bot limitations.

Build it with Unipile

Client API / MTProto

Get your Telegram API credentials: api_id and api_hash

This is the real "get Telegram API" path most people search for and never find documented plainly: my.telegram.org, section API development tools. Here is the exact walk, end to end.

1

Go to my.telegram.org and log in
You need an active Telegram account, verified with the same phone number you will authenticate with. Enter your phone number and the login code sent to your Telegram app.

2

Open "API development tools"
This section lives under your my.telegram.org account settings. It is the only official place where Telegram issues Client API credentials.

3

Fill in the app form
App title, short name and platform. These fields describe the application that will use MTProto, they do not need to match a public product name.

4

Get your api_id and api_hash
Telegram issues the pair immediately. api_id is a numeric identifier, api_hash is the matching secret. Store both like any other credential, they authenticate your MTProto client against Telegram's servers.

One constraint to plan around
A phone number can hold only one api_id. If you need several apps or several environments, you need several phone numbers, or you reuse the same api_id across your codebase. There is no self-service way to issue a second api_id on the same number.

.env

# From my.telegram.org, API development tools
TELEGRAM_API_ID=1234567
TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef

# One api_id per phone number, store it securely

Build your account connection with Unipile instead

Bot API

Get a bot token via BotFather

The other path into the Telegram API needs no my.telegram.org account, no api_id, no api_hash. It runs entirely inside a chat with Telegram's own bot, @BotFather.

1

Open a chat with @BotFather
Search "BotFather" inside Telegram. It is the official bot Telegram uses to issue and manage every other bot on the platform.

2

Send /newbot
BotFather walks you through creating a new bot directly in the chat, no dashboard, no form.

3

Choose a name and a username
The display name can be anything. The username must be unique and end in bot, for example my_support_bot.

4

Copy the bot token
BotFather replies with your token immediately. Keep it secret, it authenticates every Bot API call your bot makes.

The current Bot API is version 10.2, published July 14, 2026 (source: core.telegram.org/bots/api). Every bot token works against this same versioned HTTP API.

terminal

# Test your bot token against the Bot API
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

# Sample response
{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "username": "my_support_bot"
  }
}

Comparison

What each Telegram API actually lets you do

Four ways to touch Telegram, four very different sets of permissions. Here is what each one connects to, what credentials it needs, and where it stops.

Criteria	Bot API	Client API (MTProto)	Gateway API	Unipile
What you connect	A bot account	A real user account you build the client for	Nothing, OTP delivery only	An existing real user account
Credentials needed	Bot token from BotFather	api_id + api_hash from my.telegram.org	Gateway API account	QR code login or Hosted Auth (`providers: "TELEGRAM"`)
Sends/receives as a human account	No, acts as a bot	Yes	No	Yes
MTProto implementation	Not needed, HTTP only	You build it yourself	Not applicable	Handled by Unipile
Group participant management	Limited to bot permissions	Full, if you build it	Not applicable	Get, add, remove participants
Setup complexity	Low	High, you own the MTProto client	Low	Low, no MTProto to maintain
Cost	Free	Free	Not covered in this guide	Included in your Unipile plan
Ban risk on abuse	Token revocation	Permanent ban on flooding/spam	Not applicable	Mitigated with Unipile's rate-limit guidance

Bot API

ConnectsA bot account

CredentialsBot token (BotFather)

Acts as humanNo

SetupLow

CostFree

Client API (MTProto)

ConnectsA real user account (DIY client)

Credentialsapi_id + api_hash

Acts as humanYes

SetupHigh, MTProto self-built

CostFree

Gateway API

ConnectsNothing, OTP delivery only

CredentialsGateway API account

SetupLow

ScopeOut of this guide

Unipile

ConnectsAn existing real user account

CredentialsQR code or Hosted Auth

Acts as humanYes

SetupLow, no MTProto to maintain

GroupsGet / add / remove participants

What Unipile does not cover on Telegram
Channels, communities and broadcasts, chat theme, secret chats, contact / location / poll / event attachments, group administration (approve, promote, revoke), chat deletion, archiving, and voice or video calls. Unipile connects the account, it does not replicate every Telegram client feature.

Build your Telegram integration with Unipile

Pricing & limits

It's free. Here's where it breaks.

Both the Bot API and the Telegram API (MTProto) are free to use. There is no invoice, no per-message fee, no paid tier gating credentials. The catch is not money, it is behavior.

Flooding, spam and fake counters
Sending too fast, mass-messaging unrelated users, or artificially inflating view and reaction counters are the fastest way to trigger a permanent ban, on both the Bot API and the Client API.

Unofficial clients are watched
Any client built with your own api_id and api_hash is automatically placed under observation by Telegram's systems. Unusual patterns get flagged faster than on the official apps.

Unipile's own guidance to stay under the radar

Avoid brand-new Telegram accounts for automation, warm them up like any other channel

Ramp up message volume progressively instead of starting at full throughput

Keep at least 10 to 20 seconds between messages sent from the same account

Build safer messaging flows with Unipile

The Unipile approach

The third way: connect an existing Telegram account

Neither the Bot API nor a self-built MTProto client. Unipile's Telegram API connects an existing Telegram user account, through Telegram's own Devices feature, the same mechanism that lets you use Telegram on a new phone or a desktop app.

Login happens through a QR code scan, or through Hosted Auth with providers: "TELEGRAM" if you want a white-labelled connection flow inside your own product. Once connected, the account behaves as itself: it is not a bot, and it did not need an api_id or an api_hash issued from my.telegram.org.

This matters because it removes the two hardest parts of building on the Telegram API yourself: implementing MTProto, and managing sessions and reconnections when a device gets removed. If the Unipile device is removed from the account's Telegram sessions, Unipile detects it and the account status simply moves to disconnected, ready to be reconnected.

Send and receive direct messages as the real account

Manage group participants: get, add, remove

No channels, communities or broadcasts

No group administration (approve, promote, revoke), no voice or video calls

How to send a Telegram message with the API
Unipile Telegram API product page

Start building with Unipile

Linked account

ProviderTELEGRAM

Auth methodQR code / Hosted Auth

Statusconnected

Device removed from Telegramdisconnected

Resync supportedYes

Use cases

CRM and ATS use cases for the Telegram API

Once a Telegram account is connected as a real linked account, not a bot, two use cases show up repeatedly across Unipile customers: sales teams centralizing conversations, and recruiters reaching candidates where they already are.

CRM: unify Telegram conversations

Sales and support teams that already talk to leads and customers on Telegram do not want a separate app for it. By connecting the account through Unipile, every Telegram thread lands in the same inbox as email, LinkedIn or WhatsApp conversations, attached to the right contact record in the CRM.

Unified inboxLinked accountsContact sync

ATS: reach candidates on Telegram

In regions where Telegram is a primary messaging channel, recruiters connect their own Telegram account to reach candidates directly from the ATS, keep the full message history against the candidate profile, and hand off conversations between recruiters without losing context.

Candidate outreachMessage historyTeam handoff

Client API / MTProto

Log in with a QR code: the Devices flow, step by step

QR code login is the mechanism behind Telegram's Devices feature, the same one you use to add Telegram Desktop or Telegram Web to your account. It is also the flow Unipile operates on your behalf when it connects an existing Telegram user account. If you build it yourself, you are implementing a two-sided handshake between the device that already trusts the account and the device asking to join it, not a single request/response call. Here is exactly what happens between the two apps, method by method.

1

Request a login token
The device that wants to log in calls auth.exportLoginToken. Telegram answers with an auth.loginToken: a binary token plus an expiration, generally 30 seconds.

2

Encode it into a QR code
The token is encoded in base64url and placed inside a tg://login?token=<base64url> URL. That URL is what gets rendered on screen as a scannable QR code.

3

Scan from an already logged-in app
The Telegram app that is already authenticated scans the code and calls auth.acceptLoginToken with the decoded token.

4

Poll for the outcome
The device that is logging in receives an updateLoginToken update, then calls auth.exportLoginToken again to fetch the result of the scan.

5

Confirm, or migrate data center
If the data center matches, Telegram returns auth.loginTokenSuccess, the login is done. If it does not match, the response is auth.loginTokenMigrateTo, and the client must call auth.importLoginToken with the same token against the indicated data center.

qr-login-flow

// Device requesting the login
auth.exportLoginToken(api_id, api_hash)
// -> auth.loginToken { token, expires }

// Rendered as a QR code
tg://login?token=<base64url(token)>

// Already-authenticated device scans it
auth.acceptLoginToken(token)

// Logging-in device polls again
auth.exportLoginToken()
// -> auth.loginTokenSuccess
// or auth.loginTokenMigrateTo { dc_id }

Short window, plan the retry
The token is generally valid for only 30 seconds. If it expires before it is scanned, the client needs to call auth.exportLoginToken again and render a new code, not just retry the old one.

AUTH_TOKEN_INVALID
AUTH_TOKEN_EXPIRED
AUTH_TOKEN_ALREADY_ACCEPTED

This is precisely the exchange Unipile runs on your behalf when you connect a Telegram account through its Devices integration: the QR code, the token exchange, the data center handling, and the retry when a token expires. You call one endpoint, Unipile operates the MTProto conversation described above, including the case where the account being connected lives on a different data center than the one your app first talked to. That data center handling is easy to miss when you build the flow from scratch, because it only shows up for a subset of accounts, and it silently breaks logins for the ones it affects if the auth.loginTokenMigrateTo branch is not handled.

Build your QR login flow with Unipile

Client API / MTProto

Log in by phone number, and the 2FA wall

The classic phone-number sign-in is where most home-built Telegram clients get stuck. Not because it is complex, but because the flow silently branches the moment two-factor authentication is turned on, and the branch is not optional. A client that only implements the happy path (send code, validate code, done) works fine against a test account and then fails in production the first time it meets a real user with a cloud password enabled.

1

Send the login code
auth.sendCode sends the code to the phone number and returns an auth.sentCode object containing a phone_code_hash, required for the next call.

2

Validate the code
auth.signIn checks the code against the phone_code_hash. If the phone number has no account yet, Telegram returns auth.authorizationSignUpRequired instead of an authorization.

3

Hit the 2FA wall
If two-factor authentication is enabled on the account, auth.signIn answers with a 400 error: SESSION_PASSWORD_NEEDED. This is the expected response for any account with a cloud password, not a failure to handle as an exception.

4

Clear it with SRP
Finishing the login means running the SRP protocol: build an InputCheckPasswordSRP object from the account's password parameters, then call auth.checkPassword. Success returns an auth.authorization; a wrong password returns PASSWORD_HASH_INVALID.

Only official apps get Firebase SMS
Only Telegram's own official mobile applications are allowed to use Firebase-based SMS code delivery. Third-party applications have to route the code through another delivery channel, or write to sms@telegram.org to discuss access.

Errors to expect on this path

SESSION_PASSWORD_NEEDED
PASSWORD_HASH_INVALID
auth.authorizationSignUpRequired

Unipile's Telegram integration runs this entire branch for you: code delivery, the SESSION_PASSWORD_NEEDED check, and the SRP exchange when a cloud password is set, whether the account connects through a phone number, a QR code, or Hosted Auth. That includes the SMS delivery restriction above: because third-party applications cannot lean on Firebase-based delivery, this is one of the places where owning the phone-number flow yourself adds real operational weight, not just code, before you have sent a single message.

Sending limits

Telegram API rate limits, in numbers

Section 5 covered the behavior that gets accounts banned. Here are the actual documented ceilings on the Bot API side, and what it costs to raise them.

1/sec
Maximum messages to the same individual chat

20/min
Maximum messages inside a single group

~30/sec
Approximate ceiling for broadcasting across different chats

429
Error returned once any of these limits is crossed

Paid broadcasts raise the ceiling, with two conditions

Bots can enable paid broadcasts through BotFather, which raises the sending ceiling up to 1,000 messages per second. Messages sent above the free threshold cost 0.1 Telegram Star each. It is gated behind two account-level requirements, both need to be met at the same time.

100,000 Stars balance
100,000 monthly active users

Cross the individual, group or broadcast ceiling above and the Bot API answers with the 429 status covered in the error reference below, alongside the 420 FLOOD and FLOOD_WAIT_X codes used on the MTProto side. Both mechanisms exist for the same reason: to make you slow down before Telegram decides to slow you down for you.

These numbers are Bot API specific. For a connected user account, there is no published ceiling, only Unipile's own pacing guidance covered in it's free, here's where it breaks: warm up new accounts, ramp up progressively, keep at least 10 to 20 seconds between messages.

Error reference

Telegram API errors you need to know

MTProto errors follow the same three-digit shape as the HTTP status codes most developers already recognize, paired with a short machine-readable string. Here is the reference table, plus one error that only shows up for your end users, not for you. Knowing this list before you ship matters more than after: several of these codes, 303 and 420 in particular, are not exceptional failures, they are part of the normal operating conditions of an MTProto client and need to be handled in the code path, not logged and ignored.

Code	Meaning
303 SEE_OTHER	The request must be repeated, targeting a different data center.
400 BAD_REQUEST	The query contains errors. `API_ID_INVALID` is a common example of this code.
401 UNAUTHORIZED	The method requires a feature that is reserved to authorized users.
403 FORBIDDEN	Privacy violation, for example trying to write to a user who has blocked you.
404 NOT_FOUND	The requested object or method does not exist.
420 FLOOD / FLOOD_WAIT_X	The maximum number of allowed calls was exceeded, wait X seconds before retrying.

303 SEE_OTHERThe request must be repeated, targeting a different data center.

400 BAD_REQUESTThe query contains errors. API_ID_INVALID is a common example of this code.

401 UNAUTHORIZEDThe method requires a feature that is reserved to authorized users.

403 FORBIDDENPrivacy violation, for example trying to write to a user who has blocked you.

404 NOT_FOUNDThe requested object or method does not exist.

420 FLOOD / FLOOD_WAIT_XThe maximum number of allowed calls was exceeded, wait X seconds before retrying.

One more, on the end-user side
API_ID_PUBLISHED_FLOOD shows up for your end users when a published application reuses the example api_id shipped inside open-source sample code instead of requesting its own. Every application you publish needs its own api_id and api_hash from my.telegram.org.

A client built directly on the Client API (MTProto) needs to handle every one of these codes itself: retry against the correct data center on 303, back off on 420, and treat 401 and 403 as signals about account state rather than generic failures. Connecting an existing account through Unipile moves that error handling behind a single linked-account status, instead of a set of MTProto codes your own code needs to interpret correctly on every call.

Client API / MTProto

Choosing an MTProto library, and what it will not do for you

If you decide to build the Client API path yourself, you are not implementing MTProto from a spec sheet. A handful of libraries already speak the protocol, so the client itself is rarely the hard part. Picking one only solves part of the problem, and the part it solves is usually the smaller one.

Python

Telethon

A pure-Python MTProto implementation, built around async/await, with a client API that reads close to plain Python rather than raw protocol calls.

Python

Pyrogram

Another Python MTProto client, with its own take on session handling and a client surface designed to feel more like a conventional SDK than a protocol library.

Node.js

GramJS

The closest equivalent to Telethon for JavaScript and TypeScript codebases, implementing the same MTProto conversation for a Node.js runtime.

Official

TDLib

Telegram's own official library, written in C++, with bindings exposed for several languages. It implements the full MTProto stack the way Telegram's own apps do.

Which one fits usually comes down to the stack you already run rather than a feature comparison: a Python backend points toward Telethon or Pyrogram, a Node.js or TypeScript backend points toward GramJS, and a team that wants to stay as close as possible to Telegram's own official apps points toward TDLib and its bindings. None of that choice removes the second half of the work below.

What a library gives you

The MTProto encryption layer and the raw method calls

Update handling for incoming events from Telegram's servers

A client-side API to call auth, messaging and account methods

What you still build yourself

Persisting sessions reliably across restarts and deployments

Handling the SESSION_PASSWORD_NEEDED and SRP flow end to end for your users

Reconnecting gracefully and tracking account status when a device is removed

Or skip the client entirely
Unipile already runs the MTProto client for you
Session persistence, the 2FA wall, reconnection and account lifecycle are handled behind one API. You connect an existing Telegram account, you do not maintain a library.

Build with Unipile instead

Telegram API: Frequently Asked Questions

Straight answers on api_id, api_hash, BotFather bot tokens and connecting an existing Telegram account with Unipile.

01
What is the Telegram API?

Telegram does not have one API, it has three. The Bot API is an HTTP interface for bot accounts. The Telegram API, also called the Client API, runs on the MTProto protocol and is what full Telegram clients are built on. The Gateway API only sends verification codes. Which one you need depends on whether you are automating a bot or acting as a real user account.

02
How do I get a Telegram API key?

There is no single Telegram API key. For the Client API you sign in at my.telegram.org, open API development tools, and fill the form to receive an api_id and an api_hash. For the Bot API you message BotFather inside Telegram and it returns a bot token. Note that Telegram allows only one api_id per phone number.

03
Is the Telegram API free?

Yes. Telegram states that both the Bot API and the Telegram API are usable free of charge, with no per-message fee. The real cost sits in the infrastructure you run, the session handling, and the risk of a ban if you send aggressively.

04
How does the Telegram API work?

The Bot API is a plain HTTPS interface: you call methods like sendMessage against api.telegram.org with your bot token. The Client API is a binary MTProto protocol, which is why most developers use a library such as Telethon, Pyrogram or GramJS rather than implementing it themselves.

05
What is the latest version of the Telegram Bot API?

Bot API 10.2, published on July 14, 2026. It followed 10.1 on June 11, 2026 and 10.0 on May 8, 2026.

06
Can I use the Telegram API without building an MTProto client?

Yes. You can connect an existing Telegram account through Telegram's own Devices feature, which is how Unipile links accounts, using a QR code login or a hosted authentication flow. You get user-account access without implementing MTProto, session storage or two-factor handling yourself.

Still have questions? Our team is here to help.

Talk to an expert

Telegram API, done right

Build your Telegram API integration with Unipile

Skip the MTProto client, skip the bot limitations. Connect an existing Telegram account through Unipile and unify it with WhatsApp, LinkedIn, Instagram, Gmail, Outlook and IMAP in one API.

Build with Unipile
Read the docs See the Telegram API page

Send a Telegram message with the API
Unipile Telegram API product page