The Telegram bot token: where to get it, how to check and protect it
Where to get a Telegram bot token from @BotFather, what it looks like, how to check it with the getMe method, what to do if it is lost or leaked, and how to keep it secret.
A Telegram bot token is the key your program uses to control a bot through the Bot API. The official bot @BotFather issues it right after the /newbot command. It looks like a number and a long string of characters separated by a colon, for example 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11 (this one comes from the documentation and isn't real). Anyone who has the token can control the bot, so Telegram's advice is to keep it in a secure place and share it only with people who need direct access.
Where to get a bot token
- Open @BotFather and send
/newbot. - Give the bot a name and a username that ends in
bot. - BotFather sends you the token. The whole process is in how to create a Telegram bot.
Lost the token of an existing bot? Telegram names the /token command for this: it is meant for when the token is lost or compromised, and it generates a new one.
Don't confuse the token with api_id and api_hash. The token belongs to a bot, while api_id and api_hash are for programs that sign in to Telegram as an ordinary user: how to get them.
How the token is used in requests
The token is part of the address of every Bot API request: https://api.telegram.org/bot<token>/METHOD. For example, https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe calls the getMe method. Bot libraries add the token themselves; you only pass it once when you create the bot. Because the token sits in the address, it can end up in the logs of HTTP clients and proxies, so don't publish such logs.
How to check a token with getMe
getMe is a simple method for testing the token. It takes no parameters and returns information about the bot itself:
curl "https://api.telegram.org/bot<TOKEN>/getMe"
If the token is valid, you get JSON with "ok": true. The result holds the bot's id, is_bot, first_name and username, plus the fields can_join_groups, can_read_all_group_messages and supports_inline_queries, which only this method returns. If the token is wrong or has been replaced, ok is false and the reply has an error_code (usually 401) and a description.
A typo is the usual cause: an extra space or line break from copying, or a missing character. Copy the token again from the BotFather chat.
What to do if the token leaks
A token has leaked if it landed in a public repository, a screenshot, someone else's chat or a log that outsiders can see. Act at once:
- Open the chat with @BotFather and send
/token. Telegram's documentation names this command for a compromised token. Choose the bot, and BotFather issues a new token. Guides to BotFather also mention a/revokecommand, which likewise issues a new token. Treat the old token as dead. - Put the new token everywhere the bot uses it: server settings, environment variables, your program. Restart the bot.
- Check the new token with
getMe. - Check the webhook. Whoever held the token could have called
setWebhookwith their own address and be receiving your bot's messages. CallgetWebhookInfo: theurlfield should hold your address. If it holds someone else's, set yours withsetWebhookor remove the webhook withdeleteWebhook— more in getUpdates and webhooks. - If the token was committed to Git, deleting the file isn't enough: it stays in the repository history. Only a new token fixes that.
How to keep the token secret
- Don't write the token into source code and don't push it to a repository, even a private one.
- Keep it in an environment variable or in a settings file that stays out of Git (add its name to
.gitignore). - Don't put the token into code that runs on the user's side: a web page, a mobile app or a Mini App. Make Bot API requests from your own server.
- Don't show the token in screenshots or logs, and don't send it in chats, support chats included.
If you no longer need a bot, you can delete it with the /deletebot command in BotFather. More about bot settings is in how to create a Telegram bot.
What next
With the token you can send a first message — sendMessage with curl — and set up receiving messages: getUpdates and webhooks. Need an API to buy Stars or Premium for your users from a program? See the Shiba Bank bot's API documentation.
Frequently asked questions
How do I get a Telegram API token for a bot?
Send @BotFather the command /newbot: after you pick a name and a username it sends the token. For a bot that already exists, /token generates a new one.
What is a Telegram bot token?
It is the key that authorizes requests to the Bot API: it tells Telegram which bot a request comes from. The token is part of the address https://api.telegram.org/bot<token>/METHOD.
How do I check a bot token?
Call the getMe method: curl "https://api.telegram.org/bot<TOKEN>/getMe". With a valid token the reply has "ok": true and the bot's data.
What should I do if my bot token leaks?
Generate a new token in BotFather with /token, put it everywhere the bot uses it, and check with getWebhookInfo that the webhook points to your address.
How is a token different from api_id and api_hash?
The token belongs to a bot. api_id and api_hash are for programs that sign in to Telegram as a user, and you get them elsewhere: how to get them.
Can I keep the token in the code?
No: code easily ends up in a repository or in the wrong hands. Keep the token in an environment variable or in a file outside the repository.
