Como criar um bot de Telegram do zero (com código real, não só o BotFather)

Abri o terminal, colei um token que o BotFather tinha acabado de me dar e rodei quinze linhas de Python. Vinte segundos depois, meu celular vibrou: o bot tinha respondido “pong” numa conversa que eu mesmo iniciei um minuto antes. Não teve deploy, não teve servidor, não teve conta em nenhuma nuvem — só um script rodando na minha própria máquina. É por isso que a barreira de entrada pra criar um bot de Telegram é menor do que a maioria das pessoas imagina, e maior do que os tutoriais de “5 passos” fazem parecer.

Este post é pra quem já passou pelo guia de melhores bots de Telegram e descobriu que os prontos não fazem exatamente o que precisa. Aqui a proposta é diferente: sair do BotFather com um token guardado e chegar a um bot que responde de verdade, com código, sem enrolação de “e depois você programa” — que é onde a maioria dos guias para.

A versão de 30 segundos

Todo bot do Telegram nasce em três passos: (1) você registra o bot no @BotFather e recebe um token; (2) escreve um programa que fica perguntando ao servidor do Telegram “chegou mensagem nova?” (polling) ou recebe um aviso automático (webhook); (3) esse programa lê a mensagem e responde chamando a Bot API. Não existe mistério — é uma API HTTP como qualquer outra, só que o “cliente” do outro lado é o app do Telegram.

Conceito 1 — o token não é a conta, é a chave

Quando você conversa com o @BotFather e manda /newbot, ele pede um nome de exibição e um @username (que precisa terminar em “bot”). No fim, ele entrega uma string parecida com 123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw.

Essa string é o bot, no sentido prático: quem tiver esse token controla a conta inteira — pode ler atualizações, enviar mensagens em nome do bot e mudar suas configurações. Não é exagero tratar o token como senha de banco. Nunca cole ele num repositório público, num print de tela ou numa mensagem de grupo — o mesmo cuidado que vale pra qualquer credencial, como já detalhamos no guia de segurança em grupos de Telegram. Se vazar, o comando /revoke no próprio BotFather gera um token novo e invalida o antigo na hora.

A documentação oficial para desenvolvedores explica esse fluxo completo em core.telegram.org/bots — vale ler antes de programar qualquer coisa que vá para produção.

Conceito 2 — polling vs. webhook (a escolha que todo tutorial pula)

Aqui está a decisão que a maioria dos guias “crie seu bot em 5 minutos” esconde: como o seu programa vai saber que chegou mensagem nova?

• Long polling (getUpdates): seu script pergunta pro servidor do Telegram, em loop, “tem algo novo?”. Se não tem, o servidor segura a conexão aberta por alguns segundos e responde vazio; se tem, devolve na hora. Simples, roda em qualquer máquina — inclusive seu notebook, sem IP público, sem certificado SSL. É como comecei o bot do parágrafo de abertura.
• Webhook (setWebhook): você registra uma URL HTTPS sua, e o Telegram empurra cada atualização pra ela assim que acontece. Exige servidor com endereço público e certificado válido, mas é o modelo certo pra produção — sem o script ficando perguntando o tempo todo, e sem atraso de resposta.

Regra prática: comece com polling pra testar a lógica do bot localmente. Migre pra webhook só quando for hospedar de verdade — a própria API detalha os dois modos em core.telegram.org/bots/api.

Conceito 3 — o menor bot funcional (código real)

Isto é um bot completo, em polling, sem nenhuma biblioteca externa além da já embutida urllib do Python — só pra deixar claro que não tem mágica escondida, é requisição HTTP simples:

import json
import time
import urllib.request

TOKEN = "SEU_TOKEN_AQUI"
API = f"https://api.telegram.org/bot{TOKEN}"

def get_updates(offset=None):
    url = f"{API}/getUpdates?timeout=30"
    if offset:
        url += f"&offset={offset}"
    with urllib.request.urlopen(url, timeout=35) as r:
        return json.load(r)["result"]

def send_message(chat_id, text):
    data = json.dumps({"chat_id": chat_id, "text": text}).encode()
    req = urllib.request.Request(
        f"{API}/sendMessage", data=data,
        headers={"Content-Type": "application/json"}
    )
    urllib.request.urlopen(req)

offset = None
while True:
    for update in get_updates(offset):
        offset = update["update_id"] + 1
        msg = update.get("message", {})
        if msg.get("text") == "/start":
            send_message(msg["chat"]["id"], "pong")
    time.sleep(1)

Isso já é um bot funcional: registrado, respondendo /start com “pong”, em polling. Em produção, a maioria dos devs troca esse loop cru pela biblioteca python-telegram-bot ou aiogram, que resolvem retry, filas e webhook prontos — mas entender o esqueleto acima ajuda a debugar quando a biblioteca “some” e não avisa por quê.

Onde isso falha

Um bot rodando com time.sleep(1) num notebook para assim que a tela dorme ou a internet cai — não é confiável pra nada que precisa responder 24h, tipo um bot de moderação de grupo grande. Pra isso, ele precisa de um processo que reinicia sozinho (systemd, supervisor, ou um provedor de hospedagem com restart automático) e, idealmente, webhook em vez de polling, porque webhook não tem essa dependência de loop contínuo rodando sem parar.

Outro ponto onde iniciante tropeça: dar ao bot permissões de admin num grupo (banir, deletar mensagens) sem o código estar pronto pra tratar esses eventos direito. Se o seu bot só responde /start e você já promove ele a admin com poder de banir, está confiando numa lógica que ainda não existe. O guia de como administrar e moderar um grupo no Telegram mostra quais permissões cada função de moderação realmente exige — vale conferir antes de promover o bot que você acabou de criar.

O critério que aplicamos antes de listar um bot no diretório

Todo bot submetido para entrar em /bots passa pelo mesmo teste manual: mandamos /start e cronometramos a resposta. Se o bot não responder em até 10 segundos, ele não entra na lista naquele ciclo de curadoria — é sinal de token revogado, servidor webhook fora do ar, ou processo de polling que morreu sem ninguém notar. Não é regra da Bot API, é critério nosso: um diretório com bot quebrado listado é pior do que um diretório menor com tudo funcionando.

Se você programou o seu e quer testar antes de submeter, o mesmo teste serve: abra o chat, mande /start, cronometre. Se demorar, o problema quase sempre está no polling que caiu — não na API do Telegram.

---

Criar um bot de Telegram do zero não exige framework nem conta em nuvem paga — exige entender que, por trás do BotFather, tem uma API HTTP comum esperando requisição. Comece com polling local pra validar a lógica, trate o token como senha, e só migre pra webhook quando o bot for hospedado de verdade. O resto — biblioteca, banco de dados, deploy — é escolha de stack, não pré-requisito pra começar.