Come ospitare un bot aiogram 24/7 con un piano bot o un VPS Linux

Per ospitare un bot aiogram 24/7, eseguilo su una macchina che resta accesa invece che sul tuo PC: un VPS Linux con un servizio systemd che lo riavvia dopo un crash o un riavvio, oppure un piano bot PlayNHost (da US$1,99 al mese, vedi hosting di bot Telegram), dove carichi il codice, incolli il token e premi Avvia. Nel nostro test un bot con aiogram 3.31.0 ha usato circa 173 MB di memoria a riposo; il nostro piano bot più piccolo, STARTER, ha 0,5 GB. Entrambe le strade usano il long polling: dp.start_polling(bot) chiede a Telegram i nuovi messaggi, quindi il bot non ha bisogno di un indirizzo pubblico. I passaggi su PlayNHost:

1. In Telegram, invia /newbot a @BotFather e copia il token che ti dà.
2. Su hosting di bot Telegram, fai clic su Crea server per un piano. Nella finestra dell’ordine, rispondi a Per quale piattaforma è il tuo bot? con Telegram e scegli Python.
3. Apri il tuo server nel pannello. La scheda Configura il tuo bot in Panoramica si apre su Connetti a Telegram; il suo primo passaggio, Cosa viene eseguito, dovrebbe indicare Questo bot esegue Python Bot.
4. In Connetti a Telegram, incolla il token e fai clic su Connessione. Controlla il nome del bot mostrato e fai clic su Sì, continua.
5. In Il tuo codice, fai clic su Carica i file per aprire Files e carica bot.py e requirements.txt, oppure fai clic su Collega Git.
6. Nella pagina Bot, riquadro Codice, controlla che il File di avvio sia il file che esegue asyncio.run(main()) (bot.py per impostazione predefinita).
7. Fai clic su Avvia il bot, apri la Console e aspetta la riga di aiogram Run polling for bot @your_bot. L’indicatore in Panoramica passa a Online su Telegram. Invia /start al tuo bot.

Il primo avvio richiede più tempo perché pip installa aiogram e le sue dipendenze. Dopo, reinstalla solo quando cambiano il file dei requisiti, i pacchetti extra o la versione di Python, oppure una volta al giorno. Passo dopo passo con screenshot: Come ospitare un bot Telegram.

Cosa abbiamo misurato

Abbiamo eseguito le tre librerie Python per Telegram su uno dei nostri server, in container usa e getta configurati come il pannello esegue un bot Python: Python 3.12 (il Runtime contrassegnato come consigliato), pacchetti installati con lo stesso comando pip, un limite di memoria di 1 GB e un core di CPU.

Ogni bot ha caricato la libreria e ha chiesto a Telegram chi è, con un token finto (aiogram: bot.get_me()). La memoria è quella occupata dai processi del bot 15 secondi dopo che Telegram ha rifiutato il token; il tempo di avvio va dal lancio di Python fino a quando la libreria segnala quella risposta, quindi comprende un andata e ritorno verso Telegram. Entrambi sono la mediana di tre esecuzioni dopo una di riscaldamento.

Questi valori sono il minimo della libreria: nessuna chat, nessun handler al lavoro, niente in cache. Il tuo codice, i dati che tiene in memoria (per esempio gli stati di conversazione nello storage in memoria di aiogram) e il numero di chat che gestisce si aggiungono, quindi dimensiona il piano in base a ciò che fa il tuo bot. La nostra pagina precedente python-telegram-bot vs aiogram su PlayNHost ha misurato una configurazione diversa (Python 3.13, un bot già costruito e pronto a partire), quindi i suoi numeri non sono confrontabili con questi.

Un bot aiogram minimo

Risponde a /start, legge il token che gli dà il pannello e scrive nel log una riga di pronto. Metti la libreria in requirements.txt:

aiogram>=3,<4

E il codice in 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())

Legge BOT_TOKEN, il nome usato dagli esempi di aiogram stesso; il pannello dà il token al tuo codice con questo nome e anche come TELEGRAM_BOT_TOKEN, TOKEN e TELEGRAM_TOKEN. Il logging a livello INFO fa stampare ad aiogram una riga che inizia con INFO:aiogram.dispatcher:Run polling for bot @your_bot quando Telegram ha accettato il token, e il pannello legge quella riga per mostrare Online su Telegram, quindi non ti serve un print tuo. delete_webhook() rimuove un webhook rimasto da un altro host prima che inizi il polling. async with bot.context() chiude la connessione del bot a Telegram quando main() termina, anche se termina con un errore.

Se il token è sbagliato

Nel nostro test, con un token che Telegram rifiuta, il bot di prova ha stampato:

TelegramUnauthorizedError: Telegram server says - Unauthorized

In un traceback completo la classe appare come aiogram.exceptions.TelegramUnauthorizedError. La prima chiamata a Telegram fallisce (nel bot qui sopra, delete_webhook(); senza di essa, il getMe che fa start_polling), quindi il bot si ferma subito con codice di uscita 1. Su PlayNHost il pannello mostra Telegram non ha accettato il token del bot sopra la console, con Sostituisci il token.

Per risolvere, copia di nuovo il token: in @BotFather invia /mybots, scegli il tuo bot, poi API Token. Incollalo nella pagina Bot, riquadro Telegram, sotto Token, e riavvia il bot.

Altri due casi si presentano diversamente. Un token con uno spazio, o senza il numero del bot e i due punti prima del segreto, fallisce prima di qualsiasi richiesta: Bot() controlla la forma e solleva TokenValidationError con un messaggio che inizia con Token is invalid!. Un token revocato mentre il bot sta già facendo polling non lo ferma: aiogram scrive Failed to fetch updates - TelegramUnauthorizedError e riprova ogni pochi secondi, quindi il processo sembra in esecuzione mentre nulla risponde. Te ne accorgi dal banner del pannello.

Cosa deve sapere un host su aiogram

• Nomi del pacchetto e dell’import: entrambi sono aiogram. Installa insieme a sé aiohttp, pydantic, magic-filter, aiofiles e certifi.
• Versione di Python: aiogram 3.31 richiede Python da 3.10 a 3.14. Il Runtime nel riquadro Codice offre esattamente da 3.10 a 3.14, con 3.12 indicato come consigliato.
• Il codice aiogram 2 non funziona su aiogram 3: l’Executor è stato rimosso, quindi executor.start_polling(dp) diventa await dp.start_polling(bot). Un tutorial il cui requirements.txt fissa una versione 2.x, come aiogram==2.25.2, è codice della versione 2; vedi la domanda più sotto.
• Un webhook rimasto da un altro host: start_polling non lo rimuove, e Telegram rifiuta il polling finché ne è impostato uno, quindi aiogram scrive TelegramConflictError e riprova. Mantieni await bot.delete_webhook() come sopra, oppure fai clic su Rimuovi il webhook nella pagina Bot, riquadro Telegram.
• Logging: senza logging.basicConfig le righe INFO di aiogram, compresa quella di pronto, non vengono mostrate. A livello INFO scrive anche una riga per ogni update (Update id=... is handled); su un bot molto usato aggiungi logging.getLogger("aiogram.event").setLevel(logging.WARNING), che mantiene la riga di pronto.
• Quali update arrivano: se non passi allowed_updates, start_polling chiede a Telegram solo i tipi di update per cui hai degli handler.
• Una seconda copia: quando un’altra copia fa polling con lo stesso token, Telegram risponde 409 Conflict e aiogram riprova finché resta in esecuzione. Il pannello mostra Il tuo bot è in esecuzione anche altrove. Vedi Come risolvere l’errore 409 Conflict di un bot Telegram.

Ospitarlo da solo su un VPS Linux

Su Debian o Ubuntu, installa Python, crea un utente per il bot e installa aiogram in un ambiente virtuale. Controlla che python3 --version indichi da 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

Metti il token in un file leggibile solo da root. Aprilo con sudo nano /etc/tgbot.env, scrivi una riga, salva, poi esegui sudo chmod 600 /etc/tgbot.env:

BOT_TOKEN=123456789:your-token-from-botfather

Crea /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

Avvialo subito e a ogni boot, poi segui il suo output:

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

Le righe di logging arrivano nel journal man mano che avvengono; PYTHONUNBUFFERED=1 fa lo stesso per ogni print() che aggiungi, che altrimenti Python trattiene in un buffer quando non scrive su un terminale. systemctl stop tgbot invia SIGTERM, che start_polling gestisce fermando il polling e chiudendo la sessione del bot. Dopo aver cambiato il codice, esegui sudo systemctl restart tgbot. Ferma prima ogni copia sul tuo PC, altrimenti Telegram risponde 409 Conflict.

Self-hosting o piano bot

• Su un VPS che gestisci tu: gli aggiornamenti di sistema, la versione di Python, l’ambiente virtuale, la reinstallazione dei pacchetti, il file di unità, la lettura del journal e accorgerti quando il bot smette di rispondere. In cambio hai root e puoi usare la modalità webhook di aiogram se aggiungi un dominio e HTTPS.
• Su un piano bot lo fa il pannello: installa requirements.txt quando cambia, riavvia il bot dopo un crash, verifica il token con Telegram prima di salvarlo, lo dà al tuo codice con cinque nomi, legge la console e indica la causa quando il bot smette di rispondere (un token rifiutato, una seconda copia, un webhook), con un pulsante per il token e il webhook. I nostri piani bot non includono ancora un indirizzo HTTPS pubblico, quindi lì i bot usano il long polling, che è ciò che fa start_polling.

Vedi anche Come usare un database MySQL con un bot aiogram (aiomysql).

Domande frequenti

Posso eseguire un bot aiogram 2?

Portalo su aiogram 3 se puoi: la guida alla migrazione di aiogram elenca le modifiche, a partire dall’Executor rimosso. L’ultima versione di aiogram 2, la 2.25.2, è uscita il 6 ottobre 2023. Indica come supportati Python da 3.7 a 3.10 e richiede aiohttp precedente alla 3.9, che PyPI offre come pacchetti già compilati solo fino a Python 3.11. Se ti serve il vecchio codice funzionante prima di portarlo, fissa aiogram==2.25.2 in requirements.txt e imposta il Runtime su Python 3.10, la versione più recente che indica.

Perché il mio bot aiogram sembra in esecuzione ma non risponde mai?

aiogram continua a riprovare una volta avviato il polling: con un token revocato in @BotFather, con un’altra copia che usa lo stesso token e con un webhook rimasto sul bot. Leggi le righe che iniziano con Failed to fetch updates nella Console; il pannello trasforma ciascuno dei tre casi in un banner che indica la causa, con un pulsante per il token e il webhook.

Dove vivono gli stati FSM di aiogram?

Con lo storage in memoria predefinito, nel processo del bot: si perdono quando il bot si riavvia, per esempio dopo aver cambiato il codice. Per conservarli, usa uno storage esterno al processo, come lo storage Redis di aiogram con un server Redis raggiungibile.

Mi serve un webhook per tenere online un bot aiogram?

No. start_polling continua a chiedere a Telegram i nuovi messaggi, quindi il bot risponde finché il processo è in esecuzione. Per spostare un bot che usava un webhook: Come spostare un bot Telegram su PlayNHost.

aiogram funziona su ogni piano bot PlayNHost, da STARTER (0,5 GB) in su. Confronta i piani e fai clic su Crea server in hosting di bot Telegram.