ACLClouds
ACLClouds

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.