Como criar um bot de Telegram com Claude Code ou Codex (guia para iniciantes)

Nunca programou um bot, mas quer automatizar mensagens no Telegram? Claude Code, Codex ou outros assistentes de programação com IA podem fazer a maior parte do trabalho técnico por você, desde que sejam bem orientados. Em poucos passos, passamos de uma ideia a um bot que funciona de verdade. Veja como fazer.

1. Crie o seu bot no Telegram

Abra o Telegram e converse com o @BotFather, o bot oficial que cria bots. Digite /newbot, escolha um nome e um identificador (que deve terminar com “bot”). O BotFather dá-lhe um token : uma longa sequência de caracteres que serve como chave secreta para controlar o seu bot. Guarde-o com cuidado, nunca o partilhe publicamente — e se por acaso ele vazar (publicado por engano no GitHub, por exemplo), volte a falar com o BotFather para o revogar e gerar um novo.

2. Abra o seu assistente de IA numa pasta de projeto

Crie uma pasta vazia no seu computador e depois inicie o assistente num terminal nesse local. Ele trabalha sempre na pasta atual: é aí que vai ler e escrever os seus ficheiros.

3. Dê-lhe um prompt inicial preciso

Não precisa de vocabulário técnico, mas quanto mais precisa for a sua solicitação, melhor será o resultado. Aqui está um prompt que pode copiar e colar tal como está (substituindo os valores entre parênteses retos):

Cria um bot de Telegram em Python com a biblioteca python-telegram-bot.
O bot deve enviar todas as manhãs a previsão do tempo de [CIDADE] às [HORA].

Restrições:
- Guarda o token do Telegram num ficheiro .env, nunca diretamente no código.
- Cria um ficheiro .gitignore que exclua o .env.
- Não inventes nenhum valor secreto (token, chave API): indica-me claramente
  onde e como os preencher eu mesmo.
- Explica-me cada passo antes de o executar.
- Testa o bot antes de considerares o projeto terminado.

Para uma mensagem enviada todos os dias sem que tenha de escrever ao bot, também é preciso saber o seu chat ID (identificador da sua conversa com o bot). Basta pedir à IA para lhe explicar como obtê-lo — geralmente enviando uma primeira mensagem ao bot e depois lendo a resposta da API do Telegram.

4. Proteja o token desde o início

A IA deve criar um ficheiro .env para guardar o token.

5. Deixe a IA executar os comandos, com prudência

A IA pode lançar ela mesma os comandos de instalação (pip install, npm install, etc.) e iniciar o bot para o testar. Ela vai pedir a sua autorização antes de cada ação importante. Isso é normal, é uma segurança. Quando alguém que está a começar não tem referências para julgar “o que faz sentido”, basta uma regra simples: se um comando pede a sua palavra-passe, altera ficheiros que não reconhece, ou instala um software de que nunca ouviu falar, peça primeiro à IA para lhe explicar o que vai fazer e porquê, antes de aceitar.

6. Teste o seu bot

Depois de o bot iniciado, abra o Telegram e envie-lhe uma mensagem. Se ele não responder como esperado, descreva simplesmente o problema à IA (“o bot não responde a /start” ou “tenho um erro XYZ”): ele lerá as mensagens de erro e corrigirá o código.

7. Adicione funcionalidades aos poucos

Assim que a base estiver funcional, enriqueça-a bot progressivamente: respostas automáticas, lembretes agendados, integração com uma API externa… Peça uma funcionalidade de cada vez, teste, depois passe para a seguinte. Se o seu bot tiver de memorizar utilizadores, as suas preferências ou lembretes, peça à IA para prever um armazenamento persistente: um simples ficheiro local pode ser suficiente para um protótipo, mas não sobreviverá sempre a um reinício num alojamento, tornando-se então necessária uma pequena base de dados.

8. Aloje o seu bot continuamente

Para que o bot funcione mesmo quando o seu computador está desligado, é preciso alojá-lo num servidor. Peça à IA para lhe explicar as opções atuais (pequeno servidor cloud, plataformas como Railway ou Fly.io, funções serverless como Cloudflare Workers) e para preparar a implementação. Verifique sempre as condições e tarifas em vigor no momento em que ler isto: as ofertas gratuitas destas plataformas evoluem regularmente.

9. Resolva problemas e faça a manutenção do seu bot

Um bot que funciona hoje pode deixar de funcionar amanhã: dependência atualizada, alojador que muda as regras, token expirado… Guarde um registo do que a IA implementou (peça-lhe para documentar claude.md) para poder dar-lhe o contexto facilmente. Em caso de avaria, basta copiar e colar a mensagem de erro à IA: muitas vezes é suficiente para que ela identifique e corrija o problema.

Responder, programar ou difundir: três lógicas diferentes

Um bot Telegram pode fazer três coisas bem distintas: responder a uma mensagem recebida, enviar uma mensagem programada a uma hora fixa, ou difundir uma notificação a vários utilizadores. Este último caso é mais exigente: é preciso gerir a lista de pessoas que iniciaram uma conversa com o bot, as suas preferências, e respeitar os limites de envio impostos pelo Telegram. Um bot não pode escrever espontaneamente para qualquer conta Telegram; cada utilizador deve primeiro ter iniciado a conversa.

O que é gratuito, o que é pago

Criar um bot com BotFather é gratuito, e a API Bot Telegram geralmente não é cobrada por chamada, mas o Telegram impõe limites de débito, e certas funcionalidades podem ter as suas próprias condições. Do lado do assistente IA, o uso depende do seu plano: uma subscrição tipo Claude Pro ou Max ou ChatGPT Pro inclui a utilização da ferramenta.

Do lado do alojamento, várias plataformas (Cloudflare Workers, Railway, Fly.io…) propõem geralmente um nível gratuito adequado a um pequeno bot pessoal de baixo tráfego. Mas estas ofertas evoluem regularmente e variam conforme o uso real do seu bot : verifique sempre as condições atuais antes de se comprometer. Em resumo: é perfeitamente possível pôr um primeiro bot Telegram a funcionar sem gastar um cêntimo.

Algumas ideias de bots Telegram

Acompanhamento de preços & compras

• Alerta de descida de preço: monitoriza um produto e avisa assim que este desce abaixo de um limite definido.
• Comparador de preços de combustível: alerta quando um posto próximo desce abaixo de um determinado preço por litro.
• Acompanhamento de disponibilidade: avisa assim que um artigo esgotado volta a estar disponível.

Finanças & mercados

• Cotação de ações / cripto: envia o preço do Bitcoin, de uma ação ou de um ETF, ou alerta em caso de variação acentuada.
• Acompanhamento de carteira: calcula diariamente o valor total dos teus investimentos.
• Taxa de câmbio: alerta quando um par de moedas atinge um limiar interessante.

Meteorologia & ambiente

• Meteorologia diária para a tua cidade, enviada todas as manhãs.
• Alerta meteorológico em caso de trovoada, chuva forte ou geada prevista.
• Qualidade do ar / pólen.

Produtividade & vida pessoal

• Bot pessoal de tarefas: adicionar, eliminar e lembrar tarefas diretamente no Telegram.
• Bot de monitorização RSS: acompanha vários sites e envia apenas os novos artigos.
• Bot de resumo: envia um artigo ou um texto ao bot e recebe um resumo.
• Bot de notificações para o teu próprio site: nova encomenda, novo formulário, erro no servidor.
• Bot de acompanhamento de domótica: alerta quando um aparelho ou sensor muda de estado.
• Bot de diário pessoal: regista rapidamente notas e encontra-as por pesquisa.
• Acompanhamento de encomendas: centraliza o estado das tuas entregas num único bot.

A reter

Não precisas de saber programar para criar um bot Telegram funcional. O papel da IA é traduzir as tuas ideias em código, executar os comandos técnicos e corrigir os erros. O teu papel é descrever claramente o que o bot deve fazer, proteger os teus acessos, fazer perguntas, perguntar à IA se tem dúvidas e testar o resultado. É um verdadeiro trabalho de equipa entre a tua visão e a execução técnica da IA.