Crie um bot do Telegram com IA: guia passo a passo

Para criar um bot do Telegram com IA, peça a um agente de código (Claude Code, Codex ou similar) para escrever um bot com python-telegram-bot, coloque o token em um arquivo .env e rode primeiro na sua própria máquina com polling. A partir daí você adiciona comandos, estado salvo, respostas com LLM e, por fim, deixa rodando 24/7 em um servidor.

Este guia segue o Telegram de ponta a ponta e depois mostra como adaptar o mesmo bot para o Discord. Cada passo vem com um prompt que você pode colar no agente.

O que vamos construir

O bot de exemplo vai:

• Responder a /start e /help.
• Salvar notas com /note <text> e listá-las com /notes (estado salvo).
• Responder a mensagens comuns com um LLM, com um limite diário por usuário.
• Opcionalmente, falar só com usuários que você permitir.
• Rodar sem parar em um servidor com systemd ou Docker.

É um ótimo primeiro projeto de vibe coding: pequeno, você vê o resultado no celular na hora e ele é útil de verdade.

Escolhendo a stack: Python ou TypeScript?

Duas boas opções:

• Python + python-telegram-bot: maduro, bem documentado e assíncrono. A escolha natural se o seu código de IA, dados ou automação está em Python.
• TypeScript + grammY: moderno, tipado e leve, e se dá bem com webhooks em plataformas serverless. Vá por aqui se você já vive no Node.js.

Vou usar Python aqui; troque o nome da biblioteca nos prompts e os mesmos passos funcionam com o grammY.

Configuração:

mkdir telegram-bot && cd telegram-bot
git init
python3 -m venv .venv && source .venv/bin/activate
pip install python-telegram-bot python-dotenv anthropic
printf ".env\n.venv/\n*.db\n" >> .gitignore

Uso o SDK da Anthropic como exemplo de LLM; com outro provedor, troque o pacote, a ideia é a mesma.

Passo 1: pegue um token e coloque no .env

Pegue o token no fluxo oficial de criação de bots do Telegram: você cria um bot novo dentro do Telegram, escolhe um nome de exibição e um username único terminado em “bot”, e no final recebe um token longo. Esse token é a senha do bot; quem tiver ele pode mandar mensagens como se fosse o seu bot.

O arquivo .env:

TELEGRAM_TOKEN=your-token
LLM_API_KEY=your-api-key
LLM_MODEL=the-model-you-use
ALLOWED_USER_IDS=123456789
DAILY_LLM_LIMIT=30

Não cole o token nem a chave de API no chat com o agente. Ele não precisa dos valores, só de saber que eles vêm do .env. Se o token vazar algum dia, revogue-o no mesmo fluxo oficial e pegue um novo.

Passo 2: o primeiro prompt

Abra o agente na pasta do projeto e peça o bot mais simples que funcione:

Set up a simple Telegram bot with python-telegram-bot (async, ApplicationBuilder).
- Read the token from .env with python-dotenv. Never open or print .env.
- Layout: bot.py (startup and handler registration), handlers.py (commands),
  storage.py (SQLite later), config.py.
- Add /start and /help; /help lists all commands.
- Reply politely to unknown commands.
- Use polling. Use Python logging; never log the token.
- Add an error handler: log the error and send the user a short apology.
When done, tell me how to run it.

Rode:

python bot.py

Procure seu bot no Telegram e mande /start. Se ele responder, o primeiro ciclo está pronto. Se não, cole o erro do terminal no agente do jeito que está; normalmente é uma variável de ambiente que não foi lida.

Passo 3: comandos e estado salvo

A maioria dos bots precisa lembrar de coisas: configurações do usuário, notas, contadores de uso. Tudo o que fica em memória some quando o bot reinicia. Para um bot pequeno, o SQLite dá conta, sem servidor de banco de dados para manter.

Add SQLite to storage.py (data/bot.db).
- notes table: id, user_id, text, created_at.
- usage table: user_id, date, llm_count.
- /note <text> saves a note, /notes lists the user's last 10 notes,
  /delete <id> deletes a note only if it belongs to that user.
- All SQL must be parameterized (no string concatenation).
- Write pytest tests for the storage functions and run them.

O “only if it belongs to that user” (só se pertencer àquele usuário) importa. Agentes costumam pular verificações de autorização como essa, e de repente qualquer um que digitar /delete 5 consegue apagar a nota de outra pessoa.

O python-telegram-bot também tem opções próprias de persistência, como o PicklePersistence, que ajudam com estado de conversa (formulários de várias etapas, por exemplo). Para dados de usuário, acho o SQLite mais transparente.

Passo 4: respostas inteligentes com um LLM

Agora a parte que faz dele um bot de IA: enviar mensagens comuns para um LLM e devolver a resposta.

# llm.py
import os
from anthropic import AsyncAnthropic

client = AsyncAnthropic(api_key=os.getenv("LLM_API_KEY"))

async def reply(history: list[dict]) -> str:
    resp = await client.messages.create(
        model=os.getenv("LLM_MODEL"),
        max_tokens=500,
        system="You are a helpful Telegram assistant who answers briefly.",
        messages=history[-10:],  # only the last 10 messages
    )
    return resp.content[0].text

Um prompt para o agente:

Send plain text messages to reply() in llm.py.
- Keep the last 10 messages per user in memory (alternating user/assistant).
- /reset clears the conversation history.
- Enforce DAILY_LLM_LIMIT per user per day (usage table); when it's reached,
  send a clear message.
- If ALLOWED_USER_IDS is not empty, only answer those users.
- Send the "typing..." action while the LLM call runs.
- Split replies longer than Telegram's message length limit.
- On API errors, send the user a short message and log the error.

Por que os limites? Um bot público de LLM que alguém descobre e enche de mensagens vai inflar sua conta. Um limite diário, uma lista de permitidos e um histórico curto são as três formas mais simples de manter o custo sob controle. Quanto mais longo o histórico, mais tokens você envia em cada requisição.

Passo 5: polling ou webhook?

Um bot pode receber mensagens do Telegram de duas formas:

• Polling (long polling): o bot fica perguntando ao Telegram “tem algo novo?”. Configuração zero: sem endereço HTTPS, domínio ou porta aberta. Ideal para desenvolvimento e para bots pequenos e médios em um único servidor.
• Webhook: o Telegram envia cada atualização nova para um endereço HTTPS que você informa. Nada fica esperando, e em plataformas serverless (funções que rodam por requisição) é a única opção. Em troca, você precisa de um endpoint HTTPS válido e deve verificar se as requisições vêm mesmo do Telegram, com um caminho secreto ou um token secreto.

Minha regra: comece com polling e passe para webhook quando realmente precisar. Não dá para usar os dois ao mesmo tempo com o mesmo token; o polling não funciona enquanto um webhook estiver definido.

Passo 6: rodando 24/7 em um servidor

Quando o seu notebook desliga, o bot fica mudo. Uma VPS Linux pequena basta, e com polling você nem precisa de domínio.

systemd

# /etc/systemd/system/telegram-bot.service
[Unit]
Description=Telegram bot
After=network-online.target

[Service]
User=bot
WorkingDirectory=/home/bot/telegram-bot
EnvironmentFile=/home/bot/telegram-bot/.env
ExecStart=/home/bot/telegram-bot/.venv/bin/python bot.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now telegram-bot
journalctl -u telegram-bot -f

Docker

Peça ao agente para escrever um Dockerfile e um docker-compose.yml com restart: unless-stopped, env_file: .env e um volume para data/. Esqueça o volume e o seu banco SQLite é apagado toda vez que o contêiner é recriado.

Não rode o mesmo bot com polling em dois lugares (por exemplo, no notebook e no servidor); o Telegram recusa isso com um erro de conflito. Use um bot de teste separado, com token próprio, para desenvolvimento.

Passo 7: adaptando para o Discord

Bots do Discord são parecidos no conceito, com algumas diferenças importantes:

• Token e aplicação: você cria uma aplicação no portal de desenvolvedores do Discord, adiciona um bot a ela e pega o token ali. Você adiciona o bot ao seu servidor com um link de convite que pede o mínimo de permissões necessárias.
• Intents: para ler o conteúdo das mensagens, você precisa ativar o message content intent tanto no portal quanto no código. Se o seu bot não enxerga as mensagens, quase sempre é por isso.
• Modelo de conexão: bots do Discord mantêm uma conexão WebSocket persistente com o gateway, então o bot precisa ser um processo de longa duração; ele não funciona como função serverless.
• Comandos: slash commands são o jeito moderno, e precisam ser registrados no Discord.
• Bibliotecas: discord.py para Python, discord.js para Node.js.

A abordagem mais limpa é separar a lógica do bot da plataforma. Um prompt:

Separate the bot logic from the platform:
- core/ holds platform-independent functions: handle_note, list_notes,
  ask_llm. They take user_id and text and return text.
- Rewrite telegram_bot.py so its handlers call core/.
- discord_bot.py: /note, /notes and /ask slash commands with discord.py,
  all calling core/. DISCORD_TOKEN comes from .env.
- Add a platform column in storage so Discord and Telegram user ids don't mix.
- Keep existing tests passing; extend the tests for core.

Agora os dois bots compartilham o mesmo banco de dados e a mesma lógica de LLM, e cada um só cuida dos detalhes da própria plataforma.

Erros comuns: o que a IA costuma errar

• Escrever contra uma API antiga. O python-telegram-bot passou a ser assíncrono na versão 20, e os agentes às vezes misturam exemplos síncronos antigos. Se der erro, peça ao agente para conferir a versão instalada (pip show python-telegram-bot) e corrigir o código com base na documentação dessa versão.
• Token fixo no código. O agente pode querer colocar o token no bot.py “só para testar rápido”. Diga não.
• Falta de verificação de autorização. Comandos de admin acabam abertos para todos, ou usuários conseguem acessar os dados uns dos outros.
• Código bloqueante. Um time.sleep ou uma chamada HTTP síncrona dentro de um handler assíncrono congela o bot inteiro.
• Erros engolidos. Sem um error handler, o bot simplesmente para de responder em silêncio.
• Estado em memória. Tudo zera quando reinicia.
• Não dividir mensagens longas. Quando o LLM escreve uma resposta longa, o Telegram recusa a mensagem.

Segurança

• Tokens e chaves de API ficam só no .env, e o .env está no .gitignore.
• Nunca cole chaves em um chat, em um print ou em um relatório de bug.
• Leia os comandos que o agente quer rodar antes de aprovar, principalmente qualquer coisa que leia o .env ou envie dados para fora.
• Ao repassar texto de usuários para um LLM, assuma que ele pode tentar sobrescrever suas instruções (prompt injection). Não dê ao bot habilidades perigosas, como rodar comandos ou apagar arquivos.
• Avise seus usuários que você guarda os dados deles e os envia a um provedor de LLM.
• Não rode o bot como root no servidor; aplique chmod 600 no arquivo env.

Fazendo isso com o AgentVera

Este projeto se divide naturalmente em dois trabalhos paralelos: um agente escreve o lado do Telegram, outro o lado do Discord. No AgentVera você pode rodar o Claude Code em um worktree e o Codex em outro, na mesma grade. Depois de cada turno, a revisão de código automática põe um segundo modelo para olhar pontos fáceis de deixar passar, como verificações de autorização. Você revisa as mudanças no painel Git antes do merge e acompanha o uso de tokens dos agentes enquanto constrói a parte de LLM. Na hora do servidor, o SSH e SFTP leva os arquivos, e o gerenciador de Docker mostra os logs do contêiner localmente.

Nada disso é obrigatório; um terminal e o git também levam este bot até o fim. Se você procura algo para o seu bot fazer, os alertas no Telegram em criar um bot de trading de cripto com IA são um bom exemplo.

Conclusão

Criar um bot do Telegram com IA é uma das formas mais divertidas de começar no vibe coding. Pegue o token no fluxo oficial e guarde-o no .env, peça ao agente o bot mais simples primeiro e depois adicione comandos, estado em SQLite e respostas de LLM, camada por camada. Comece com polling, rode em um servidor com systemd ou Docker e mantenha a lógica separada da plataforma para que o Discord seja um passo fácil. Leia você mesmo as verificações de autorização que o agente escreve e os comandos que ele roda; o resto o agente resolve.