Como hospedar um bot aiogram 24/7 em um plano de bot ou VPS Linux

Para hospedar um bot aiogram 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 bot 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. No nosso teste, um bot com aiogram 3.31.0 usou cerca de 173 MB de memória em repouso; nosso menor plano de bot, o STARTER, tem 0,5 GB. As duas opções usam long polling: dp.start_polling(bot) pede ao Telegram as novas mensagens, então o bot não precisa de um endereço público. Os passos na PlayNHost:

1. No Telegram, envie /newbot para @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.
6. Na página Bot, painel Código, confira se o Arquivo de entrada é o arquivo que executa asyncio.run(main()) (bot.py por padrão).
7. Clique em Iniciar bot, abra o Console e espere a linha do aiogram Run polling for bot @your_bot. O indicador em Visão geral muda para Online no Telegram. Envie /start ao seu bot.

A primeira inicialização demora mais porque o pip instala o aiogram e suas dependências. 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 dos nossos próprios servidores, em contêineres descartáveis configurados como 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 (aiogram: bot.get_me()). 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 informar essa resposta, então inclui uma ida e volta ao Telegram. Os dois valores 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 mantém na memória (por exemplo, os estados de conversa no armazenamento em memória do aiogram) 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á montado e pronto para iniciar), então os números dela não são comparáveis com estes.

Um bot aiogram mínimo

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

aiogram>=3,<4

E o código em bot.py:

import asyncio
import logging
import os
import sys

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message

dp = Dispatcher()


@dp.message(CommandStart())
async def start(message: Message) -> None:
    await message.answer("Hello! I am running on PlayNHost.")


async def main() -> None:
    bot = Bot(os.environ["BOT_TOKEN"])
    async with bot.context():
        await bot.delete_webhook()
        await dp.start_polling(bot)


if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    asyncio.run(main())

Ele lê BOT_TOKEN, o nome que os próprios exemplos do aiogram usam; o painel entrega o token ao seu código com esse nome, além de TELEGRAM_BOT_TOKEN, TOKEN e TELEGRAM_TOKEN. O log em INFO faz o aiogram imprimir uma linha que começa com INFO:aiogram.dispatcher:Run polling for bot @your_bot quando o Telegram aceita o token, e o painel lê essa linha para mostrar Online no Telegram, então você não precisa de um print próprio. delete_webhook() remove um webhook deixado por outro host antes de o polling começar. async with bot.context() fecha a conexão do bot com o Telegram quando main() termina, inclusive quando termina com erro.

Se o token estiver errado

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

TelegramUnauthorizedError: Telegram server says - Unauthorized

Em um traceback completo, a classe aparece como aiogram.exceptions.TelegramUnauthorizedError. A primeira chamada ao Telegram falha (no bot acima, delete_webhook(); sem ela, o getMe que o start_polling faz), então o bot para na hora 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.

Outros dois casos parecem diferentes. Um token com um espaço, ou sem o número do bot e os dois-pontos antes do segredo, falha antes de qualquer requisição: Bot() verifica o formato e gera TokenValidationError com uma mensagem que começa com Token is invalid!. Um token revogado enquanto o bot já está em polling não o faz parar: o aiogram registra Failed to fetch updates - TelegramUnauthorizedError e tenta de novo a cada poucos segundos, então o processo parece estar rodando enquanto nada responde. O aviso do painel é como você percebe.

O que um host deve saber sobre o aiogram

• Nomes do pacote e da importação: os dois são aiogram. Ele instala junto aiohttp, pydantic, magic-filter, aiofiles e certifi.
• Versão do Python: o aiogram 3.31 precisa do Python 3.10 a 3.14. O Runtime no painel Código oferece exatamente 3.10 a 3.14, com a 3.12 marcada como recomendada.
• O código do aiogram 2 não roda no aiogram 3: o Executor foi removido, então executor.start_polling(dp) vira await dp.start_polling(bot). Um tutorial cujo requirements.txt fixa uma versão 2.x, como aiogram==2.25.2, é código da versão 2; veja a pergunta abaixo.
• Um webhook deixado por outro host: o start_polling não o remove, e o Telegram recusa o polling enquanto houver um configurado, então o aiogram registra TelegramConflictError e tenta de novo. Mantenha await bot.delete_webhook() como acima, ou clique em Remover webhook na página Bot, painel Telegram.
• Log: sem logging.basicConfig, as linhas INFO do aiogram, inclusive a de pronto, não aparecem. Em INFO ele também registra uma linha por update (Update id=... is handled); em um bot movimentado, adicione logging.getLogger("aiogram.event").setLevel(logging.WARNING), que mantém a linha de pronto.
• Quais updates chegam: se você não passar allowed_updates, o start_polling pede ao Telegram apenas os tipos de update para os quais você tem handlers.
• Uma segunda cópia: quando outra cópia faz polling com o mesmo token, o Telegram responde 409 Conflict e o aiogram 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 um VPS Linux

No Debian ou Ubuntu, instale o Python, crie um usuário para o bot e instale o aiogram em um ambiente virtual. Confira se python3 --version mostra 3.10 a 3.14.

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:

BOT_TOKEN=123456789:your-token-from-botfather

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

[Unit]
Description=Telegram bot (aiogram)
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

As linhas de log chegam ao journal assim que acontecem; PYTHONUNBUFFERED=1 faz o mesmo para qualquer print() que você adicionar, que o Python de outro modo segura em um buffer quando não escreve em um terminal. systemctl stop tgbot envia SIGTERM, que o start_polling trata parando o polling e fechando a sessão do bot. 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 bot

• Em um VPS que você administra: atualizações do sistema, a versão do Python, o ambiente virtual, reinstalar pacotes, o arquivo de unit, ler o journal e perceber quando o bot para de responder. Em troca, você tem root e pode usar o modo webhook do aiogram se adicionar um domínio e HTTPS.
• Em um plano de bot, o painel faz isso: instala 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 nomeia 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 bot ainda não incluem um endereço HTTPS público, então os bots lá usam long polling, que é o que o start_polling faz.

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

Perguntas frequentes

Posso rodar um bot aiogram 2?

Migre-o para o aiogram 3 se puder: o guia de migração do aiogram lista as mudanças, começando pelo Executor removido. A última versão do aiogram 2, a 2.25.2, saiu em 6 de outubro de 2023. Ela lista o Python 3.7 a 3.10 como compatível e precisa do aiohttp anterior ao 3.9, que o PyPI oferece como pacotes prontos só até o Python 3.11. Se você precisa do código antigo rodando antes de migrar, fixe aiogram==2.25.2 em requirements.txt e defina o Runtime como Python 3.10, a versão mais nova que ela lista.

Por que meu bot aiogram parece estar rodando, mas nunca responde?

O aiogram continua tentando depois que o polling começou: com um token revogado no @BotFather, com outra cópia usando o mesmo token e com um webhook deixado no bot. Leia as linhas que começam com Failed to fetch updates no Console; o painel transforma cada um dos três casos em um aviso que nomeia a causa, com um botão para o token e o webhook.

Onde ficam os estados FSM do aiogram?

Com o armazenamento em memória padrão, no processo do bot: eles se perdem quando o bot reinicia, por exemplo depois de você mudar o código. Para mantê-los, use um armazenamento fora do processo, como o armazenamento Redis do aiogram com um servidor Redis que você consiga acessar.

Preciso de um webhook para manter um bot aiogram online?

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

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