> Manutenzione di un bot Telegram: cosa si rompe più spesso (e come prevenirlo)

Chi gestisce un bot Telegram sa che il primo mese è tranquillo. Poi arrivano i guai. Non sono errori di design – sono le frizioni quotidiane che nessuno ti spiega quando guardi il primo tutorial.

# Le quattro cause più comuni di rottura

Se il tuo bot smette di funzionare, la colpa è quasi sempre una di queste quattro cose. Non ho statistiche precise, ma chi lavora con bot Telegram si scontra costantemente con questi problemi in produzione.

1. La connessione HTTP si blocca

Se usi il metodo webhook (cioè comunichi a Telegram l'indirizzo dove ricevere gli update), il timeout della connessione è il nemico silenzioso. Il tuo server risponde lentamente – magari per un database overloaded, magari per una API esterna che fa cilecca – e Telegram rinuncia.

Telegram aspetta una risposta HTTP 200 entro un tempo limitato. Se non arriva, l'update va perso. Il bot continua a girare, ma smette di ricevere messaggi da quel momento in poi.

Come prevenirlo: le risposte ai webhook devono essere veloci. Se il tuo bot chiama un database o un'API esterna, fai il lavoro in background (con una coda, tipo Celery o RabbitMQ) e rispondi subito a Telegram con 200 OK. Imposta anche un timeout ragionevole – di solito 10-15 secondi.

2. I token scadono o vengono revocati

Raramente il token del bot scade per decadimento naturale – ma accade spesso che BotFather (il manager dei bot su Telegram) lo rivochi se Telegram rileva un comportamento sospetto, o se abiliti accidentalmente qualche opzione nei settaggi del bot che non è compatibile con quello che il bot fa davvero.

Più frequente: il token viene messo pubblicamente su GitHub, lo raccolgono bot scanner, e qualcuno lo usa per fare spam. Telegram lo disabilita.

Come prevenirlo: tieni il token in una variabile d'ambiente, mai in git. Se il token viene usato illegittimamente, rigeneralo da BotFather. Prima di metterlo in produzione, cambialo una volta – è una piccola frizione, ma gratis e salva vite.

3. L'API di Telegram cambia

Succede raramente, ma Telegram aggiorna le sue API. Un parametro che era opzionale diventa obbligatorio, oppure una risposta cambia struttura. Se il tuo bot è scritto male (senza error handling su quello che riceve da Telegram), si rompe silenziosamente.

Esempio reale: Telegram ha aggiunto il campo is_premium ai messaggi di utenti premium. Se il parser del tuo bot fa un accesso diretto a un indice invece di usare un .get(), il tutto crasha se quel campo manca da un update più vecchio.

Come prevenirlo: non fidarti della struttura dati che Telegram ti manda. Usa parsing difensivo: .get() per accedere ai campi, sempre. Scrivi test che simulano risposte malformate. Monitora gli errori in produzione – se i log cominciano a riempirsi di KeyError, significa che la struttura è cambiata.

4. Il polling si inceppa

Se usi il metodo polling (cioè il bot chiede continuamente a Telegram "ho nuovi messaggi?"), il processo di polling può incepparsi. Un errore di rete non gestito, oppure una eccezione in mezzo al loop che non viene catturata, e il bot smette di fare polling. Il processo continua a girare, ma non riceve più messaggi.

Come prevenirlo: il loop di polling deve avere una struttura robusta. Cattura eccezioni di rete, implementa exponential backoff (se la connessione fallisce, aspetta un po' prima di riprovare), e registra sempre gli errori. Se il polling si ferma, devi saparlo dal log.

# Monitoraggio: come accorgersi che il bot è morto

Se nessuno se ne accorge perché il bot non risponde, è come se non fosse mai morto – solo che l'azienda perde soldi.

Implementa almeno questi controlli:

• Health check periodico: ogni minuto (o ogni 5 minuti, dipende da quanto è critico), il bot invia un messaggio a un chat di test con te. Se il messaggio non arriva, qualcosa è rotto.
• Log centralizzato: non leggere i log dal server direttamente. Usa uno strumento come ELK, Loki, o anche solo CloudWatch. Se il bot crasha, il file di log sul server potrebbe essere irraggiungibile.
• Alert su errori: se il bot registra un KeyError, una timeout exception, o qualunque cosa che non dovrebbe accadere, ricevi un alert Slack/email. Non aspettare che qualcuno se ne accorga per caso.

Problema	Sintomo	Come vederlo
Webhook timeout	Bot smette di ricevere update dopo poco	Log della API; Telegram non registra consegna
Token revocato	Errore 401 Unauthorized su ogni richiesta	Leggi il log; prova a mandare un messaggio di test
API Telegram cambiata	Errori sporadici su particolari utenti/messaggi	Exception logging; monitora eccezioni su parse
Polling bloccato	Processo in memoria ma niente messaggi ricevuti	Health check; monitora il timestamp dell'ultimo update

# Struttura di un bot robusto

Non devo reinventare la ruota: le librerie mature come python-telegram-bot o aiogram gestiscono già molti di questi casi. Ma devi comunque sapere cosa controllare:

1. Usa la libreria ufficiale più mantenuta nel linguaggio che scegli.
2. Configura timeout decenti (30 secondi per le richieste lunghe, 5-10 per le normali).
3. Implementa retry con exponential backoff per errori transitori.
4. Tutti gli handler devono catturare le eccezioni e loggare, non crashare silenziosamente.
5. Metti il token in una variabile d'ambiente, mai in codice.
6. Testa il parsing con dati malformati.
7. Monitora il bot da fuori – health check, log centralizzato, alert.

# Quando questo approccio è sufficiente (e quando non lo è)

Questo vale per bot a medio-basso volume: decine o centinaia di utenti, niente esigenze di disponibilità 99.9%. Se il bot va giù per un'ora qualche volta all'anno, è un fastidio, non una catastrofe.

Se invece il bot è mission-critical – usato da migliaia di persone ogni giorno, con SLA – allora devi aggiungere uno strato di ridondanza: load balancer davanti a più istanze del bot, database replicato, e veri monitoring (Prometheus, Datadog). Ma è un altro livello di complessità.