Telegram Bot Token: What It Unlocks and How to Replace It

Every guide treats the bot token the same way: get it from BotFather, paste it into your code, move on. That framing is why so many bots end up compromised or quietly taken over. The token is not a setup step. It is the account. There is no password behind it, no second factor, and no recovery flow that proves you are the owner faster than whoever else is holding the string.

This is written from the published documentation rather than from habit, because the ground moved recently. In April 2026 Telegram shipped Managed Bots, adding two methods that did not exist before: one that hands a token to another bot, and one that revokes a token and returns a fresh one. A credential that used to arrive once, by chat message, is now something software can fetch and rotate on its own. Most of what is written about bot tokens predates that change entirely.

What follows covers what the string contains, how to verify one without exposing it, where the chat ID comes from, the two other things also called tokens, what someone holding yours can and cannot do, and how to replace it.

What the Token Actually Is

Start with what makes bot accounts unusual, because the token follows directly from it.

A bot account has no phone number

Telegram describes bots as special accounts that do not need a phone number to set up. That single sentence explains the whole design. An ordinary account is anchored to a SIM, so the login flow can send a code to it and the recovery flow can send another. A bot has nothing to send a code to. The only thing proving you are allowed to drive it is a string you were handed once, and removing the phone number removes every recovery path that depended on it.

The token authenticates the bot, not you

The official tutorial is precise: the token authenticates your bot, not your account. It cuts both ways. Someone who steals your token does not get your personal account, your chats, or your contacts; they get the bot, completely. And when you hand a token to a contractor to finish an integration, you have not given them limited access to one feature. You have given them the account, with no way to scope it down and no log of what they did with it.

Everyone holding it has full control

Telegram's wording on the introductory page is that everyone who has your token will have full control over your bot, and that you should share it only with people who need direct access. There is no read-only variant, no per-method permission, no expiry, and no way to issue a second token for a second person so you can revoke one without breaking the other. One bot, one live token. That constraint drives most of the practical advice below, and it is what separates a token from an ordinary API key.

Where It Comes From

There are now two origins for a bot token, and until recently there was only one.

BotFather and the new bot command

The original route has not changed. You message @BotFather, send /newbot, and answer two questions: a display name and a username. The username has to be five to thirty-two characters, is not case sensitive, may contain only Latin letters, numbers and underscores, and must end in the bot suffix. When you have answered both, the token arrives in the chat. Our walkthrough of that flow, along with the limits that show up afterwards, sits in the piece on creating a Telegram bot and what it will not do.

One choice you cannot undo

The display name is editable forever. The username is not. Telegram states plainly that unlike the name, the username cannot be changed later, so choose it carefully. People discover this after printing the handle on something, and the only remedy is to create an entirely new bot, which means a new token, a new user ID, and an audience that has to be told to start over. Treat the username decision as permanent from the first message, because that is exactly what it is.

The second origin, added in April 2026

Since Bot API 9.6, a bot can create and manage other bots on behalf of their owners. When a bot in management mode spawns a new bot, the token is never shown in a chat at all. It is fetched programmatically with getManagedBotToken. That is a genuine break with how this credential used to work, and it gets its own section below, because it changes both the threat model and the storage advice.

Reading the Format Literally

The string is not random filler. Both halves carry meaning, and knowing which is which saves time when something fails.

Two halves separated by a colon

The documentation prints three example tokens across three pages, and all three share a shape: digits, a colon, then a longer mixed-case string. The authorization section uses 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 and the tutorial uses 4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc. Any string that does not fit that pattern is not a token, which is the cheapest validation you can run before making a single request.

The number in front is the bot's user ID

The leading digits are not a serial number for the credential. They are the bot's identifier as an account, the same value returned in the id field when you ask the API who you are. This matters more than it sounds. The first half of a token is not secret in any meaningful sense, since anyone who has ever received a message from your bot can see that identifier. The secret lives entirely after the colon, and that is the only part worth protecting.

The word bot goes in front of the token

Every request has the form https://api.telegram.org/bot<token>/METHOD_NAME, with the literal word attached directly to the front of the token and no separator between them. The documentation spells this out because it trips people constantly. A URL carrying a space after the prefix, or omitting the prefix, produces an error that looks like a bad token but is actually a bad address. Four ways of passing parameters are supported: query string, form encoding, JSON for everything except file uploads, and multipart for uploads.

Checking a Token Without Leaking It

Before debugging anything else, confirm the credential itself works. There is exactly one right way to do that.

One call is the entire test

Call the method that returns the bot's own user record. It takes no parameters, changes nothing, and either succeeds or does not. A successful call proves the string is valid, the bot still exists, and nothing has revoked it since you last looked. It also gives you the bot's identifier, which you can compare against the digits in front of the colon as a check that you are holding the token you think you are holding.

What comes back, and what a rejection looks like

The response is a JSON object with a boolean field that reports success, and the payload sits in a result field. Three values come back only from this method and nowhere else: whether the bot can be invited to groups, whether privacy mode is switched off, and whether it supports guest queries from chats it is not a member of. So this is not merely a heartbeat. It is the only place to read your bot's current configuration back from the platform rather than from your own notes.

When the request fails, the success field is false, a human-readable description explains the problem, and an integer error code comes back too, though the documentation warns that the contents of that code are subject to change. Some errors carry an extra parameters object that helps you handle the failure automatically. The practical reading: match on the description, but do not build permanent logic on the numeric code alone, because Telegram has explicitly reserved the right to change it.

The Chat ID Is Not in the Token

Search for a bot token and the phrase that follows it more than any other is "and chat ID". That pairing is not a coincidence, and neither is the confusion behind it.

Why the two get searched together

The token tells Telegram who is asking. The chat ID tells Telegram where to deliver. You need both to send one message, and a tutorial that mentions the first without the second leaves you with a working credential and nowhere to point it. That is why the terms are welded together in autocomplete. Technically they are unrelated: one is a secret, the other is a plain integer appearing in every update you receive.

Route one, read it off an update

Message your bot from the account or group you want to reach, then fetch pending updates. Every incoming update carries a chat object, and that object's identifier field is what you need. This route works everywhere, needs no extra tooling, and costs one request. The one catch is that a bot cannot start a conversation, so somebody has to write to it first, which is also the reason this step exists at all.

Route two, let the user pick the chat

Since keyboard buttons that request a chat were added, you can hand the user a button, they tap a chat, and Telegram sends your bot a service message containing that chat's identifier while closing the picker. This is the cleaner path for anything a customer sets up themselves, because it removes the step where you talk a non-technical person through reading raw update payloads. The identifier arrives as a proper field, not as something you parse out of text.

The size trap that breaks quietly

The documentation attaches an unusual warning to these identifiers: the number may have more than thirty-two significant bits, some programming languages have difficulty or silent defects interpreting it, but it has at most fifty-two significant bits, so a signed sixty-four-bit integer or a double-precision float is safe. The word doing the work is silent. In a language that stores numbers as thirty-two-bit integers by default, a large chat identifier does not throw. It wraps, and your messages go somewhere else or nowhere at all.

Two Ways to Receive Updates, Never Both

The token gets you access. How updates reach you is a separate decision, and it is exclusive.

Long polling

You call the update method in a loop and Telegram answers with whatever has arrived. Between one and a hundred updates come back per call, and a timeout parameter turns short polling into long polling. The documentation is direct that short polling, a timeout of zero, should be used for testing only. It needs no public address and stays adequate until traffic makes the idle round trips wasteful.

Webhooks

You register an address and Telegram posts updates to it as they happen. This inverts the cost: no idle requests, but you now need a reachable secure endpoint and something listening on it. You can also answer the API inside your reply to the webhook by naming the method in a parameter, which saves a round trip, with the caveat that you cannot learn whether such a request succeeded or read its result.

The error that means you tried both

The two are described as mutually exclusive, and the update method carries a flat statement: it will not work if an outgoing webhook is set up. So a bot that has stopped receiving anything through polling, for no reason you can find, has very often had a webhook registered against it and forgotten. Clear the webhook first, then poll. Separately, incoming updates are held on Telegram's side until you collect them, but not longer than twenty-four hours, so a bot down for a weekend does not come back to a full queue.

The Webhook Secret, Which Is a Different Token

The second thing called a token here exists for the opposite reason to the first.

What it is for

Your bot token proves your identity to Telegram. The webhook secret proves Telegram's identity to you. When you register a webhook you may pass a secret value, and Telegram then includes it in a header on every request it sends to your endpoint. Without it, your endpoint cannot distinguish a genuine update from anything else that finds the address and posts to it. The two credentials point in opposite directions and are not interchangeable.

The header it arrives in

The value arrives in a header named for the secret token, and the documentation limits it to between one and two hundred fifty-six characters from a restricted alphabet of letters and digits. Checking it costs one string comparison at the top of your handler. Skipping it is the most common gap in bots that are otherwise carefully written, because obscurity feels like security until someone finds the address in a certificate log.

The older advice that still circulates

Before this parameter existed, Telegram's own guidance was to put the bot token in the webhook path, on the reasoning that since nobody else knows the token, you can be fairly sure the request is genuine. That advice is still in the frequently asked questions and it still works, but it puts your live credential into every access log, proxy log and error report your stack produces. If you have a path shaped like your token, the secret parameter replaces it, and the swap takes one request.

The Payment Provider Token, Which Is a Third One

The third thing called a token has nothing to do with authenticating anything of yours.

Where it comes from, and when you pass nothing

To bill in ordinary currency, an invoice carries a payment provider token, also obtained through BotFather but issued by a payment processor you have connected. It is a per-provider credential living inside the invoice payload rather than in the request address. People conflate it with the bot token because both arrive from the same chat, then wonder why pasting one where the other belongs produces an error naming neither.

For invoices denominated in the platform's own currency, the provider token is passed as an empty string. That is the tell separating the two billing routes: an empty provider field is not a mistake or an omission, it is the documented signal that no external processor is involved. If you are choosing between routes, our breakdown of the in-platform currency sits alongside the wider question of making money on Telegram.

The Credentials That Belong to a Phone Number

The fourth confusion is the largest, because these credentials belong to a different API entirely.

What they identify

A bot token authorizes a bot on the Bot API. An application identifier and hash pair authorizes an application on the user-facing API, the one real clients are built on. They are the parameters required for user authorization, which is precisely what a bot token cannot do. No amount of formatting turns one into the other, and no library bridges them, because they sit on different sides of the platform.

One per phone number

Telegram states that for the moment each number can only have one application identifier connected to it. So this credential is bound to a person's SIM in exactly the way a bot token is not. That sentence is the cleanest summary of the difference between automating as a bot and automating as an account, and it explains why account-based work needs infrastructure that bot work never touches, as covered in our comparison of session files and tdata folders.

The sample credential trap

The open source clients ship with a sample identifier, and the documentation warns that it is limited on the server side and unsuitable for released apps, producing a specific published flood error for your users. Copied tutorials still pass that sample value around. The failure it produces looks like rate limiting or a network fault, which sends people to proxy configuration when the actual cause is a shared credential that was never meant to leave a test.

What Someone Can Do With Your Token

Understanding the blast radius is what turns storage advice from a chore into a habit.

Send as the bot, to anyone it knows

Every message the bot can send, they can send, to every chat the bot can reach. To your users the messages are indistinguishable from yours, because there is no sender identity below the bot itself. For an account with a real audience this is the whole loss in one line, and it is why a leaked token is an incident rather than an inconvenience.

Read what the bot can read

What that covers depends on privacy mode, which decides whether the bot sees all group messages or only commands and replies directed at it. But whatever your bot receives, the token holder receives too, including anything users have sent it privately. If your bot collects anything sensitive, the token protects that data, and it is the only thing protecting it.

Repoint the webhook

This is the quiet one. Rather than sending anything, an attacker can register their own address as the webhook and simply receive your traffic. Your bot appears to work from the outside while every update is delivered somewhere else. Nothing in the interface announces this, and there is no notification. Reading back the current webhook configuration should be part of any incident check, not an afterthought.

Rewrite the public face

The profile, description, about text, picture and command list are all settings on the account, so whoever holds the credential can change them. A hijacked bot can be pointed at a different offer or a different link without touching a single message, and users who trusted it last week have no signal that anything changed. This is the failure mode our write-up of scam patterns keeps meeting from the victim's side.

What a Leak Does Not Hand Over

Overstating the damage is its own problem, because it pushes people toward responses that cost more than the incident.

Your personal account stays yours

The token authenticates the bot, not you. A stolen bot token does not log anyone into your Telegram account, does not expose your private chats, and does not reach your contacts. Your other bots are equally untouched, since each has its own credential. The damage is real but bounded, and the boundary is one account wide.

No old history, and no new audience

A bot added to a group is not handed the archive. It receives what arrives after it joins, filtered by privacy mode, so a token stolen today does not retroactively open years of conversation. If you need that history deliberately and legitimately, that is a separate operation with a separate route, which we covered under exporting chat history.

A bot also cannot message people who have not written to it first, and a stolen token does not lift that restriction. An attacker inherits your existing audience, not the ability to build a new one. This is also why cold outreach is an account-side capability rather than a bot-side one, a distinction we set out in the guide to sending mass direct messages.

Replacing a Token, and Handing a Bot Over

Both operations are one command each, and both are irreversible in ways worth understanding first.

The revoke command

If your token is compromised or you lost it, BotFather's /token command generates a new one. That is the entire documented remedy, and it is deliberately blunt: no partial revoke, no grace period, and no way to keep the old string alive while you migrate. The moment the new token exists, the old one is dead.

What breaks the second you rotate

Everything holding the old string stops working at once, which in practice means more than you think: your production process, any staging copy, any scheduled job, any teammate's local run, and any third-party service you connected months ago. Rotation is fast; the inventory of who holds the credential is the slow part. Doing that inventory before the emergency is the whole difference between a five-minute fix and an afternoon.

Transferring ownership, and why selling a bot is not selling a string

Through the bot list you can transfer a bot to another user, with one requirement: they must have interacted with it at least once. Telegram is explicit about what transfers, and it is everything. The new owner gets full control, can access the bot's messages, and can delete it outright. The transfer is permanent and the documentation asks you to consider it carefully, which is unusually direct phrasing for a settings screen.

Because ownership moves through that flow rather than by handing over a string, a bot changing hands properly means the seller loses access at the moment of transfer. Anyone offering to sell you a bot by sending you its token is not transferring anything; they are sharing a credential they still hold and can rotate the instant the money clears. If you want capability rather than one specific account, our custom build service is the version of that transaction that leaves you owning the result.

Managed Bots Changed What a Token Is

This is the part of the subject most published material has not caught up with, and it is a year old.

The management mode switch

Telegram now allows bots to create and manage other bots on behalf of their owners. You pick one of your existing bots or make a new one, open its settings in BotFather's mini application, and enable bot management mode. From there your bot acts as a factory for other people's bots, which is what lets customers spin up their own assistants without touching a developer chat.

The link that creates a bot

Sharing works through an address naming your manager bot and a suggested username, with an optional display name in the query. Opening it gives the user a window to finish creating their bot with both fields pre-filled and editable. This is a real onboarding primitive: the person never messages BotFather, never sees a raw token, and never has to be talked through a developer interface.

Fetching and replacing a managed token

When creation completes, the manager receives an update carrying information about the new bot and its creator, and can then call getManagedBotToken to fetch that bot's access token. A companion method revokes a managed bot's current token and returns the new one as a string, taking only the user identifier of the bot in question. Rotation is now an API call rather than a conversation, which is the most consequential change in this whole area.

What this means for how you store tokens

If you operate a manager bot, you are no longer guarding one credential. You hold a set of them, on behalf of other people, and the update stream tells you whenever one is created, rotated or reassigned to a new owner. That is a different security posture from a single environment variable, closer to running a key store than to running a bot. Anyone building at that scale should read our notes on channel automation alongside this, and our bot management product exists for exactly this shape of problem.

Where to Keep It

The storage rules are short, and each exists because of a specific way tokens get out.

Not in source control

Telegram's tutorial says to store the token in a dedicated settings file or an environment variable rather than in the code, and the reason is mechanical rather than stylistic. Code gets committed, pushed, forked and searched. A token in a repository is leaked from the moment it is pushed, even to a private one, because the history keeps it after you delete the line. Rotate first, clean the history second.

Never in anything a user runs

A token shipped inside a mobile application, a browser extension or any client-side script is public. Anyone can read it out of the bundle, and no amount of obfuscation changes that. The token belongs on a server you control, and the client should talk to your server rather than to Telegram directly. This is the rule most commonly broken by people building a quick front end, and it is broken silently.

Keep a second bot for testing

Telegram suggests running another instance of your code against a separate bot account so you never test against live users, with one gotcha: file identifiers are tied to a single bot, so your test instance cannot reuse a shared file database and must upload media again. A second bot also means your development and production tokens are different strings, which is the cheapest possible protection against a debugging session touching real people. Our roundup of public Telegram scripts is a good reminder of how often that separation is missing in code you might reuse.

Moving a Bot Between Servers

Two methods exist for this and neither is obvious from its name, which is why bots get stranded.

Log out first, then close when you move again

The Bot API can be self-hosted. Before pointing your bot at your own server you must log it out of the cloud one, and the documentation is direct that otherwise there is no guarantee the bot will receive updates. After a successful logout you can immediately log in locally. Skipping this produces a bot that appears configured and simply gets no traffic, with no error to explain why. Moving from one self-hosted instance to another uses a second method that closes the bot instance, and you delete the webhook before calling it so the bot is not relaunched on the old server mid-move.

What self-hosting actually buys you

The published list is specific: downloads with no size limit, uploads up to two thousand megabytes, local file paths, a plain webhook address, any port, and a maximum webhook connection count of one hundred thousand. Telegram itself says most bots will be fine on the default configuration. If none of those describes a problem you have, self-hosting is operational work for nothing, and the token behaves identically either way.

The Test Environment Has Its Own Tokens

Separate from running a second bot, there is a whole parallel environment, and it is more separate than people expect.

A different world, with tighter limits than you expect

The test environment is completely separate from the main one, so you need a new user account and a new bot created there, reached through a debug entry point in the clients. Requests go to the same host with a marker inserted in the path after the token. None of your live bots, chats or files exist there.

Flood limits are not raised in the test environment and may at times be stricter, which inverts what most people assume a sandbox is for. The documented advice is to handle errors with retry policies and not depend on hardcoded limit values, which is good practice in production too. What the environment does relax is transport: plain unencrypted links are allowed for web applications and login flows, and that is the actual reason to use it.

What All of This Adds Up To

The bot token is the smallest credential on Telegram and the least defended. One string, no password, no second factor, no scoping, no expiry, and full control for anyone holding it. Every practical rule follows: keep it out of code and out of anything a user can run, put a secret on your webhook, do not confuse it with the payment provider token or with the credentials tied to a phone number, and know the revoke command before you need it.

What changed in April 2026 is worth repeating. Tokens can now be fetched and replaced by software, and a bot can hold credentials for other people's bots and rotate any of them with a single call. For anyone running one bot, that is a curiosity. For anyone running a platform, it moves token handling from a setup detail into an operational system with its own failure modes.

If your bot does real work and its token sits in a repository, a chat message, or a webhook path, the fix takes two minutes: rotate it, put the new one in an environment variable, add a secret to the webhook, and confirm with a single call that asks the bot who it is. For work larger than one bot, our outreach tooling and account management sit on the other side of this line, in the part of Telegram a bot token deliberately cannot reach.

Frequently Asked Questions

What does a Telegram bot token look like?

It is two parts joined by a colon: digits, then a longer mixed-case string of letters, numbers and occasional dashes. Telegram's published examples take the shape of a short numeric portion, a colon, and roughly thirty-five characters after it. The digits before the colon are the bot's user identifier, so that half is not really secret. Everything after the colon authorizes requests, and that is the part that matters if it gets out.

How do I get a Telegram bot token?

Message BotFather, send the new bot command, and answer two questions: a display name and a username ending in the bot suffix. The token comes back in that chat immediately. There is no application, no review and no cost. Since Bot API 9.6 there is a second route where a bot operating in management mode creates the bot for you and fetches the token programmatically, so the user never sees the string at all.

Is the bot token the same as the chat ID?

No, and they are not even the same kind of thing. The token is a secret identifying your bot to Telegram. The chat ID is a plain integer identifying a destination, and it appears in the payload of every update your bot receives. You need both to send a message, which is why they are searched together, but the chat ID is not contained in the token and cannot be derived from it.

How do I find my chat ID?

Send a message to your bot from the chat you want, then fetch pending updates and read the identifier from the chat object. Alternatively, present a keyboard button that requests a chat, and when the user taps one Telegram sends your bot a service message containing that chat's identifier. Store the value in a sixty-four-bit integer, because the documentation warns these numbers can exceed thirty-two bits and fail silently in languages that assume otherwise.

What happens if someone gets my bot token?

They control the bot completely. They can send messages as it to every chat it can reach, read whatever it receives, change its profile and command list, and redirect its webhook to their own server so your updates arrive somewhere else. They do not get your personal account, your other bots, or group history from before your bot joined. The correct response is to revoke immediately rather than investigate first.

How do I revoke or change a Telegram bot token?

Send the token command to BotFather and it generates a new one for the bot you select. The old string stops working immediately, with no grace period, so plan for everything holding it to break at once: production, staging, scheduled jobs, teammates' local copies and any connected third-party service. For bots created through a manager bot, a dedicated method revokes the current token and returns the replacement as a string.

Can I have two tokens for the same bot?

No. Each bot has exactly one live token, and generating a new one invalidates the previous. That is why you cannot give a contractor limited access, and why the standard advice is to create a separate bot for testing rather than sharing production credentials. If different systems need different access, they need different bots, since the credential itself carries no scope.

Is a bot token the same as an application identifier and hash?

No. A bot token authorizes a bot on the Bot API. The identifier and hash pair authorizes an application on the user-facing API, and it is tied to a phone number, with only one identifier permitted per number. They cannot substitute for each other in either direction. Anything that needs to act as a person rather than as a bot needs the second kind, and that is a different set of problems entirely.

Do I need a webhook secret if my address is hard to guess?

Yes. An obscure address is not authentication, and addresses leak through certificate transparency logs, error reports and proxy logs. Passing a secret when you register the webhook makes Telegram include it in a header on every delivery, and comparing it costs one string check. The older practice of putting the bot token in the webhook path still works but writes your live credential into every log your stack keeps.