Come ospitare un bot pyTelegramBotAPI 24/7

Per ospitare un bot pyTelegramBotAPI (telebot) 24/7, fallo girare su una macchina che resta accesa invece che sul tuo PC: una VPS Linux con un servizio systemd che lo riavvia dopo un crash o un riavvio, oppure un piano bot PlayNHost (da 1,99 US$ al mese, vedi hosting per bot Telegram), dove carichi il codice, incolli il token e premi Avvia. Nel nostro test un bot con pyTelegramBotAPI 4.37.1 ha usato circa 40 MB di memoria a riposo; il nostro piano bot più piccolo, STARTER, ha 0,5 GB. Entrambe le strade usano il long polling: bot.infinity_polling() 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 per bot Telegram, clicca su Crea server su 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 panel. La scheda Configura il tuo bot in Panoramica si apre su Connetti a Telegram; il suo primo passaggio, Cosa viene eseguito, dovrebbe dire Questo bot esegue Python Bot.
4. In Connetti a Telegram, incolla il token e clicca su Connessione. Controlla il nome del bot mostrato e clicca su Sì, continua.
5. In Il tuo codice, clicca su Carica i file per aprire Files e carica bot.py e requirements.txt, oppure clicca su Collega Git. In requirements.txt il pacchetto è pyTelegramBotAPI, non telebot.
6. Nella pagina Bot, riquadro Codice, controlla che File di avvio sia il file che chiama infinity_polling() (bot.py per impostazione predefinita) e che Runtime sia Python 3.11 o più recente.
7. Clicca su Avvia il bot, apri Console e attendi Logged in as @your_bot. L'indicatore in Panoramica passa a Online su Telegram. Invia /start al tuo bot.

Il primo avvio richiede più tempo mentre pip installa pyTelegramBotAPI. 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 fatto girare le tre librerie Python per Telegram su uno dei nostri server, in container usa e getta configurati come il panel 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 falso (pyTelegramBotAPI: bot.get_me() sul TeleBot semplice). 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 riporta quella risposta, quindi include un andata e ritorno verso Telegram. Entrambi sono la mediana di tre esecuzioni dopo una esecuzione di riscaldamento.

Questi valori sono il minimo della libreria: nessuna chat, nessun gestore al lavoro, niente in cache. Il tuo codice, i dati che tiene in memoria e il numero di chat che gestisce si sommano, quindi scegli il piano in base a ciò che fa il tuo bot. La dimensione installata include entrambe le librerie HTTP da cui dipende pyTelegramBotAPI, requests e aiohttp, anche se usi solo il TeleBot semplice.

Un bot pyTelegramBotAPI minimo

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

pyTelegramBotAPI>=4,<5

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

Le due chiamate prima del polling contano su un host. delete_webhook() rimuove un webhook rimasto da un altro host, e bot.user chiede a Telegram chi è il bot, così Logged in as @your_bot compare solo con un token che Telegram accetta. Il panel legge quella riga per mostrare Online su Telegram. Entrambe le chiamate fermano anche subito il bot con un errore chiaro quando il token è sbagliato, invece di lasciare che il polling lo ritenti in background. Il panel passa il token al tuo codice come TELEGRAM_BOT_TOKEN, e anche come BOT_TOKEN, TOKEN e TELEGRAM_TOKEN.

Se il token è sbagliato

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

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

In un traceback completo la classe si legge telebot.apihelper.ApiTelegramException. Con il bot qui sopra, la prima chiamata fallisce e il bot si ferma con codice di uscita 1; su PlayNHost il panel 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 avvia di nuovo il bot.

Un bot che chiama subito infinity_polling(), come fanno la maggior parte degli esempi, si comporta diversamente: non si ferma. Il polling chiede prima a Telegram chi è il bot; con un token rifiutato questo fallisce, e il bot registra Infinity polling exception: A request to the Telegram API was unsuccessful. Error code: 401. Description: Unauthorized e ritenta ogni 3 secondi, finché il processo gira. Un token revocato mentre il bot sta già facendo polling dà invece Threaded polling exception: con lo stesso messaggio, ritentato dopo un'attesa che raddoppia ogni volta, fino a un minuto. In entrambi i casi il bot sembra in funzione mentre nulla risponde. Il panel riconosce entrambe le righe e mostra lo stesso banner.

Cosa deve sapere un host su pyTelegramBotAPI

• Nomi del pacchetto e dell'import: installi pyTelegramBotAPI e importi telebot. Il pacchetto PyPI chiamato telebot è un altro piccolo progetto; metti pyTelegramBotAPI in requirements.txt.
• Versione di Python: pyTelegramBotAPI 4.37.1 richiede Python 3.11 o più recente. Con Python 3.10, pip non fallisce: installa la 4.37.0, l'ultima versione che permetteva 3.10. Tieni Runtime nel riquadro Codice su 3.11 o più recente (3.12 è contrassegnato come consigliato) per ottenere la versione attuale.
• infinity_polling() o polling(): usa infinity_polling(). Il polling() semplice si ferma al primo errore di Telegram, e lo termina anche un'eccezione in uno dei tuoi gestori, quindi il bot esce. Con infinity_polling(), gli errori di Telegram vengono ritentati, e qualsiasi altra eccezione in un gestore viene registrata come Infinity polling exception: ... prima che il polling riparta 3 secondi dopo.
• Logging: pyTelegramBotAPI ha un suo logger, TeleBot, impostato su ERROR, quindi non stampa nulla all'avvio; per questo il bot qui sopra stampa la propria riga di pronto. Gli errori compaiono come una riga senza il traceback. Per vedere dove è fallito un gestore, avvia con bot.infinity_polling(logger_level=logging.DEBUG) (e import logging), che aggiunge il traceback. Queste righe nascondono la parte segreta del token.
• Un webhook rimasto da un altro host: il polling non lo rimuove, e Telegram rifiuta il polling finché ce n'è uno impostato. Mantieni bot.delete_webhook() come sopra, oppure clicca su Rimuovi il webhook nella pagina Bot, riquadro Telegram.
• Thread o asyncio: TeleBot usa requests ed esegue i gestori in due thread di lavoro per impostazione predefinita (num_threads=2); un gestore lento ne occupa uno. AsyncTeleBot da telebot.async_telebot usa aiohttp e si avvia con asyncio.run(bot.polling()). Entrambi girano allo stesso modo sul panel.
• Una seconda copia: quando un'altra copia fa polling con lo stesso token, Telegram risponde 409 Conflict e infinity_polling() ritenta finché gira. Il panel mostra Il tuo bot è in esecuzione anche altrove. Vedi Come risolvere l’errore 409 Conflict di un bot Telegram.

Ospitalo tu su una VPS Linux

Su Debian o Ubuntu, installa Python, crea un utente per il bot e installa la libreria in un ambiente virtuale. Controlla prima python3 --version: sotto la 3.11, pip installa un pyTelegramBotAPI più vecchio.

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 che solo root può leggere. Aprilo con sudo nano /etc/tgbot.env, scrivi una riga, salva, poi esegui sudo chmod 600 /etc/tgbot.env:

TELEGRAM_BOT_TOKEN=123456789:your-token-from-botfather

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

Avvialo ora e a ogni avvio del sistema, poi segui il suo output:

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

PYTHONUNBUFFERED=1 conta qui: quando l'output di Python non va a un terminale viene messo in buffer a blocchi, quindi senza di esso Logged in as può restare in un buffer invece di arrivare al journal. Restart=always riavvia anche il bot 5 secondi dopo che si ferma per un token sbagliato, quindi controlla il journal se continua a riavviarsi. Dopo aver cambiato il codice, esegui sudo systemctl restart tgbot. Ferma prima ogni copia sul tuo PC, o Telegram risponde 409 Conflict.

Self-hosting o piano bot

• Su una 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 accorgersi quando il bot smette di rispondere. In cambio hai root e puoi usare un webhook se aggiungi un dominio e HTTPS.
• Su un piano bot se ne occupa il panel: installa requirements.txt quando cambia, riavvia il bot dopo un crash, controlla il token con Telegram prima di salvarlo, lo passa 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 per 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 infinity_polling().

Domande frequenti

Perché il mio bot telebot gira ma non risponde mai?

Perché infinity_polling() ritenta ogni errore di Telegram senza fermarsi: un token rifiutato, un'altra copia che usa lo stesso token, un webhook rimasto sul bot. Cerca righe con Infinity polling exception (un token rifiutato all'avvio) o Threaded polling exception (quando il polling è già attivo) nella Console; il panel trasforma ciascuna delle tre cause in un banner che la indica.

Ottengo ModuleNotFoundError: No module named 'telebot'. Cosa manca?

Il pacchetto. Aggiungi pyTelegramBotAPI a requirements.txt e avvia di nuovo il bot: il file dei requisiti è cambiato, quindi pip lo installa a quell'avvio. L'import resta import telebot.

pyTelegramBotAPI ha bisogno di un webhook per restare online?

No. infinity_polling() continua a chiedere a Telegram i nuovi messaggi, quindi il bot risponde finché il processo gira. Per spostare un bot che usava un webhook: Come spostare un bot Telegram su PlayNHost.

Devo usare TeleBot o AsyncTeleBot?

Entrambi girano su un piano bot. Usa quello che usano il tuo codice o il tuo tutorial: con TeleBot i gestori sono funzioni normali, con AsyncTeleBot sono funzioni async def che fanno await sui metodi del bot. La nostra misura qui sopra è per il TeleBot semplice.

pyTelegramBotAPI gira su ogni piano bot PlayNHost, da STARTER (0,5 GB) in su. Confronta i piani e clicca su Crea server su hosting per bot Telegram.