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

URL: https://agentvera.dev/pt/blog/build-telegram-bot-with-ai/ · Publicado: 2026-10-11

Crie um bot do Telegram com IA: pegue um token, escolha polling ou webhook, guarde estado, adicione respostas de LLM, hospede em um servidor e adapte ao Discord.

**Resumo:**

- Use python-telegram-bot, ou grammY para TypeScript, guarde o token do bot só no .env e comece com polling, que não precisa de endereço HTTPS; webhooks precisam de HTTPS e são a única opção em serverless.
- Guarde o estado em SQLite com verificação de dono, e controle o custo do LLM com um limite diário por usuário, uma lista de IDs permitidos e um histórico curto de mensagens.
- Rode o bot 24/7 em uma VPS com systemd ou Docker; um bot do Discord precisa de uma conexão persistente com o gateway, então mantenha a lógica em um módulo central independente da plataforma.

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](/pt/glossary/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:

```bash
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`:

```bash
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:

```text
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:

```bash
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.

```text
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.

```python
# 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:

```text
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](/pt/glossary/token/) 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

```ini
# /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
```

```bash
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:

```text
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](/pt/features/workspace/) 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](/pt/features/code-review/) 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](/pt/features/git-and-github/) antes do merge e acompanha o [uso de tokens](/pt/features/token-savings/) dos agentes enquanto constrói a parte de LLM. Na hora do servidor, o [SSH e SFTP](/pt/features/ssh-and-sftp/) leva os arquivos, e o [gerenciador de Docker](/pt/features/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](/pt/blog/build-crypto-trading-bot-with-ai/) 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.

## Perguntas frequentes

**Preciso saber programar para criar um bot do Telegram com IA?** Muito pouco. Um agente de código pode escrever o bot inteiro; seu trabalho é dar prompts claros, testar o bot pela sua própria conta e ler os comandos que o agente roda. Uso básico do terminal e saber o que é um arquivo .env bastam.

**Onde consigo o token de um bot do Telegram?** No fluxo oficial de criação de bots do Telegram: você cria um bot novo dentro do Telegram, dá a ele um nome e um username e, no final, recebe um token. Guarde esse token só no seu arquivo .env.

**Um bot do Telegram deve usar polling ou webhook?** Polling é mais simples para desenvolvimento e bots pequenos porque não precisa de um endereço HTTPS público. Webhooks são mais eficientes para bots movimentados e são obrigatórios em plataformas serverless.

**Como adiciono respostas de IA (LLM) a um bot do Telegram?** O bot envia a mensagem recebida para uma API de LLM e devolve a resposta. Guarde a chave da API no .env e use um limite diário por usuário e um histórico curto de conversa para manter os custos sob controle.

**Posso levar o mesmo bot para o Discord?** A maior parte da lógica, sim. Se o tratamento de comandos e mensagens fica em um módulo que não sabe nada da plataforma, o lado do Discord é só uma camada fina escrita com discord.py ou discord.js.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/