Guide

Telegram BotFather Guide: Create a Bot, Pick a Valid Username, Get and Revoke Your Token

Every BotFather step from /newbot to a working token, the username rules that trip people up, how to replace a leaked token and what each error means.

Last updated: November 2026 11 min read

Quick answer: get a Telegram bot token in five steps

  1. Open @BotFather in Telegram (verified badge) and tap Start.
  2. Send /newbot.
  3. Type a display name, e.g. Acme Support.
  4. Type a username ending in bot, e.g. acme_support_bot (5–32 characters, no spaces).
  5. Copy the token BotFather sends: 110201543:AAHdq…

Then paste it here →Connect your bot to a BetterClaw agent: Settings ▸ Integrations, pick the agent, choose who can message it. Nothing to host.

Already made the bot? Send /mybots, pick it, tap API Token. Leaked it? Send /token and the old one stops working.

Rules checked against Telegram's developer docs on 19 November 2026. Every BotFather message, error and fix is below.

Before you start

You need a Telegram account and Telegram itself, on your phone, on desktop or in a browser at Telegram Web. There is no developer account to register and nothing to pay.

Step 1: Open BotFather in Telegram

Search for @BotFather, open the chat and tap Start. Type / in the message box to see every command it understands; Telegram calls that menu the up-to-date list.

Step 1: Open BotFather — Telegram search showing the verified @BotFather account with the blue checkmark
If the account has no verified badge, or the handle is anything other than @BotFather, close the chat. Real tokens never come from look-alikes.

Telegram's docs also point to a BotFather Mini App with the same functions and a more modern interface, at t.me/BotFather?startapp. The steps below use the classic chat.

Step 2: Send /newbot and name your bot

Send /newbot. BotFather asks for a name first.

The name is what people see in chats and in the bot's contact details. It can be anything, such as Acme Support or Nova, and you can change it later with /setname.

"Alright, a new bot. How are we going to call it? Please choose a name for your bot." What to type

This is BotFather's first question after /newbot, and it's asking for the display name, not the username. Type any name people should see at the top of the chat, for example Acme Support or My Assistant, and press send. Spaces, capitals and emoji are all fine here, and there is no "bot" rule yet; that comes with the next question.

Step 3: Name your bot — BotFather asking 'How are we going to call it?' after /newbot

Step 3: Choose a username that ends in "bot"

Next, BotFather asks for the username in a message that starts Good. Now let's choose a username for your bot. This is the bot's @handle, the name used in search, mentions and its t.me link.

Telegram's rules for the username:

RulePassesFails
Must end in "bot", in any caseacme_support_bot, AcmeSupportBotacme_support
"bot" has to be the endingacme_botbot_acme
5 to 32 characters, "bot" includedacme_botabot (4 characters)
Latin letters, digits and underscores onlyacme_2_botacme-support-bot
Not already takenSomething specific to youAnything BotFather reports as taken

Usernames are not case sensitive, so AcmeSupportBot and acmesupportbot are the same name. And unlike the display name, the username cannot be changed later, Telegram's docs warn, so pick one you would be happy to see in a link for years.

An easy slip is typing the display name again. "Acme Support" fails twice: it has a space, and it doesn't end in "bot".

If BotFather rejects a username, it is one of three problems, and Telegram's API names all three: the username is invalid (wrong characters or length), it is already occupied, or the "bot" suffix is missing (USERNAME_INVALID, USERNAME_OCCUPIED, USERNAME_SUFFIX_MISSING). Fix that one thing and send another.

If BotFather says the username is taken, it is taken by anyone on Telegram, not just by bots. Add your company or product name: acme_support_bot → acmehq_support_bot.

"Good. Now let's choose a username for your bot. It must end in 'bot'." What to type

Now BotFather wants the username: the unique @handle that becomes the bot's t.me link. Type one word, 5 to 32 characters, Latin letters, digits and underscores only, ending in "bot", for example acme_support_bot or AcmeSupportBot. Case doesn't matter. Press send.

If the name is taken, BotFather says so. Add your company name or a number and try again: acme_support_2_bot.

"Sorry, the username must end in 'bot'. E.g. 'Tetris_bot' or 'Tetrisbot'": the fix

You typed a username that doesn't end in "bot". Send a new one that does, for example the same word with _bot added: acme_support becomes acme_support_bot. You don't need to start over with /newbot; BotFather is still waiting for a valid username.

Can a bot username end in ai or agent?

Only as an extra username, and only with Telegram Premium. Telegram's Bot API changelog for 9 November 2026 (Bot API 10.4, checked 19 November 2026) lets Premium users assign secondary usernames ending in "agent", "ai", "app", "game" or "gay" to up to 2 bots they own.

The main username still ends in "bot". When a manager bot creates a bot with one of those endings, Telegram's docs say the ending becomes the secondary username and a regular "bot" username is assigned automatically.

Step 4: Copy your BotFather Telegram token

Once the username is accepted, BotFather sends a success message containing your token. Copy the whole string, digits, colon and everything after it, with no spaces at either end.

Step 5: Copy the token — BotFather's 'Done! Congratulations' message with the HTTP API token

Telegram's docs attach a warning to that token, and it is worth reading twice:

Keep your token secure and store it safely, it can be used by anyone to control your bot.

Every token has two parts:

PartIn Telegram's exampleWhat it is
Before the colon110201543Your bot's numeric ID
After the colonAAHdqTcvCH1vGWJxfSeofSAs0K5PALDsawThe secret, 34 characters in each of Telegram's examples

Already created the bot and need the token again? /mybots → your bot → API Token. It shows the current token without changing anything.

Check that your BotFather token works

Paste this into a browser, with your token in place of <TOKEN> and the word bot kept directly in front of it:

https://api.telegram.org/bot<TOKEN>/getMe

A working token returns "ok": true with your bot's ID, name and username. A wrong, mistyped or revoked one returns "ok": false with Unauthorized in the description. Treat that URL like the token itself, because anyone who sees it has the key.

Lost the token? Look it up before you replace it

If the token is misplaced rather than leaked, send /mybots, pick the bot and tap API Token to see the current one. Nothing changes and nothing breaks.

Only replace it if it may have leaked, because replacing it means updating every place the old one lives.

Then: connect the token to an AI agent

Most guides stop at the token. If you made this bot to put an AI agent behind it, here is where the token goes on three common setups.

OpenClaw (self-hosted)

The fastest route is OpenClaw's CLI, which writes the token into your config for you:

openclaw channels add --channel telegram --token <bot-token>

To edit the config by hand instead, this goes in ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

TELEGRAM_BOT_TOKEN works as an environment fallback for the default account, but the config always wins over it. Start the gateway if it isn't running (openclaw gateway start for the service, or openclaw gateway in a terminal), message your bot, then approve the pairing request:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Pairing codes expire after one hour. If the bot stays quiet after that, our OpenClaw Telegram troubleshooting guide covers the usual causes.

Hermes Agent (self-hosted)

Run the setup wizard and choose Telegram. It asks for the bot token and the user IDs allowed to talk to the bot:

hermes gateway setup

Or add both to ~/.hermes/.env yourself, then start the gateway in the foreground with hermes gateway run:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Don't skip the user IDs. By default the Hermes gateway denies everyone who isn't on an allowlist or paired by DM.

BetterClaw (managed)

BetterClaw doesn't host OpenClaw or Hermes. It is the option if you want the agent, not the server: no config file, no gateway to keep alive and no pairing code in a terminal.

  1. Open Settings ▸ Integrations and select Connect Telegram bot.
  2. Choose the agent that should answer messages.
  3. Paste the token from BotFather.
  4. Choose who can message the bot: All users, or Specific usernames only (comma or newline separated, without the @). Then select Connect.

The bot appears as a card with its agent, username and response mode. Open the bot in Telegram, tap Start and send a message.

OpenClawHermes AgentBetterClaw
Where the token goesopenclaw.json, or TELEGRAM_BOT_TOKEN~/.hermes/.envPasted into Settings ▸ Integrations
Who can message the botPairing by defaultAn allowlist or DM pairingAll users, or a username allowlist
What you keep runningThe OpenClaw gatewayThe Hermes gatewayNothing, it is hosted
Changing the tokenEdit the configEdit .env, restart the gatewayDisconnect and reconnect

Checked: 19 November 2026.

Once it's connected, what a BetterClaw agent can do from Telegram, from inbox questions to a public support bot, is on our Telegram AI agent page.

Is BotFather free and safe to use?

Yes on both counts, as long as you are talking to the real one: BotFather is Telegram's official bot-creation tool. Telegram's developer docs say its bot platform "is free for both users and developers", so creating a bot or a token costs nothing.

BotFather is run by Telegram. The Telegram FAQ calls it "Telegram's official tool for creating bots", and its public page shows the verified badge and, about 8.1 million monthly users (BotFather's Telegram profile, November 2026).

The risks come from look-alikes and from what happens to the token afterwards:

  • Check the handle is exactly @BotFather, with the verified badge, before you send anything.
  • Never paste a token into a "token generator" site or an unofficial bot. Real tokens come from BotFather, or from a manager bot you chose yourself (see below).
  • Treat the token like a password. Telegram says everyone who has it "will have full control over your bot".

Bots that create bots: the 2026 alternative to BotFather

Since Telegram's April 2026 update (Bot API 9.6), a bot can create and manage other bots on your behalf. Telegram calls these managed bots: you confirm a pre-filled name and username, the bot is created under your account, and the manager bot fetches its token through the Bot API.

Some agent tools now create the bot for you. Hermes Agent's dashboard, for one, has a Create with QR button: scan it in Telegram and Hermes makes the bot and saves its token, as our Hermes Agent Telegram setup guide shows alongside the manual route.

Know what you are agreeing to. Telegram's docs say a manager bot can control the bot it created, receive and answer its messages, and replace its token, so only use a manager you trust. You can still manage the bot from BotFather like any other bot you own.

Telegram's bot features docs now include a dedicated "AI Agents" section, and managed bots and secondary "ai" and "agent" usernames both arrived in 2026: the platform expects bots to be agents.

Watch: Telegram bot token to live agent in two minutes

How to Connect Your BetterClaw AI Agent to Telegram in 2 Minutes

The full flow in about two minutes: create the bot in BotFather, copy the token and connect it to a BetterClaw agent.

Keep your bot token secret

Telegram's introduction for developers puts it plainly: "Everyone who has your token will have full control over your bot." Whoever holds it can read what people send your bot and reply as your bot.

Tokens leak from places people put them on purpose:

  • A .env file committed to Git, public or private. History outlives the file you deleted.
  • A screenshot of the BotFather chat, or a log pasted into a support chat.
  • The same token copied onto a second machine "just for testing".
A bot token is a password with no second factor. Whoever holds it is your bot.

For the wider problem of keys sitting in files, our guide on how to stop storing API keys in plaintext covers vaults, encryption and rotation.

TELEGRAM_BOT_TOKEN: what it is and where to put it

TELEGRAM_BOT_TOKEN is the environment variable most agent frameworks read for the token BotFather gave you. The value is the whole string, digits, colon and secret, with no quotes and no bot prefix. OpenClaw reads it as a fallback for channels.telegram.botToken; Hermes Agent reads it from ~/.hermes/.env. BetterClaw has no variable: you paste the token into Settings ▸ Integrations once and it is stored encrypted.

Many tools, OpenClaw and Hermes Agent among them, read the token from an environment variable called TELEGRAM_BOT_TOKEN. Keep the real value in one place and point everything else at it.

WhereHow it looksRule
.envTELEGRAM_BOT_TOKEN=110201543:AAH...No spaces around =; add .env to .gitignore before the first commit
config.yaml or config.jsonA reference to the variablePoint to the variable, never paste the token
CI, such as GitHub ActionsA repository secret named TELEGRAM_BOT_TOKENNever print it in build logs
Staging and productionOne bot for eachTwo programs polling one token get 409 Conflict errors

Did your Telegram bot token leak? A 30-second check

Run this in your project folder. It searches every commit on every branch, not just the files you have now:

git log -p --all | grep -E '[0-9]{6,}:[A-Za-z0-9_-]{30,}'

If it prints a match, or the token ever sat in a public repo, a chat or a screenshot, treat it as compromised and replace it now. Deleting the file or the commit does not stop the token working.

Rather not keep a bot token in a file at all? On BetterClaw you paste it once into Settings ▸ Integrations, it is stored encrypted, and your agents never see it. Plans start at $19 a month and Telegram comes with Pro at $49 ($39 billed annually). See BetterClaw plans

Revoke a BotFather token and get a new one

A bot has no password reset. Replacing the token is how you revoke the old one.

  1. Open your chat with @BotFather and send /token. Telegram's docs name this command for a token that is compromised or lost.
  2. Pick the bot whose token you want to replace.
  3. Copy the new token BotFather sends. The old one stops working.
  4. Check it: run the old token through getMe. It should now return Unauthorized; if it still works, it hasn't been revoked yet.
  5. Put the new token everywhere the old one lived, then restart whatever runs the bot.

Searching for /revoke? Many tutorials use it for the same job. Type / in BotFather and use whichever of the two its menu shows, then let step 4 confirm it worked.

A revoke you haven't tested is a revoke you are hoping for.

Revoking changes the key and nothing else: the bot and its username stay. Deleting is a different command, /deletebot, which removes the bot, frees its username and cannot be undone.

Where the old token livedWhat to do
BetterClawDisconnect the bot in Settings ▸ Integrations, then connect it again with the new token
OpenClawUpdate botToken (or TELEGRAM_BOT_TOKEN), then check with openclaw channels status --probe
Hermes AgentUpdate TELEGRAM_BOT_TOKEN in ~/.hermes/.env, then run hermes gateway restart
.env files, CI secrets, webhooksReplace the value and redeploy

Common BotFather errors and what they mean

BotFather problems come in two kinds: BotFather refusing to create the bot, and a bot that exists but stays silent. Here is each one, with what Telegram documents about it.

"Sorry, this username is already taken. Please try something different."

Someone on Telegram, person or bot, already owns that @handle. BotFather is still waiting, so you do not need to start over. Send another username: add your company, product or a region, acme_support_bot → acmehq_support_bot or acme_support_uk_bot. Numbers work but are easy to mistype. The API name for this reply is USERNAME_OCCUPIED.

"Sorry, the username must end in 'bot'."

Covered under Step 3: the username must end in 'bot' fix.

Token revoked, or "Unauthorized" when you connect it

If getMe returns "ok": false with Unauthorized, or your agent platform says the token was rejected (BetterClaw shows "Telegram rejected this bot token"), the token is wrong or has been replaced. Common cause: someone ran /token or /revoke in BotFather, which kills the old token everywhere at once. Send /mybots → your bot → API Token, copy the current one and paste it back into your config or into Settings ▸ Integrations. If you did not revoke it and it still fails, check for a trailing space or a missing character: the token is case-sensitive and the whole string is required. BetterClaw's side of this is in our Telegram integration troubleshooting.

"Unfortunately, you cannot create new bots at this time"

Telegram does not document this reply or publish a wait time. It appears when the account has hit the bot cap (20 bots, 40 with Premium; count them in /mybots and free one with /deletebot or a transfer), or when the account itself is limited: new numbers, some virtual or VoIP numbers, and accounts reported for spam. Try again later, check @SpamBot, and if you are running an agent read which Telegram ban you actually have and what to do, which covers this message, 401s, 429s and appeals.

"Oops! Please make sure the new owner has sent at least one message to the bot and didn't block it."

You'll see this when transferring a bot from /mybots with Transfer Ownership. Telegram's docs say a bot can only be transferred to someone who has interacted with it at least once. Ask the new owner to open the bot's t.me link, press Start, send any message and make sure they haven't blocked it, then run the transfer again. The transfer is permanent, so check the account before you confirm.

BotFather tells you to wait

If you fire off a burst of commands, BotFather may say you've made too many attempts and give a wait time. Wait the full time before you try again. Telegram applies the same kind of wait across its API, where the error reads "a wait of X seconds is required".

BotFather not working or not answering

  • Check you are in the verified @BotFather chat, not a look-alike.
  • Start over: send /newbot again and answer each question in order.
  • Still stuck? Telegram's docs send bot platform problems to @BotSupport.

The bot exists but doesn't reply

A token on its own does nothing. Telegram's Bots FAQ says a working bot needs a BotFather account plus a backend connected through the API, so something has to run behind the token: your own code, OpenClaw, Hermes Agent or BetterClaw.

When something is running and the bot still stays quiet, the reply or the error tells you why:

What you seeWhat it meansFix
Silence in a brand-new chatBots can't start conversations; a person has to message firstOpen the bot, tap Start, send a message
Silence for some people onlyYour agent or framework has an allowlistAdd their username or ID to it
Silence in a groupPrivacy mode is on by default, so the bot only sees commands and replies meant for itMake the bot an admin, or turn privacy off with /setprivacy and re-add the bot
Unauthorized (401)Wrong, mistyped or revoked tokenCopy the current token and update your config
Conflict: terminated by other getUpdates request; make sure that only one bot instance is running (409)Two programs are polling the same tokenStop one, or give each its own bot
Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first (409)A webhook is set, so polling is blockedCall deleteWebhook, or connect the token to one platform only
Too Many Requests: retry after N (429)A flood limit: about one message a second per chat, 20 a minute per group, about 30 a second in bulkWait N seconds, then slow down

Checked: 19 November 2026.

Both 409 messages mean the same thing underneath: the token is in use in two places at once. If you run Hermes, our Hermes Telegram 409 Conflict fix walks through it step by step.

How to find your Telegram chat ID

The token identifies your bot. A chat ID identifies a conversation, and tools ask for it when they need to know where to send messages, as a chat_id field or a TELEGRAM_CHAT_ID variable.

You can read it with your own token, so there is no need to hand that token to a third-party "chat ID" bot:

  1. Open your bot, tap Start and send any message, such as "hi".
  2. Open https://api.telegram.org/bot<TOKEN>/getUpdates in a browser.
  3. Find "chat":{"id": ...} inside message. That number is the chat ID.
Chat typeWhat the ID looks like
Private chatA positive number, the same as the person's user ID
Basic groupA negative number, such as -4512345678
Supergroup or channelA negative number starting with -100, such as -1001234567890

If a basic group is upgraded to a supergroup, its ID changes, so read it again.

If getUpdates comes back empty, send a fresh message: Telegram keeps pending updates for 24 hours at most. In groups, privacy mode also hides ordinary messages from the bot.

If it returns the webhook 409 error from the table above instead, a webhook is set, which is often the case once the token is connected to an agent platform. Read the chat ID before you connect, or from your platform's logs.

Optional: customise your bot

Send these to BotFather before or after you connect the bot:

CommandWhat it changes
/setnameThe display name
/setdescriptionThe "What can this bot do?" text, up to 512 characters
/setabouttextThe short profile bio, up to 120 characters
/setuserpicThe profile picture
/setcommandsThe command menu people see when they type /
/setprivacyWhether the bot sees every group message
/setjoingroupsWhether the bot can be added to groups at all
/deletebotDeletes the bot and frees its username, for good

Quick reference

TaskWhat to sendWhere
Create a bot/newbot, then a name, then a username ending in botBotFather chat
See the current token/mybots, pick the bot, API TokenBotFather chat
Replace a leaked token/token, pick the bot, update every copyBotFather chat
Test a tokenhttps://api.telegram.org/bot<TOKEN>/getMeBrowser
Find a chat IDhttps://api.telegram.org/bot<TOKEN>/getUpdatesBrowser
Delete a bot/deletebot, which cannot be undoneBotFather chat

BotFather is the quick part: two questions, one token, done before your coffee cools.

The token is the part that stays with you. Keep one copy in one safe place, give every environment its own bot, and practise the replacement once before you need it.

Want help putting an agent behind your bot?

If the bot is the easy part and the agent is the real project, a second pair of eyes helps. Our AI automation audit starts with a 30-minute call about how your team works, and within 5 business days you get a written report on where agents fit.

Book an AI automation audit

Frequently asked questions

Is BotFather free?

Yes. BotFather is Telegram's official bot-creation tool and Telegram says its bot platform is "free for both users and developers". Creating bots and tokens costs nothing. The default cap is 20 bots per account, or 40 with Telegram Premium (Telegram's client config, checked 19 November 2026).

Is BotFather safe and official?

Yes, if it is the real one: @BotFather, with Telegram's verified badge, run by Telegram. Look-alikes exist, so check the exact handle and never send a token to any other bot or site. Note that bot messages are not end-to-end encrypted; Telegram's servers can read them.

Why does the username have to end in bot?

Telegram requires every bot username to end in "bot", such as tetris_bot or TetrisBot, and to be 5 to 32 Latin letters, digits or underscores. The rule applies to the username, not the display name. Premium users can add a secondary username ending in agent, ai, app, game or gay to up to 2 bots, but the main username still ends in bot.

Where do I find a token I already created?

Send /mybots to @BotFather, pick the bot and tap API Token. BotFather shows the current token without changing it. Only use /token (or /revoke, if that is what your menu shows) when the token may have leaked, because that replaces it and the old one stops working everywhere.

How do I get a Telegram bot token from BotFather?

Open @BotFather in Telegram and send /newbot. Give the bot a display name, then a username that ends in "bot" and is 5 to 32 characters long. BotFather replies with the token, a string like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw.

How do I revoke a bot token in BotFather?

Send /token to @BotFather and pick the bot, which is the command Telegram's docs name for a compromised or lost token. BotFather issues a new token and the old one stops working. If your BotFather menu shows /revoke instead, use that, then test the old token with getMe to confirm it now returns Unauthorized.

Why does BotFather say I cannot create new bots?

Telegram doesn't document that reply, so check the limits it does document: the bot cap (20 bots without Premium, 40 with it, by default) and account limits after spam reports, which you appeal through @SpamBot. If neither applies, try again later, and contact @BotSupport if it persists.

Where do I put TELEGRAM_BOT_TOKEN?

In an environment variable, usually a .env file listed in .gitignore, or in your CI secret store. Config files should reference the variable rather than hold the token. On BetterClaw you paste the token into Settings ▸ Integrations instead, where it is stored encrypted.

BotFather says "Good. Now let's choose a username for your bot. It must end in 'bot'." What do I type?

Type a single word of 5 to 32 Latin letters, digits or underscores that ends in "bot", for example acme_support_bot. This is the bot's unique @username and t.me link, so nobody else on Telegram can already be using it.

BotFather says "Sorry, the username must end in 'bot'." How do I fix it?

Send a new username that ends in "bot" or "_bot", for example change acme_support to acme_support_bot. You don't need to restart /newbot; BotFather keeps waiting for a valid username. The rule applies only to the username, not to the display name you chose a step earlier.

What does "Alright, a new bot. How are we going to call it?" mean?

BotFather is asking for the bot's display name, the name people see at the top of the chat. Type anything, such as Acme Support, and send it. Spaces and capitals are allowed and there is no "bot" rule for this step. The username, which does have to end in "bot", is the next question.