Seu próprio bot no Telegram, com Claude respondendo do outro lado

Você já vive dentro do Telegram — grupo de trabalho, aviso de cliente, lembrete pessoal — e queria ter ali um assistente que responde na hora, sem abrir outra aba de chat. A saída rápida é um construtor de bot sem código, tipo ManyChat ou Chatfuel: resolve numa tarde, mas prende você num template pronto e cobra assinatura todo mês pra continuar no ar.

Escrever o próprio bot em Python, com a IA gerando boa parte do código, dá outro resultado: controle total sobre o que o bot faz e nenhuma mensalidade de plataforma. A troca é que a manutenção também fica com você — não tem suporte de terceiro pra chamar quando algo quebra. Já construí bots e integrações de mensageria assim como parte de sistemas de automação pra cliente, e o esqueleto é sempre o mesmo: um token do Telegram, uma chave da Anthropic, e um arquivo Python ligando os dois.

O que você precisa

• Conta no Telegram
• Python 3.10 ou mais recente instalado
• Um editor de texto ou IDE qualquer
• Uma chave de API da Anthropic, gerada em console.anthropic.com
• Disposição pra rodar comando no terminal — não precisa saber programar de antemão, a própria IA ajuda a escrever o código
• Custo: o bot em si não custa nada; a chave da Anthropic cobra por uso, e o Passo 3 mostra a faixa de preço

Passo 1: Criar o bot no BotFather

Abra uma conversa com @BotFather dentro do próprio Telegram — é o bot oficial que cria outros bots. Mande o comando /newbot e responda as duas perguntas: um nome de exibição (o que o usuário vê) e um username, que precisa terminar em "bot" (por exemplo, meu_assistente_bot).

O BotFather devolve um token de API na hora. Trate esse token como senha: nunca cole num print público, nunca mande num grupo, e principalmente nunca commite no Git. Quem tiver esse token controla o bot inteiro.

Passo 2: Preparar o ambiente Python

Crie uma pasta pro projeto, um ambiente virtual, e instale as três bibliotecas que o bot usa:

mkdir meu-bot-telegram
cd meu-bot-telegram
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install python-telegram-bot anthropic python-dotenv

Depois crie um arquivo .env na raiz do projeto com as duas credenciais:

TELEGRAM_TOKEN=token_recebido_do_botfather
ANTHROPIC_API_KEY=chave_da_anthropic

Antes de qualquer commit, adicione .env ao .gitignore. É a mesma regra do Passo 1: token e chave não podem aparecer em texto puro dentro do repositório.

Passo 3: Escrever o bot em Python

Duas bibliotecas fazem o trabalho pesado. A python-telegram-bot, na versão 20 ou mais recente, tem uma API assíncrona — os handlers são funções async def, e o app roda dentro de um Application.builder(). A anthropic é o SDK oficial: o cliente anthropic.Anthropic() já lê a chave ANTHROPIC_API_KEY do ambiente sozinho, sem precisar passar na mão.

O modelo recomendado pra esse uso é o claude-sonnet-5 — equilíbrio bom entre custo e qualidade pra conversa geral. Salve isso como bot.py:

import os
from dotenv import load_dotenv
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, ContextTypes, filters
import anthropic

load_dotenv()
client = anthropic.Anthropic()

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.message.reply_text("Oi! Pode perguntar o que quiser.")

async def responder(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    resposta = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": update.message.text}],
    )
    await update.message.reply_text(resposta.content[0].text)

app = Application.builder().token(os.environ["TELEGRAM_TOKEN"]).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, responder))
app.run_polling()

Cada peça tem um papel fixo. O CommandHandler cuida só do /start, a mensagem de boas-vindas. O MessageHandler com filters.TEXT & ~filters.COMMAND pega qualquer texto que não seja um comando e manda pra função responder. Dentro dela, resposta.content[0].text é onde o SDK guarda o texto que o Claude devolveu. E app.run_polling() mantém o processo vivo, checando o Telegram por mensagem nova o tempo todo.

Passo 4: Testar localmente

Rode python bot.py no terminal, abra o bot no Telegram pelo username escolhido, e mande /start. Depois faça uma pergunta qualquer — "O que é machine learning?" ou "Escreva um haiku sobre programação" servem bem pra ver a resposta chegando.

Um limite aparece rápido nesse teste: o bot não guarda o que foi dito antes. Cada mensagem chega isolada, sem histórico — pedir "resuma o que conversamos" ainda não funciona. Não é falha, é o comportamento padrão de um bot sem memória implementada.

Esse bot, do jeito que está, é fluxo fixo puro: uma entrada, uma chamada ao modelo, uma resposta. Não decide nada sozinho e não encadeia passos — o que é uma escolha, não uma limitação a esconder.

Passo 5: Manter o bot rodando o dia inteiro

Enquanto o terminal estiver aberto e o processo vivo, o bot responde. Fechar o terminal mata o processo, e o bot junto. Duas saídas comuns pra manter rodando sem depender do seu computador ligado: rodar nohup python bot.py & num servidor Linux, ou hospedar numa plataforma como Railway ou Render. As duas costumam ter uma camada gratuita ou de baixo custo — confira o valor atual no site, porque muda com frequência.

Se optar por hospedar fora da sua máquina, o token do Telegram e a chave da Anthropic nunca vão dentro do código-fonte. Entram como variáveis de ambiente da própria plataforma escolhida — o mesmo princípio do .env, só que gerenciado pela hospedagem.

O que pode dar errado

• Token do bot exposto em algum commit do Git: qualquer pessoa com acesso a ele assume o controle do bot inteiro. .env mais .gitignore evita isso desde o início.
• Seguir um tutorial antigo da python-telegram-bot: versões anteriores à 20 usam uma API síncrona diferente da que está aqui. Se o código que você está lendo em outro lugar não bater com este, confira a versão da biblioteca.
• Chamar o SDK da Anthropic de forma síncrona dentro de um handler assíncrono trava a fila de mensagens quando muita gente escreve ao mesmo tempo. Pra uso pessoal ou poucos usuários não faz diferença; num bot com tráfego real, vale investigar uma chamada assíncrona pro modelo.
• O bot "esquecer" a conversa a cada mensagem nova não é falha — é a ausência de memória, que o próximo passo resolve.

Próximos passos

Pedir pra própria IA implementar memória por usuário — guardar o histórico de mensagens e reenviar a cada nova chamada a messages.create — é um bom primeiro prompt depois de terminar este tutorial. Depois vem o deploy em Railway ou Render, pra rodar sem depender do seu computador ligado, e comandos extras como /help e /reset.

Esse bot de poucas linhas é o esqueleto mínimo de qualquer sistema que conecta um canal de mensagem a um modelo de IA. Memória, ferramentas, integração com outro sistema — tudo isso se constrói em cima da mesma base: token de um lado, chave de API do outro, um arquivo Python no meio.