Como hospedar um bot pyTelegramBotAPI 24/7

Para hospedar um bot pyTelegramBotAPI (telebot) 24/7, rode-o em uma máquina que continue ligada em vez de no seu PC: uma VPS Linux com um serviço systemd que o inicia de novo após uma falha ou reinicialização, ou um plano de bots da PlayNHost (a partir de US$1,99 por mês, veja hospedagem de bots do Telegram), onde você envia seu código, cola o token e clica em Iniciar. Em nosso teste, um bot com pyTelegramBotAPI 4.37.1 usou cerca de 40 MB de memória em repouso; nosso menor plano de bots, o STARTER, tem 0,5 GB. Os dois caminhos usam long polling: bot.infinity_polling() pede ao Telegram as novas mensagens, então o bot não precisa de endereço público. Os passos na PlayNHost:

1. No Telegram, envie /newbot para @BotFather e copie o token que ele der.
2. Em hospedagem de bots do Telegram, clique em Criar servidor em um plano. Na janela do pedido, responda a Para qual plataforma é o seu bot? com Telegram e escolha Python.
3. Abra seu servidor no painel. O cartão Configurar seu bot em Visão geral abre em Conectar ao Telegram; o primeiro passo, O que roda, deve dizer Este bot roda Python Bot.
4. Em Conectar ao Telegram, cole o token e clique em Conectar. Confira o nome do bot exibido e clique em Sim, continuar.
5. Em Seu código, clique em Enviar arquivos para abrir Files e envie bot.py e requirements.txt, ou clique em Conectar o Git. No requirements.txt, o pacote é pyTelegramBotAPI, não telebot.
6. Na página Bot, painel Código, confira se Arquivo de entrada é o arquivo que chama infinity_polling() (bot.py por padrão) e se Runtime é Python 3.11 ou mais recente.
7. Clique em Iniciar bot, abra Console e espere por Logged in as @your_bot. O indicador em Visão geral muda para Online no Telegram. Envie /start ao seu bot.

A primeira inicialização demora mais enquanto o pip instala o pyTelegramBotAPI. Depois disso, ele só instala de novo quando seu arquivo de requisitos, os pacotes extras ou a versão do Python mudam, ou uma vez por dia. Passo a passo com capturas de tela: Como hospedar um bot do Telegram.

O que medimos

Rodamos as três bibliotecas Python do Telegram em um de nossos próprios servidores, em contêineres descartáveis configurados como o painel executa um bot Python: Python 3.12 (o Runtime marcado como recomendado), pacotes instalados com o mesmo comando pip, um limite de memória de 1 GB e um núcleo de CPU.

Cada bot carregou a biblioteca e perguntou ao Telegram quem ele é, com um token falso (pyTelegramBotAPI: bot.get_me() no TeleBot simples). A memória é o que os processos do bot ocupavam 15 segundos depois de o Telegram recusar o token; o tempo de partida vai do início do Python até a biblioteca informar essa resposta, então inclui uma ida e volta ao Telegram. Ambos são a mediana de três execuções após uma execução de aquecimento.

Esses números são o piso da biblioteca: sem chats, sem handlers trabalhando, nada em cache. Seu próprio código, os dados que ele guarda na memória e o número de chats que ele atende vêm por cima, então dimensione o plano pelo que seu bot faz. O tamanho instalado inclui as duas bibliotecas HTTP de que o pyTelegramBotAPI depende, requests e aiohttp, mesmo que você use apenas o TeleBot simples.

Um bot pyTelegramBotAPI mínimo

Ele responde a /start, lê o token que o painel lhe dá e imprime uma linha de pronto. Coloque a biblioteca em requirements.txt:

pyTelegramBotAPI>=4,<5

E o código em bot.py:

import os

import telebot

bot = telebot.TeleBot(os.environ["TELEGRAM_BOT_TOKEN"])


@bot.message_handler(commands=["start"])
def start(message):
    bot.reply_to(message, "Hello! I am running on PlayNHost.")


bot.delete_webhook()
print(f"Logged in as @{bot.user.username}")
bot.infinity_polling()

As duas chamadas antes do polling importam em um host. delete_webhook() remove um webhook deixado por outro host, e bot.user pergunta ao Telegram quem é o bot, então Logged in as @your_bot só aparece com um token que o Telegram aceita. O painel lê essa linha para mostrar Online no Telegram. As duas chamadas também param o bot na hora, com um erro claro, quando o token está errado, em vez de deixar o polling tentar de novo em segundo plano. O painel entrega o token ao seu código como TELEGRAM_BOT_TOKEN, e também como BOT_TOKEN, TOKEN e TELEGRAM_TOKEN.

Se o token estiver errado

Em nosso teste, com um token que o Telegram recusa, nosso bot de teste imprimiu:

ApiTelegramException: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized

Em um traceback completo, a classe aparece como telebot.apihelper.ApiTelegramException. Com o bot acima, a primeira chamada falha e o bot para com código de saída 1; na PlayNHost, o painel mostra O Telegram não aceitou o token do seu bot acima do console, com Substituir o token. Para corrigir, copie o token de novo: no @BotFather, envie /mybots, escolha seu bot e depois API Token. Cole-o na página Bot, painel Telegram, em Token, e inicie o bot de novo.

Um bot que chama infinity_polling() logo de cara, como a maioria dos exemplos, se comporta de outro jeito: ele não para. O polling primeiro pergunta ao Telegram quem é o bot; com um token recusado isso falha, e o bot registra Infinity polling exception: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized e tenta de novo a cada 3 segundos, enquanto o processo estiver rodando. Um token revogado quando o bot já está fazendo polling dá Threaded polling exception: com a mesma mensagem, repetida após uma espera que dobra a cada vez, até um minuto. Nos dois casos o bot parece estar rodando enquanto nada responde. O painel reconhece as duas linhas e mostra o mesmo aviso.

O que um host precisa saber sobre o pyTelegramBotAPI

• Nomes do pacote e do import: você instala pyTelegramBotAPI e importa telebot. O pacote do PyPI chamado telebot é outro projeto, pequeno; coloque pyTelegramBotAPI em requirements.txt.
• Versão do Python: o pyTelegramBotAPI 4.37.1 precisa do Python 3.11 ou mais recente. No Python 3.10, o pip não falha: ele instala a 4.37.0, a última versão que permitia 3.10. Mantenha Runtime no painel Código em 3.11 ou mais recente (3.12 está marcado como recomendado) para obter a versão atual.
• infinity_polling() ou polling(): use infinity_polling(). O polling() simples para no primeiro erro do Telegram, e uma exceção em um dos seus handlers também o encerra, então o bot sai. Com infinity_polling(), os erros do Telegram são repetidos, e qualquer outra exceção em um handler é registrada como Infinity polling exception: ... antes de o polling recomeçar 3 segundos depois.
• Logging: o pyTelegramBotAPI tem seu próprio logger, TeleBot, definido como ERROR, então não imprime nada ao iniciar; por isso o bot acima imprime sua própria linha de pronto. Os erros aparecem em uma linha, sem o traceback. Para ver onde um handler falhou, inicie com bot.infinity_polling(logger_level=logging.DEBUG) (e import logging), que adiciona o traceback. Essas linhas ocultam a parte secreta do seu token.
• Um webhook deixado por outro host: o polling não o remove, e o Telegram recusa o polling enquanto houver um definido. Mantenha bot.delete_webhook() como acima, ou clique em Remover webhook na página Bot, painel Telegram.
• Threads ou asyncio: o TeleBot usa requests e executa os handlers em duas threads de trabalho por padrão (num_threads=2); um handler lento segura uma delas. O AsyncTeleBot de telebot.async_telebot usa aiohttp e roda com asyncio.run(bot.polling()). Os dois rodam do mesmo jeito no painel.
• Uma segunda cópia: quando outra cópia faz polling com o mesmo token, o Telegram responde 409 Conflict e o infinity_polling() tenta de novo enquanto estiver rodando. O painel mostra Seu bot também está rodando em outro lugar. Veja Como corrigir o erro 409 Conflict do bot do Telegram.

Hospede você mesmo em uma VPS Linux

No Debian ou Ubuntu, instale o Python, crie um usuário para o bot e instale a biblioteca em um ambiente virtual. Confira antes python3 --version: abaixo de 3.11, o pip instala um pyTelegramBotAPI mais antigo.

sudo apt update
sudo apt install -y python3 python3-venv
sudo useradd --system --create-home --home-dir /opt/tgbot --shell /usr/sbin/nologin tgbot
sudo cp bot.py requirements.txt /opt/tgbot/
sudo -u tgbot python3 -m venv /opt/tgbot/venv
sudo -u tgbot /opt/tgbot/venv/bin/pip install -r /opt/tgbot/requirements.txt

Coloque o token em um arquivo que só o root possa ler. Abra-o com sudo nano /etc/tgbot.env, escreva uma linha, salve e depois execute sudo chmod 600 /etc/tgbot.env:

TELEGRAM_BOT_TOKEN=123456789:your-token-from-botfather

Crie /etc/systemd/system/tgbot.service:

[Unit]
Description=Telegram bot (pyTelegramBotAPI)
Wants=network-online.target
After=network-online.target

[Service]
User=tgbot
WorkingDirectory=/opt/tgbot
EnvironmentFile=/etc/tgbot.env
Environment=PYTHONUNBUFFERED=1
ExecStart=/opt/tgbot/venv/bin/python /opt/tgbot/bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Inicie-o agora e a cada boot, depois acompanhe a saída:

sudo systemctl daemon-reload
sudo systemctl enable --now tgbot
sudo journalctl -u tgbot -f

PYTHONUNBUFFERED=1 importa aqui: quando a saída do Python não vai para um terminal, ela é armazenada em blocos, então sem isso Logged in as pode ficar em um buffer em vez de chegar ao journal. Restart=always também inicia o bot de novo 5 segundos depois de ele parar por causa de um token errado, então confira o journal se ele ficar reiniciando. Depois de mudar o código, execute sudo systemctl restart tgbot. Pare antes qualquer cópia no seu PC, ou o Telegram responde 409 Conflict.

Hospedagem própria ou plano de bots

• Em uma VPS que você gerencia: atualizações do sistema, a versão do Python, o ambiente virtual, a reinstalação de pacotes, o arquivo de unit, a leitura do journal e perceber quando o bot para de responder. Em troca, você tem root e pode usar um webhook se adicionar um domínio e HTTPS.
• Em um plano de bots, o painel faz isso: instala o requirements.txt quando ele muda, inicia o bot de novo após uma falha, confere o token com o Telegram antes de salvá-lo, entrega-o ao seu código com cinco nomes, lê o console e aponta a causa quando o bot para de responder (um token recusado, uma segunda cópia, um webhook), com um botão para o token e para o webhook. Nossos planos de bots ainda não incluem um endereço HTTPS público, então os bots neles usam long polling, que é o que o infinity_polling() faz.

Perguntas frequentes

Por que meu bot telebot roda, mas nunca responde?

Porque o infinity_polling() tenta de novo cada erro do Telegram sem parar: um token recusado, outra cópia usando o mesmo token, um webhook deixado no bot. Procure linhas com Infinity polling exception (um token recusado na partida) ou Threaded polling exception (quando o polling já está rodando) no Console; o painel transforma cada uma das três causas em um aviso que a nomeia.

Recebo ModuleNotFoundError: No module named 'telebot'. O que está faltando?

O pacote. Adicione pyTelegramBotAPI ao requirements.txt e inicie o bot de novo: o arquivo de requisitos mudou, então o pip o instala nessa inicialização. O import continua sendo import telebot.

O pyTelegramBotAPI precisa de um webhook para ficar online?

Não. O infinity_polling() continua pedindo ao Telegram as novas mensagens, então o bot responde enquanto o processo estiver rodando. Para mudar um bot que usava webhook: Como migrar um bot do Telegram para a PlayNHost.

Devo usar TeleBot ou AsyncTeleBot?

Os dois rodam em um plano de bots. Use o que seu código ou tutorial usa: com TeleBot, os handlers são funções comuns; com AsyncTeleBot, são funções async def que fazem await nos métodos do bot. Nossa medição acima é para o TeleBot simples.

O pyTelegramBotAPI roda em todos os planos de bots da PlayNHost, a partir do STARTER (0,5 GB). Compare os planos e clique em Criar servidor em hospedagem de bots do Telegram.