How to create a Telegram bot with BotFather and get its token

Every Telegram bot starts in the same place: a chat with BotFather, Telegram's own bot for creating and configuring other bots. There is no developer portal and no form. You answer a few messages and get back a token, a string that your code uses to prove it controls the bot.

This guide covers the full path: creating the bot, choosing a username, protecting the token, checking that it works and running a first bot. The code uses Python with the python-telegram-bot version 22 API, which requires a Python version that is still supported (the minimum is in the library's docs).

What do I need before starting?#

• A Telegram account, on the phone or the desktop app.
• A Python version that is still supported, only if you want to run the test code.
• A place to keep secrets, such as an environment variable or a .env file.

How do I create a bot with BotFather?#

1. Open @BotFather in Telegram. Make sure the username is exactly @BotFather, since lookalike accounts exist.
2. Send /newbot.
3. BotFather asks for a name. This is the display name shown in chats and contact details. It can contain spaces and can be changed later with /setname.
4. BotFather asks for a username. It must be 5 to 32 characters, use only Latin letters, numbers and underscores, and end in bot, such as tetris_bot or TetrisBot. Usernames are not case sensitive, must be unique, and cannot be changed afterwards.
5. BotFather replies with the token and a link to your bot, t.me/<username>.

If the username is taken, BotFather asks for another one. Try adding a word or a number.

What does the token look like and what can it do?#

A token is a number, a colon and a long string of letters and digits. Telegram's documentation shows this shape:

110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

That example is not a real credential. The token authenticates your bot, not your account. Anyone who has it can control the bot, so treat it like a password. Telegram's tutorial calls hardcoding it in source code bad practice and recommends environment variables or a settings file.

If it leaks, revoke it through BotFather and generate a new one (Telegram's documentation points to /token for this). Update every place the bot runs, then call getMe (below) with the old token to confirm it now fails. See what are environment variables and what is a dotenv file for ways to keep it out of your repository.

How do I test that the token works?#

The Bot API is plain HTTPS. Every request goes to https://api.telegram.org/bot<token>/METHOD_NAME, with the word bot placed before the token. The getMe method returns the bot's own profile, which makes it a good check.

export BOT_TOKEN="paste-your-token-here"
curl "https://api.telegram.org/bot${BOT_TOKEN}/getMe"

A valid token returns JSON with "ok": true and a result object holding the bot's id, name and username. An invalid one returns "ok": false with error_code 401 (or 404 when the token is malformed).

How do I run a first bot?#

Install the library and write a bot that replies to /start and echoes text messages.

pip install "python-telegram-bot>=22,<23"

import os

from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Hi! Send me a message and I will repeat it.")


async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text(update.message.text)


def main() -> None:
    app = Application.builder().token(os.environ["BOT_TOKEN"]).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.run_polling()


if __name__ == "__main__":
    main()

Run it with BOT_TOKEN set in the same shell, open your bot's link and press Start. The bot uses long polling: it asks Telegram for new updates, so it needs no public URL. For the difference between polling and webhooks, read how to host a Telegram bot 24/7.

How do I finish setting up the bot in BotFather?#

These commands polish the bot. All are optional:

• /setdescription: text of up to 512 characters shown under "What can this bot do?" when a user first opens the chat.
• /setabouttext: a shorter bio of up to 120 characters shown on the profile page.
• /setcommands: the list of commands users see when they type /.
• /setname: change the display name.

Commands you register this way only show a menu. Your code still has to handle each one.

What are the most common errors?#

• telegram.error.InvalidToken or 401 Unauthorized: the token is wrong, has extra spaces or quotes, or was revoked in BotFather. Copy it again.
• KeyError: 'BOT_TOKEN': the environment variable is not set in the shell that runs the script.
• The bot does not answer: the process is not running, or you never pressed Start.
• 409 Conflict (telegram.error.Conflict): two instances use the same token with long polling, or a webhook is set. Stop the extra copy, or remove the webhook with deleteWebhook.
• Username rejected: it does not end in bot, is outside 5 to 32 characters, or is already taken.

If the bot was working and stopped answering, the Telegram bot not responding guide walks through the causes one by one.

How to do this on Square Cloud#

The bot above only answers while its process runs. On your own machine that stops when the computer sleeps, so a bot other people use needs an always-on host.

On Square Cloud, hosting is self-service: you deploy the bot yourself and set BOT_TOKEN as an environment variable on the application, which keeps the token out of your code. The platform supports python-telegram-bot, aiogram, Telethon, Telegraf and grammY. Long polling works without extra configuration, and an HTTPS subdomain is available if you prefer webhooks. The squarecloud.app configuration file is optional: the dashboard can generate it during deploy, or you can write it at the project root.

Each background application, such as a bot, needs at least 256 MB of RAM, and all plans are paid. Details are in host a Telegram bot on Square Cloud.