Como hospedar um bot python-telegram-bot 24/7

Para hospedar um bot python-telegram-bot 24/7, rode-o em uma máquina que fica sempre ligada, em vez de no seu PC: um 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), em que você envia seu código, cola o token e clica em Start. No nosso teste, um bot python-telegram-bot 22.8 usou cerca de 44 MB de memória em repouso; nosso menor plano de bots, STARTER, tem 0,5 GB. Os dois caminhos usam long polling: run_polling() pergunta ao Telegram por novas mensagens, então o bot não precisa de um endereço público. Os passos na PlayNHost:

1. No Telegram, envie /newbot ao @BotFather e copie o token que ele der a você.
2. Em hospedagem de bots do Telegram, clique em Criar servidor em um plano. Na janela do pedido, responda 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. Ainda sem código? Criar um bot inicial escreve um bot python-telegram-bot 22 para você.
6. Na página Bot, painel Código, confira se Arquivo de entrada é o arquivo que chama run_polling() (bot.py por padrão).
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 python-telegram-bot. Depois disso, ele só instala de novo quando o 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 de Telegram para Python em um dos nossos próprios servidores, em contêineres descartáveis configurados do jeito que o painel roda 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 (python-telegram-bot: Application.initialize()). A memória é o que os processos do bot ocupavam 15 segundos depois de o Telegram recusar o token; o tempo de inicialização vai do lançamento do Python até a biblioteca relatar 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. Nossa página mais antiga python-telegram-bot vs aiogram na PlayNHost mediu uma configuração diferente (Python 3.13, um bot já construído e pronto para iniciar), então seus números não são comparáveis com estes.

Um bot mínimo com python-telegram-bot

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

python-telegram-bot>=22,<23

E o código em bot.py:

import os

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    await update.effective_message.reply_text("Hello! I am running on PlayNHost.")


async def post_init(application: Application) -> None:
    print(f"Logged in as @{application.bot.username}")


def main() -> None:
    application = (
        Application.builder()
        .token(os.environ["TELEGRAM_BOT_TOKEN"])
        .post_init(post_init)
        .build()
    )
    application.add_handler(CommandHandler("start", start))
    application.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()

post_init roda depois que a aplicação é inicializada, que é quando o python-telegram-bot verifica o token com o Telegram, então Logged in as @your_bot só aparece depois que o Telegram o aceitou. O painel lê essa linha para mostrar Online no Telegram. O painel entrega o token ao seu código como TELEGRAM_BOT_TOKEN, e também como BOT_TOKEN, TOKEN e TELEGRAM_TOKEN, então os.environ["TOKEN"] também funciona se você partir dos exemplos da biblioteca, que usam um espaço reservado "TOKEN".

Se o token estiver errado

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

InvalidToken: The token `1000000000:AAFakeTokenForAMemoryTestNotReal00000` was rejected by the server.

O python-telegram-bot verifica o token antes de o polling começar, então o bot acima para na hora com código de saída 1. O console mostra primeiro Network Retry Loop (Bootstrap Initialize Application): Invalid token. Aborting retry loop. com um traceback, depois o traceback do próprio erro, cuja última linha diz telegram.error.InvalidToken: The token `...` was rejected by the server. Na PlayNHost, o painel mostra O Telegram não aceitou o token do seu bot acima do console, com Substituir o token. Note que os dois tracebacks contêm o próprio token: não cole essa saída do console em nenhum lugar público.

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. Se o token for revogado enquanto o bot já está fazendo polling, o python-telegram-bot registra Network Retry Loop (Polling Updates): Invalid token. Aborting retry loop. e para o polling, mas o processo continua rodando, então o bot parece funcionar enquanto nada responde. O painel mostra o mesmo aviso.

O que um host deve saber sobre o python-telegram-bot

• Nomes do pacote e da importação: você instala python-telegram-bot e importa telegram e telegram.ext.
• Versão do Python: o python-telegram-bot 22.8 exige Python 3.10 ou mais recente. O Runtime no painel Código oferece de 3.10 a 3.14, com 3.12 marcado como recomendado, então qualquer escolha atende.
• Um webhook deixado por outro host: antes de começar o polling, run_polling() apaga qualquer webhook definido no bot, então um bot vindo de um host com webhook funciona sem código extra. As mensagens que aguardam no Telegram são mantidas, a menos que você passe drop_pending_updates=True.
• Logging: o python-telegram-bot registra sua inicialização no nível INFO, que o Python não mostra até você configurar o logging, então o bot acima imprime sua própria linha de pronto. Com logging.basicConfig(level=logging.INFO) ele registra INFO:telegram.ext.Application:Application started, que o painel também lê como pronto. Se fizer isso, adicione também logging.getLogger("httpx").setLevel(logging.WARNING), como os próprios exemplos da biblioteca: no nível INFO, a biblioteca HTTP registra cada URL de requisição, e as URLs de requisição do Telegram contêm o seu token.
• Tarefas agendadas: a JobQueue precisa de um extra. Escreva python-telegram-bot[job-queue]>=22,<23 em requirements.txt; sem ele, application.job_queue é None e a biblioteca avisa No `JobQueue` set up.
• Uma segunda cópia: quando outra cópia faz polling com o mesmo token, o Telegram responde 409 Conflict. O python-telegram-bot registra Exception happened while polling for updates. e continua tentando, então o bot parece rodar, mas perde mensagens. 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 um 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 se python3 --version mostra 3.10 ou mais recente.

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 consiga 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 (python-telegram-bot)
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, e 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 parado em um buffer em vez de chegar ao journal. systemctl stop tgbot envia SIGTERM, que run_polling() trata encerrando de forma limpa. 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 um VPS que você gerencia: as atualizações do sistema, a versão do Python, o ambiente virtual, a reinstalação de pacotes, o arquivo de unidade, a leitura do journal e perceber quando o bot para de responder. Em troca, você tem root e pode rodar um webhook se adicionar um domínio e HTTPS.
• Em um plano de bots, o painel faz: instala requirements.txt quando ele muda, inicia o bot de novo após uma falha, verifica o token com o Telegram antes de salvá-lo, entrega-o ao seu código com cinco nomes, lê o console e indica 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 o webhook. Nossos planos de bots ainda não incluem um endereço HTTPS público, então os bots ali usam long polling, que é o que run_polling() faz.

Veja também Como usar um banco de dados MySQL com um bot python-telegram-bot (aiomysql).

Perguntas frequentes

Preciso de um webhook para manter um bot python-telegram-bot online?

Não. run_polling() mantém uma conexão aberta com o Telegram e pergunta por novas mensagens, então o bot responde enquanto o processo estiver rodando. Um webhook precisa de um endereço HTTPS público, que nossos planos de bots ainda não incluem. Para mover um bot que usava um: Como migrar um bot do Telegram para a PlayNHost.

Por que meu token apareceu no console?

Ele aparece em dois lugares comuns: a mensagem InvalidToken quando o Telegram recusa o token, e as linhas de requisição da biblioteca HTTP quando o logging está em INFO. Defina o logger httpx como WARNING, como mostrado acima. Nosso bot inicial também captura InvalidToken e imprime uma linha simples no lugar.

Posso usar run_repeating e outras tarefas agendadas?

Sim, com o extra job-queue em requirements.txt. O extra instala o APScheduler na próxima inicialização, porque o arquivo de requisitos mudou. As tarefas rodam dentro do processo do bot, então continuam rodando enquanto o bot roda.

O bot inicial usa python-telegram-bot?

Sim. Em um servidor Python, Criar um bot inicial escreve bot.py e um requirements.txt com python-telegram-bot 22. Ele responde a /start, imprime Logged in as @your_bot e mantém o token fora das suas linhas de log. Altere como quiser e depois reinicie.

O python-telegram-bot 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.