Tutorial: criar um bot Telegram e alojá-lo gratuitamente
Criar um bot Telegram com o BotFather, escrever o código mínimo em Python ou em Node.js e alojá-lo gratuitamente 24/7: cada etapa, com os erros mais
Para alojar um bot Telegram gratuitamente, são precisas três coisas: um token dado pelo BotFather, uma dezena de linhas de código em Python ou em Node.js, e uma máquina que fique ligada em vez da sua. Este tutorial segue essas três etapas por ordem, até à primeira resposta do bot ao comando /start. Utiliza o polling: o bot não precisa de endereço público nem de certificado HTTPS.
- O BotFather cria o bot e dá o seu token com o comando /newbot.
- O código lê o token na variável de ambiente TELEGRAM_TOKEN, nunca escrito diretamente num ficheiro.
- Em polling, o bot não precisa de endereço público nem de certificado HTTPS.
- O plano Free da ACLClouds mantém a correr 1 bot Node.js ou Python com 315 MB de RAM, sem cartão bancário.
- Um erro 409 Conflict significa que duas cópias do bot estão a correr com o mesmo token.
Criar o bot com o BotFather
No Telegram, abra uma conversa com @BotFather, a conta oficial que gere os bots, e envie /newbot. Ele pede um nome a apresentar e depois um nome de utilizador que tem de terminar em bot, por exemplo mon_premier_bot. Responde com o token, uma sequência de algarismos e letras separados por dois pontos.
- O token dá o controlo total do bot: não o ponha no código nem numa captura de ecrã.
- Se tiver sido exposto, envie /revoke ao BotFather: o token antigo deixa de funcionar e é criado um novo.
- Num grupo, um bot só recebe por omissão os comandos. Para ler todas as mensagens, desative o modo de privacidade com /setprivacy.
O código mínimo em Python
A biblioteca mais utilizada é a python-telegram-bot. Crie um ficheiro requirements.txt que contenha a linha python-telegram-bot e depois um ficheiro bot.py. O programa lê o token na variável de ambiente TELEGRAM_TOKEN, declara um comando /start e inicia a receção das mensagens.
- Crie a aplicação: Application.builder().token(os.environ["TELEGRAM_TOKEN"]).build().
- Escreva uma função assíncrona start(update, context) que responde com await update.message.reply_text("Olá").
- Ligue-a ao comando com add_handler(CommandHandler("start", start)) e termine com run_polling().
- O pacote a instalar chama-se python-telegram-bot, mas o import escreve-se from telegram.ext import Application, CommandHandler.
O mesmo bot em Node.js
Em Node.js, o Telegraf e o grammY fazem o mesmo trabalho. Com o Telegraf, o package.json contém a dependência telegraf e um script start que executa node index.js. O ficheiro index.js cabe em quatro linhas.
- Carregue a biblioteca: const { Telegraf } = require("telegraf").
- Crie o bot com o token lido no ambiente: const bot = new Telegraf(process.env.TELEGRAM_TOKEN).
- Responda a /start com bot.start((ctx) => ctx.reply("Olá")) e depois execute bot.launch().
Alojar o bot gratuitamente
O plano Free do alojamento de bots da ACLClouds mantém um programa Node.js ou Python a correr em contínuo, sem cartão bancário. É apresentado para Discord, mas um bot Telegram em polling funciona lá da mesma forma: é um programa que abre uma ligação de saída. Na encomenda, escolha Python ou Node.js e substitua o projeto de exemplo pelos seus ficheiros no separador Ficheiros ou por SFTP na porta 2222.
- No separador Arranque, acrescente uma variável de ambiente chamada TELEGRAM_TOKEN com o token do BotFather. O campo «Token do bot Discord» fica vazio.
- Não envie node_modules nem .venv: as dependências são instaladas no servidor a partir de requirements.txt ou de package.json.
- Para enviar os ficheiros com o FileZilla, siga o guia implementar um bot por SFTP.
Iniciar e testar
Inicie o bot a partir da consola, abra a conversa com o seu bot no Telegram e envie /start. A resposta chega num ou dois segundos. Se não chegar nada, a consola mostra a causa: leia a primeira linha de erro.
- 401 Unauthorized: o token está errado ou foi revogado. Copie-o de novo a partir do BotFather.
- 409 Conflict: outra cópia do bot já está a correr com o mesmo token, muitas vezes no seu computador. Pare-a. Se alguma vez foi definido um webhook, apague-o com o método deleteWebhook.
- No module named telegram: a linha python-telegram-bot falta em requirements.txt. Veja o guia ModuleNotFoundError.
- Nenhuma mensagem recebida num grupo: o modo de privacidade está ativo, só chegam os comandos.
O que o plano Free permite
Um bot Telegram de comandos consome pouco: o plano Free chega na maioria dos casos. Os seus limites são públicos, e a contrapartida de ser gratuito é uma renovação a fazer à mão.
- 1 bot por conta, 315 MB de RAM, 0,25 vCPU e 715 MB de armazenamento.
- Renovação gratuita a cada 4 dias a partir da página do bot. Sem renovação, o bot é suspenso.
- O bot não é suspenso entre duas mensagens, e reinicia sozinho depois de uma paragem inesperada.
- Polling ou webhook, ritmo dos envios e memória: o guia bot Telegram 24/7 explica estas escolhas.
Perguntas frequentes
Um bot Telegram pode correr num plano previsto para Discord?
Sim. O plano executa um programa Node.js ou Python: um bot Telegram em polling arranca lá como um bot Discord. Só muda o nome da variável do token.
É preciso um nome de domínio ou um certificado HTTPS?
Não, em polling não: é o bot que interroga o Telegram. Já um webhook exige um endereço HTTPS acessível a partir da Internet.
O bot responde quando o meu computador está desligado?
Sim. É executado na infraestrutura da ACLClouds. Basta renovar o plano Free gratuitamente a cada 4 dias a partir da página do bot.
Que biblioteca escolher para começar?
python-telegram-bot em Python, Telegraf ou grammY em Node.js. As três estão documentadas e chegam para um bot de comandos. Use a linguagem que já conhece.