How to Get Your Telegram API ID and API Hash (my.telegram.org)

To get a Telegram API ID and API hash, log in at my.telegram.org with your phone number, open API development tools, fill in the short form describing your application, and submit it. The page then shows your api_id (a number) and api_hash (a long string of letters and digits). Treat both as secrets, because they identify your application to Telegram.

This guide explains what the two values are, when you actually need them and when a bot token is enough, how to fill in the form, how to store the values safely, and how to fix the errors people run into. It also covers the scam that uses my.telegram.org to steal accounts.

What the API ID and API hash actually are

Telegram offers two different programming interfaces, and they need different credentials.

The Bot API is a simplified HTTP interface for bots. You create a bot with @BotFather and receive a bot token. That token is all an ordinary bot needs. Most people building a bot never touch my.telegram.org.

The Telegram API, built on Telegram's own MTProto protocol, is the full interface that Telegram's own apps use. With it you can build a complete Telegram client, automate a user account, or use libraries that talk to Telegram directly rather than through the Bot API. To use it, your program must say which application it is. That is what the api_id and api_hash do.

• The api_id is a number that identifies your application.
• The api_hash is a secret string that goes with it, a little like a password for the application.

They identify the application, not the person using it. Every user who logs in through your app still needs their own phone number and login code. Your api_id does not give you access to anyone's account, and it does not give anyone access to yours. Those secrets matter for a different reason, covered below.

For a broader comparison of the two interfaces and of user-account automation, see Bot API vs MTProto vs userbots.

Do you need them at all?

Check this first. Many people go through my.telegram.org when they do not need to.

You need an api_id and api_hash if you are:

• building your own Telegram client app;
• using TDLib, Telegram's official client library, which requires them;
• using an MTProto library to automate your own user account or to read channels as a user;
• running a bot through an MTProto-based framework, which usually asks for an api_id and api_hash in addition to the bot token;
• following a tool's setup instructions that explicitly ask for them.

You do not need them if you are:

• creating an ordinary bot that uses the Bot API (a token from @BotFather is enough; see how to create a Telegram bot with BotFather);
• using a no-code bot builder that only asks for a bot token;
• adding Telegram login to a website through the login widget, which is set up through @BotFather;
• just using Telegram normally.

If a website or person asks for your api_id and api_hash and you are not building anything, stop and read the scam section below.

Alternatives that need no API ID at all

Before you set up a developer application, check whether a built-in feature or a plain bot already does the job. Each alternative below avoids the risks of running your own account through code.

Saving your chat history. If your goal is a copy of your chats, channels or media, Telegram Desktop has an export tool that saves history as readable files or as machine-readable data. It needs no programming. See how to export Telegram chat history.

Posting to your own channel automatically. A bot added as an admin of your channel can post through the Bot API. That covers scheduled announcements, posts from a website feed, and buttons under posts. Only the bot token is needed.

Replying to people who message you. Again a bot is the right tool. People start a chat with the bot, and the bot can answer them. Automating your personal account to reply to strangers is far more likely to get it restricted.

Collecting form answers, polls or sign-ups. Native polls, a group with a bot, or a bot builder cover most of this without any MTProto work.

Reading channels you do not run. This is where a Bot API bot usually falls short, because a bot only sees chats it has been added to. Reading public channels as yourself, at a gentle pace, is one of the more common honest reasons to get an api_id.

As a rule of thumb, if the job is something a bot could do as a member or admin, use a bot. Reach for the api_id when the job genuinely requires acting as a user.

Before you start

• An active Telegram account on a phone number you keep. Telegram uses this number to send developer notices, so its own guide asks for a current number tied to an account you use.
• Access to Telegram on another device. The my.telegram.org login code is sent as a Telegram message, not as an SMS. You need to be logged in to Telegram somewhere to read it.
• A rough idea of what you are building. You will be asked for a name and a short description.
• Time to read Telegram's API terms of service. By creating an application you agree to them. The key points are summarised below.

Telegram's own guide also notes that each phone number can currently have only one api_id. If you already created an application with your number, you will see its details instead of the form.

Step by step: getting your API ID and hash

1. Open my.telegram.org in a web browser. Type the address yourself rather than following a link from a chat or an email.
2. Enter your phone number in international format, starting with the country code, and submit.
3. Find the code. Open Telegram on your phone or computer. A message from Telegram contains a confirmation code for my.telegram.org. That message also warns you not to give the code to anyone.
4. Enter the code on the website and sign in.
5. Choose API development tools from the menu. (The same site also has options for deleting your account and other account tools, which is why the login code is so sensitive.)
6. Fill in the application form (field by field below).
7. Submit the form by choosing the option to create the application.
8. Copy your credentials. The page now shows your App api_id, App api_hash, and server details. Copy the api_id and api_hash into a secure place straight away.

You can come back later, log in again and open API development tools to view the same values.

Filling in the form, field by field

The form is short. None of the fields needs to be perfect, but sensible values avoid problems.

App title. A human-readable name for your application, such as "Sam's Channel Archiver". It appears in the active sessions list of anyone who logs in through your app, so pick something you would be happy for users to see.

Short name. A compact identifier made of letters and digits only. The form tells you the allowed length if your entry is rejected. Avoid spaces, punctuation and anything that resembles Telegram's own app names.

URL. A website for your project, if you have one. Many personal projects leave it blank or use a project page. It is optional on most versions of the form.

Platform. The platform your application runs on, such as desktop, Android, iOS, web or other. Choose the closest match; it does not limit where you can run your code.

Description. A sentence or two explaining what the app does. Be honest and plain: "Personal tool that saves posts from channels I follow into a local archive."

What the page shows afterwards

• App api_id: the number you will put into your library or app configuration.
• App api_hash: the secret string that goes with it.
• Test configuration and production configuration: server addresses for Telegram's test environment and its main servers, plus the public keys used to verify them. Most libraries already know the production servers, so you rarely need these unless a library asks.

Telegram's documentation says the test servers are a separate environment with separate accounts. They are useful for trying sign-in flows without risking your main account, but data there is not your real Telegram data.

Keeping the API hash secret

Telegram's developer terms describe these credentials as confidential and prohibit publishing them. In practice:

• Do not put them in public code. If you share a project on a public code hosting site, keep the values out of the files you upload. Load them from a configuration file that is excluded from the upload, or from environment settings on the machine where the program runs.
• Do not paste them into chats, forums or support tickets. If someone helping you needs to see your setup, replace the values with placeholders such as "your api_id here".
• Do not build them into apps you distribute to strangers without understanding that anyone can extract values from a distributed app. If you are publishing a client to the public, read Telegram's API terms carefully first.

Why it matters

If your api_id and api_hash leak, other people can run software that presents itself to Telegram as your application. If that software spams or floods Telegram's servers, the abuse is tied to your application. Telegram may then restrict the api_id, which breaks your app for everyone using it, and may take action against the account that registered it.

Sample credentials in open-source code

Some open-source projects include an api_id and api_hash in their example code. Telegram's terms say these sample values are restricted and meant for testing only. Software that uses them outside testing can trigger an error for its users (API_ID_PUBLISHED_FLOOD). Always get your own pair for anything real.

Telegram's API terms in plain English

You should read Telegram's API terms of service yourself, because they are the binding version and they change. The main themes, in general terms:

• No spam, no flooding. Automating messages to people who did not ask for them, or hammering the servers with requests, breaks the terms.
• Respect privacy and security. Apps must protect users' data and must not mislead them about what the app does.
• Do not impersonate Telegram. Your app's name and branding must not suggest it is an official Telegram app.
• Consequences. Telegram monitors API use. Applications and accounts that break the rules can be restricted or banned.

For people automating their own account, the practical rule is to behave like a careful human, not a script running flat out. The guide to Telegram flood wait explains the rate limits you will meet when a program sends requests too quickly, and what they mean.

Common errors and how to fix them

The login code never arrives

How to recognise it: you entered your number on my.telegram.org but see no SMS.

Why: the code is sent inside Telegram, not by SMS. It arrives as a message from Telegram's official notification account.

Fix:

1. Open Telegram on any device where you are logged in.
2. Look for the newest message from Telegram in your chat list.
3. Enter the code from that message.

If it still does not appear: check that you typed the number exactly as it is registered, including the country code. If you are logged out of every device, log in to Telegram first, then return to the website.

"Too many tries" or a waiting period

How to recognise it: the site refuses to send another code or says to try later.

Fix: wait. Repeated attempts extend the block. Come back later, request one code and enter it carefully. The limit lifts on its own after a while; nothing you do on the site shortens it.

A generic error when creating the application

How to recognise it: you submit the form and get an error message with little or no explanation.

Why: Telegram does not publish a full list of reasons. Developers commonly report it with brand-new accounts, with connections through a VPN or proxy, with browser extensions that block scripts, and with form values the site does not accept.

Fix, one step at a time:

1. Check the short name uses only letters and digits, with no spaces.
2. Fill in every field, including URL and description, with plain values.
3. Turn off ad blockers or privacy extensions for the site, or try a private window.
4. Turn off any VPN or proxy and try from your normal connection.
5. Try another browser or device.
6. Try again on another day.

If it still fails: the account may be too new or have restrictions that prevent creating an application. Using Telegram normally for a while, rather than creating many accounts to try, is the reasonable path. Do not buy accounts or pre-made credentials to get around it; those come from other people and break the terms.

Your library reports an invalid api_id

How to recognise it: the program starts but Telegram rejects the connection with an error mentioning an invalid API ID.

Fix:

1. Check you copied the api_id as a number and the api_hash as the full string, with no extra spaces or quotation marks.
2. Make sure the two values belong together. Mixing your id with a hash from an example will fail.
3. Confirm the program is reading your configuration, not leftover sample values.

Your account was limited after automation

How to recognise it: you start getting flood errors, cannot message people outside your contacts, or receive a notice about restrictions.

Fix: stop the automation, read the restriction message carefully, and follow the in-app path Telegram offers. The account banned guide covers the appeal routes. Then reduce how often your program acts and stop any messaging to people who did not ask for it.

The scam that uses my.telegram.org

Because my.telegram.org can delete accounts and create API credentials, scammers target its login code.

The pattern usually looks like this. Someone in a chat, often posing as support, a bot developer or a giveaway organiser, asks you to "verify" by logging in to my.telegram.org and sending them the code, or by entering it on a site they link. With that code, they can log in to the site as you. From there they can create an API application on your number, view your api_hash, or reach the account deletion page.

Rules that protect you:

• The my.telegram.org code is for you alone. Nobody needs it to help you, verify you or pay you.
• Only type it on my.telegram.org itself, at the address you typed yourself, never on a lookalike.
• If you shared it by mistake, log in to my.telegram.org straight away, and check Telegram's active sessions for anything unfamiliar. Turn on two-step verification if it is not already on.

The broader rules are in never share your Telegram login code.

Using the credentials: what happens next

Each library or tool has its own setup, but the flow is broadly the same.

1. You give the library your api_id and api_hash, usually through a configuration file or settings on the machine.
2. On first run, it asks for a phone number (yours, for a personal tool) or a bot token.
3. For a phone number, Telegram sends a login code to your Telegram app, exactly as when you log in on a new device. If you use two-step verification, the library asks for that password as well.
4. The library stores a session so it does not need to log in each time. That session file or string is now as sensitive as a logged-in phone. Anyone who copies it can act as your account.
5. The new login appears in your active sessions, labelled with your app title. You can end it there at any time.

That fourth point catches many people out. The api_hash identifies your app; the session is the key to your account. Keep session files out of public code and shared folders, and delete them when you stop using a tool.

Running automation without endangering your account

Code that logs in as you acts with your full account. A mistake in it, or a rule broken by accident, lands on your personal profile, your chats and any channels you own. A few habits reduce that risk.

1. Start slowly. Run one action, check the result, then add more. A loop that runs a thousand times by mistake can trigger limits within minutes.
2. Add pauses between actions. Waiting between requests keeps you well inside Telegram's limits. When Telegram returns a flood wait, the program must wait the time it names before trying again, never retry at once.
3. Read, do not message. Tools that only read public content carry far less risk than tools that send messages, join groups or add people. Sending unsolicited messages to strangers is the behaviour most likely to get an account restricted.
4. Keep channel ownership separate where it matters. If you own valuable channels, think carefully before running experimental code on the same account. A restriction on the account can make managing them harder. Adding a trusted second admin to important channels is a sensible precaution anyway; see how to add admins to a Telegram channel.
5. Log what the program does. A simple record of each action helps you see what went wrong if Telegram responds with an error.
6. End sessions you no longer use. When you retire a tool, end its session from Telegram's devices list and delete its session file.

Using the test environment

Telegram runs a separate test environment, and the server details for it appear on your API development tools page. It has its own accounts, separate from your real one, and data there is not your real Telegram data.

It is useful when you are building something that handles sign-in, such as your own client, and you want to try the login flow repeatedly without tripping limits on your real number. Most libraries have a setting to point them at the test servers instead of the production ones. Your library's documentation explains how.

For tools that read real channels or manage your real account, the test environment does not help, because the content you care about only exists in production. In that case, go slowly in production instead.

Checklist before your first run

1. You confirmed you need an api_id rather than a bot token.
2. The api_id and api_hash are in local configuration, not in code you might share.
3. The configuration and session files are excluded from any public upload.
4. Two-step verification is on for the account you will log in with.
5. Your program pauses between actions and respects flood waits.
6. You have read Telegram's API terms of service.
7. You know where the devices list is, so you can end the program's session if needed.

Worked examples

Example: a personal channel archive. A researcher wants to save posts from public channels they follow into a spreadsheet. A Bot API bot cannot read channels it is not a member of, so they create an application on my.telegram.org, use an MTProto library with their own api_id and api_hash, and log in with their own account. They keep the request rate low and run it once a day.

Example: a bot that turns out not to need it. A shop owner wants a bot that answers questions and takes orders. A tutorial mentioned api_id, so they went to my.telegram.org first. In fact a bot token from @BotFather is all their Bot API framework needs, and the my.telegram.org step was unnecessary.

Example: a leaked hash. A developer pushed a project to a public repository with their api_id and api_hash inside. They remove the values, rewrite the project history so old versions no longer contain them, and move the values to local configuration. They also review their active sessions, remove any session files from the repository, and watch for unusual activity on the account.

What to do next

Once you have your credentials, the next steps depend on what you are building.

• A personal tool. Pick a well-maintained library in a language you know, read its documentation on configuration and sessions, and start with a read-only task such as listing your own chats. Confirm it works before adding anything that sends.
• A bot built on an MTProto framework. You will combine the api_id and api_hash with a bot token from @BotFather. The bot logs in as the bot, not as you, so your personal account is not the one acting.
• A full client for other people. Read Telegram's API terms in full and the client development guidelines on Telegram's developer site before you begin. Publishing a client brings obligations around privacy, security and naming that a personal tool does not.
• Something you are unsure about. Write down in one sentence what the program will do and to whom. If that sentence involves messaging people who never asked to hear from you, rethink the plan before you write any code.

Keep the API development tools page bookmarked, and keep the phone number current, since Telegram uses it to reach you about your application.

Common mistakes

• Going to my.telegram.org for an ordinary bot. A Bot API bot needs only a token from @BotFather.
• Expecting an SMS. The code arrives as a message inside Telegram.
• Sharing the code with anyone. It opens a site that can delete your account.
• Committing credentials or session files to public code. Load them from local settings instead.
• Using sample credentials from a tutorial. They are restricted and lead to errors.
• Running automation at full speed. Flood limits and restrictions follow quickly.
• Using a temporary number. Telegram sends developer notices to that number, and you need it to manage the application later.

FAQ

Is getting an API ID free?

Yes. Creating an application on my.telegram.org does not cost anything.

Can I have more than one api_id?

Telegram's guide says each phone number can currently be linked to only one api_id. One application usually serves all your personal projects.

Can I change or delete my application later?

The API development tools page shows your application details when you log in again. Options to edit details may be offered there; check the page itself, as Telegram does not document every option. Your api_id stays tied to your number.

Does someone with my api_id and api_hash have access to my account?

No, not by themselves. They would still need a login code or a session for your account. But they could run software that presents itself as your application, and abuse by that software is tied to you. Keep both values private.

Do bots created with BotFather have an api_id?

Bots have a token, not an api_id. Some MTProto-based bot frameworks ask for an api_id and api_hash as well, which come from your own application on my.telegram.org.

I logged in to my.telegram.org but never asked for a code. What now?

Someone may be trying to get into it with your number. Do not share the code with anyone who contacts you about it. Check your active sessions in Telegram and turn on two-step verification if you have not already. Our guide to two-step verification walks through it.

Summary

Log in to my.telegram.org with your number, type the code sent inside Telegram, open API development tools and fill in the short form to get your api_id and api_hash. You only need them for MTProto-based tools, clients and TDLib, not for ordinary bots. Keep both values and any session files private, follow Telegram's API terms, and never give the my.telegram.org code to anyone.