Como criar um bot do Telegram no BotFather e pegar o token

Todo bot do Telegram começa no mesmo lugar: uma conversa com o BotFather, o bot oficial do Telegram que cria e configura outros bots. Não há portal de desenvolvedor nem formulário. Você responde algumas mensagens e recebe um token, uma sequência de caracteres que o seu código usa para provar que controla o bot.

Este guia cobre o caminho inteiro: criar o bot, escolher o username, proteger o token, conferir se ele funciona e rodar um primeiro bot. O código usa Python com a API da versão 22 do python-telegram-bot, que exige uma versão do Python ainda com suporte (a mínima está na documentação da biblioteca).

O que você precisa antes de começar?#

• Uma conta no Telegram, no celular ou no app de desktop.
• Uma versão do Python ainda com suporte, só se você quiser rodar o código de teste.
• Um lugar para guardar segredos, como uma variável de ambiente ou um arquivo .env.

Como criar um bot no BotFather?#

1. Abra o @BotFather no Telegram. Confira se o username é exatamente @BotFather, porque existem contas parecidas.
2. Envie /newbot.
3. O BotFather pede um nome. É o nome de exibição que aparece nas conversas e nos dados de contato. Pode ter espaços e pode ser trocado depois com /setname.
4. O BotFather pede um username. Ele precisa ter de 5 a 32 caracteres, usar só letras latinas, números e sublinhado e terminar em bot, como tetris_bot ou TetrisBot. O username não diferencia maiúsculas de minúsculas, precisa ser único e não pode ser alterado depois.
5. O BotFather responde com o token e um link para o seu bot, t.me/<username>.

Se o username já estiver em uso, o BotFather pede outro. Tente acrescentar uma palavra ou um número.

Como é o token e o que ele permite fazer?#

O token é um número, dois-pontos e uma sequência longa de letras e dígitos. A documentação do Telegram mostra este formato:

110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Esse exemplo não é uma credencial real. O token autentica o seu bot, não a sua conta. Quem tiver o token controla o bot, então trate-o como uma senha. O tutorial do Telegram chama de má prática deixar o token escrito no código-fonte e recomenda variáveis de ambiente ou um arquivo de configuração.

Se ele vazar, revogue-o pelo BotFather e gere um novo (a documentação do Telegram indica o /token para isso). Atualize todos os lugares onde o bot roda e chame o getMe (abaixo) com o token antigo para confirmar que ele parou de funcionar. Veja o que são variáveis de ambiente e o que é um arquivo .env para manter o token fora do seu repositório.

Como testar se o token funciona?#

A Bot API é HTTPS puro. Toda requisição vai para https://api.telegram.org/bot<token>/NOME_DO_METODO, com a palavra bot antes do token. O método getMe devolve o perfil do próprio bot, o que faz dele um bom teste.

export BOT_TOKEN="cole-seu-token-aqui"
curl "https://api.telegram.org/bot${BOT_TOKEN}/getMe"

Um token válido devolve um JSON com "ok": true e um objeto result com o id, o nome e o username do bot. Um inválido devolve "ok": false com error_code 401 (ou 404 quando o token está malformado).

Como rodar um primeiro bot?#

Instale a biblioteca e escreva um bot que responde ao /start e repete as mensagens de texto.

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("Oi! Mande uma mensagem que eu repito.")


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()

Rode com a BOT_TOKEN definida no mesmo terminal, abra o link do seu bot e toque em Iniciar. O bot usa long polling: ele pergunta ao Telegram se há atualizações novas, então não precisa de URL pública. Para entender a diferença entre polling e webhook, leia como hospedar um bot do Telegram 24/7.

Como terminar de configurar o bot no BotFather?#

Estes comandos dão acabamento ao bot. Todos são opcionais:

• /setdescription: texto de até 512 caracteres mostrado em "O que este bot pode fazer?" quando o usuário abre a conversa pela primeira vez.
• /setabouttext: uma bio mais curta, de até 120 caracteres, mostrada na página de perfil.
• /setcommands: a lista de comandos que o usuário vê ao digitar /.
• /setname: muda o nome de exibição.

Os comandos registrados assim só montam um menu. O seu código ainda precisa tratar cada um deles.

Quais são os erros mais comuns?#

• telegram.error.InvalidToken ou 401 Unauthorized: o token está errado, tem espaços ou aspas sobrando ou foi revogado no BotFather. Copie de novo.
• KeyError: 'BOT_TOKEN': a variável de ambiente não está definida no terminal que roda o script.
• O bot não responde: o processo não está rodando, ou você nunca tocou em Iniciar.
• 409 Conflict (telegram.error.Conflict): duas instâncias usam o mesmo token com long polling, ou há um webhook configurado. Pare a cópia extra ou remova o webhook com deleteWebhook.
• Username recusado: não termina em bot, foge dos 5 a 32 caracteres ou já está em uso.

Se o bot estava funcionando e parou de responder, o guia bot do Telegram não responde percorre as causas uma a uma.

Como fazer isso na Square Cloud#

O bot acima só responde enquanto o processo dele roda. No seu computador, isso acaba quando a máquina hiberna, então um bot que outras pessoas usam precisa de uma hospedagem sempre ligada.

Na Square Cloud, a hospedagem é self-service: você mesmo faz o deploy do bot e define a BOT_TOKEN como variável de ambiente da aplicação, o que mantém o token fora do código. A plataforma suporta python-telegram-bot, aiogram, Telethon, Telegraf e grammY. O long polling funciona sem configuração extra, e há um subdomínio HTTPS disponível se você preferir webhook. O arquivo de configuração squarecloud.app é opcional: o painel pode gerá-lo no deploy, ou você pode escrevê-lo na raiz do projeto.

Cada aplicação de fundo, como um bot, precisa de no mínimo 256 MB de RAM, e todos os planos são pagos. Os detalhes estão em hospedar um bot do Telegram na Square Cloud.