Come funziona la creazione di un bot Telegram tramite BotFather?
Scopri come creare un bot Telegram con BotFather: registrazione, token, comandi e configurazione, con percorsi per mobile e desktop e best practice.

BotFather: che cosa è e quale problema risolve
La creazione di un bot Telegram tramite BotFather è il punto di partenza obbligato per chiunque voglia mettere in piedi un'automazione, un servizio di notifica o un'interfaccia conversazionale dentro Telegram. BotFather è un bot ufficiale messo a disposizione dalla piattaforma e si comporta come un pannello di controllo testuale: non esistono schermate grafiche dedicate alla gestione dei bot, ma solo una conversazione con un account speciale a cui si inviano comandi in slash. Comprendere questo dettaglio cambia l'approccio, perché non si «compila un form», si dialoga con un bot che risponde con testi, pulsanti inline e istruzioni passo passo. La conseguenza pratica è che ogni operazione — creare, rinominare, revocare un token — passa da un messaggio di testo, e la cronologia della chat diventa di fatto il registro delle modifiche apportate.
Il problema concreto che BotFather risolve è la registrazione di un'identità automatizzata all'interno dell'ecosistema Telegram. Un bot non è un account umano: non ha un numero di telefono, non ha una rubrica, non riceve chiamate. È un'entità distinta che possiede un username, un profilo pubblico, una serie di metadati e — soprattutto — una chiave di autenticazione chiamata token, che consente al tuo codice di parlare con i server della piattaforma a nome del bot. Senza passare da BotFather non esiste un modo legittimo di ottenere quel token, e questo lo rende l'unico punto di ingresso controllato all'intero ciclo di vita del bot.
Vale la pena chiarire subito il confine rispetto ad altre funzionalità che a volte vengono confuse con i bot. Un canale serve a distribuire contenuti a un pubblico, ma non risponde ai messaggi. Un gruppo è una conversazione tra persone, eventualmente con un bot aggiunto come membro. Una Mini App è un'applicazione web che si apre dentro Telegram e che, per esistere, ha comunque bisogno di un bot come contenitore. In altre parole, BotFather è il livello di registrazione; tutto il resto è ciò che si costruisce sopra, e confondere i due livelli porta a scegliere lo strumento sbagliato per il proprio caso d'uso.
Suggerimento: se stai valutando se il tuo caso d'uso richieda davvero un bot, chiediti se serve una risposta automatica a un input dell'utente. Se la risposta è no e ti basta pubblicare, probabilmente ti serve un canale, non un bot.
Prerequisiti, account e limiti pratici
Prima di aprire la chat con BotFather serve un account Telegram attivo, con un numero di telefono verificato. Non esistono prerequisiti di programmazione per la fase di registrazione: chiunque può creare un bot e ottenere un token in pochi minuti. La programmazione diventa necessaria nel momento in cui si vuole che il bot faccia qualcosa di diverso dal restare inerte, perché ogni comportamento osservabile richiede un processo in ascolto e una risposta inviata tramite API.
Un secondo prerequisito, spesso trascurato, è la disponibilità di un ambiente in cui conservare il token. Il token è un segreto: chi lo possiede può inviare messaggi a nome del bot, leggerne gli aggiornamenti e, in alcuni casi, modificare la configurazione tramite l'API. Conservarlo in un file di testo sul desktop o incollarlo in un repository pubblico sono due errori classici che portano, prima o poi, alla necessità di revocarlo. Vale quindi la pena decidere in anticipo dove vivrà il segreto, prima ancora di creare il bot.
Requisiti minimi su mobile e desktop
Sul piano tecnico, la creazione del bot richiede soltanto un client Telegram funzionante e una connessione di rete. I client ufficiali per Android, iOS, Windows, macOS e Linux espongono tutti la stessa chat con BotFather, perché si tratta di una conversazione come le altre. La versione web consente di fare la stessa cosa dal browser, con la limitazione che alcune operazioni avanzate — per esempio la gestione dei pagamenti — risultano più comode su un client desktop, dove si copiano e incollano testi lunghi con maggiore facilità.
Non esiste una versione minima universalmente valida da citare come soglia, perché i client si aggiornano in modo indipendente e silenzioso. Come regola pratica: se la chat con BotFather risponde correttamente ai comandi, il client è adeguato. Se alcuni comandi restituiscono errori o non producono risposta, il primo passo è aggiornare il client all'ultima versione disponibile nello store e riprovare.
Che cosa BotFather non fa
Chiarire i confini evita frustrazioni successive. BotFather non scrive codice al posto tuo, non ospita il tuo backend e non esegue logica di business. Non è un server: è un'interfaccia di registrazione e configurazione. Non gestisce nemmeno l'analisi delle conversazioni dei tuoi utenti, salvo le statistiche aggregate che Telegram mette a disposizione per i bot con determinate caratteristiche.
BotFather non crea automaticamente un database, non invia notifiche push al di fuori di Telegram e non aggira i limiti di invio imposti dalla piattaforma. Se il tuo piano prevede di inviare messaggi a decine di migliaia di destinatari, sappi che quella parte del lavoro si scontra con i limiti di frequenza pubblicati nella documentazione ufficiale, non con una decisione di BotFather. Riconoscere questa separazione di responsabilità aiuta a cercare la causa dei problemi nel posto giusto: nel proprio codice e nella propria infrastruttura, non nella chat di gestione.
Percorso operativo: creare il primo bot passo passo
Il flusso di creazione è breve e sostanzialmente identico su tutte le piattaforme. Quello che cambia è il percorso più corto per raggiungere la chat, non la sequenza dei comandi. Vediamo prima il percorso generale, poi le differenze di piattaforma.
- Apri Telegram e cerca @BotFather nel campo di ricerca globale. In alternativa, apri direttamente il link
t.me/BotFather. - Verifica il segno di spunta di verifica accanto al nome: esistono account che imitano BotFather, e un token inviato al bot sbagliato è un token compromesso.
- Apri la chat e premi Avvia (o invia
/start). BotFather risponde con l'elenco dei comandi disponibili. - Invia
/newbot. BotFather chiede un nome visualizzato, cioè il nome che gli utenti vedranno nel profilo. - Invia il nome visualizzato. Puoi cambiarlo in seguito, quindi non bloccarti sulla scelta.
- BotFather chiede uno username. Deve essere unico a livello globale e deve terminare con il suffisso
bot. Se è già occupato, il bot te lo segnala e ti invita a riprovare. - Al termine, BotFather restituisce un messaggio con il link al bot e il token di accesso.
Il passo critico è il sesto. Il vincolo sul suffisso bot non è una convenzione stilistica ma un requisito tecnico della piattaforma: serve a rendere immediatamente riconoscibile un account automatizzato rispetto a un account umano. Alcuni username possono risultare non disponibili anche per motivi diversi dall'occupazione, per esempio se contengono sequenze riservate o se violano le linee guida sui nomi.
Attenzione: il token viene mostrato una volta nel messaggio di conferma. Copialo subito in un gestore di password o in una variabile d'ambiente. Se lo perdi, non è un problema grave — puoi recuperarlo con /token — ma se lo esponi accidentalmente devi revocarlo immediatamente.
Percorso su Android e iOS
Su Android, il percorso più breve consiste nell'aprire l'app, toccare l'icona di ricerca in alto e digitare BotFather. Il risultato corretto è un contatto con nome «BotFather», username @BotFather e badge di verifica. Su iOS la sequenza è analoga: scheda Chat, barra di ricerca in alto, digitazione di BotFather, quindi apertura del contatto verificato.
Su entrambe le piattaforme mobile, il comando /newbot si invia come qualsiasi altro messaggio. La tastiera suggerisce i comandi disponibili non appena si digita la barra, il che riduce gli errori di battitura. La copia del token avviene con una pressione prolungata sul messaggio: su Android si seleziona il testo e si sceglie Copia, su iOS si tocca Copia nel menu contestuale. Su mobile la tastiera può interferire con la selezione di stringhe lunghe; se il token è particolarmente lungo, valutare di completare l'operazione su desktop.
Percorso su Desktop e Web
Su Telegram Desktop, la ricerca si trova in alto a sinistra nella barra laterale. Digitando BotFather compare il contatto verificato; in alternativa si può aprire il link t.me/BotFather direttamente dal browser, che avvia il client desktop se installato. Il vantaggio pratico del desktop è la gestione degli appunti: si copia il token con un clic, lo si incolla in un file di configurazione o in un gestore di segreti e non si perde il contesto della chat.
La versione Web di Telegram, accessibile dal browser, offre le stesse funzionalità di base per la creazione del bot. Tuttavia, per operazioni che richiedono più passaggi consecutivi — impostare un elenco di comandi formattato, caricare un'immagine di profilo, configurare un dominio per il Login Widget — il client desktop resta più comodo, perché consente di tenere aperte più finestre e di copiare testi strutturati senza perdere la chat.
Rami di fallimento e piani di riserva
Non tutte le creazioni vanno a buon fine al primo tentativo. Il caso più frequente è l'username già occupato: BotFather risponde indicando che il nome è preso e chiede di sceglierne un altro. Non c'è nulla da fare se non provare una variante, per esempio aggiungendo un prefisso legato al progetto o un separatore. Un secondo caso è l'uso di caratteri non ammessi: gli username Telegram sono composti da lettere, cifre e underscore, con lunghezza limitata.
Un terzo scenario, meno frequente ma possibile, è l'assenza di risposta da parte di BotFather. In quel caso il problema è quasi sempre di rete o di sincronizzazione del client. Le verifiche utili, in ordine: controllare la connessione con un altro bot, riavviare il client, verificare che il messaggio sia stato effettivamente consegnato (la spunta singola indica invio, la doppia indica consegna), riprovare dopo qualche minuto. Se il problema persiste su tutti i client, può trattarsi di un disservizio temporaneo lato piattaforma: in quel caso l'unica azione sensata è attendere e riprovare.
Il token: dove si trova, come si protegge, quando revocarlo
Il token è la credenziale che identifica il bot presso l'API. La sua forma tipica è una stringa che inizia con una sequenza numerica, seguita da due punti e da una parte alfanumerica. Questa struttura non è casuale: la parte numerica identifica il bot, quella successiva è il segreto vero e proprio. Non è necessario memorizzarla a mano, ma riconoscerne la forma aiuta a individuarla se compare accidentalmente in un log o in uno screenshot.
Per recuperare il token in un secondo momento esistono due strade. La prima è il comando /token, che BotFather accetta nella chat principale ma che, per motivi di sicurezza, nella maggior parte dei casi richiede di selezionare prima il bot interessato. La seconda è il menu /mybots: si sceglie il bot dall'elenco e si apre la voce relativa alle credenziali. Entrambe le strade presuppongono che tu sia autenticato con l'account che ha creato il bot.
La revoca è l'operazione da eseguire quando il token è stato esposto. Il comando /revoke, disponibile nel menu di gestione del bot, invalida il token corrente e ne genera uno nuovo. Da quel momento tutte le chiamate effettuate con il vecchio token restituiscono un errore di autorizzazione, mentre il bot continua a esistere con la stessa identità, lo stesso username e gli stessi utenti. Questo è un punto importante: la revoca non cancella il bot, protegge soltanto l'accesso, e proprio per questo è un'operazione rapida da eseguire e priva di effetti collaterali sull'utenza.
Buona pratica: tratta il token come una password. Inseriscilo in variabili d'ambiente o in un gestore di segreti, non nel codice sorgente, non nei commenti, non nei messaggi di commit. Se il progetto è su un repository pubblico, aggiungi il file di configurazione al file di esclusione prima del primo commit.
Configurare l'identità del bot: nome, descrizione, immagine
Un bot appena creato è funzionalmente vuoto: ha un nome e uno username, ma il profilo appare scarno. La configurazione dell'identità si fa sempre tramite BotFather, con una serie di comandi che agiscono su metadati diversi. Distinguere questi metadati è utile perché vengono mostrati in contesti diversi dell'interfaccia.
| Comando | Metadato | Dove appare |
|---|---|---|
/setname | Nome visualizzato | Intestazione della chat, elenco chat |
/setdescription | Descrizione lunga | Schermata iniziale prima di avviare il bot |
/setabouttext | Testo «Informazioni» | Pagina del profilo |
/setuserpic | Immagine del profilo | Avatar nelle chat e nei risultati di ricerca |
La distinzione tra descrizione e testo «Informazioni» genera spesso confusione. La descrizione è ciò che un utente nuovo legge prima di premere il pulsante di avvio: è il tuo spazio per spiegare cosa fa il bot e a cosa serve. Il testo «Informazioni» è ciò che l'utente trova nel profilo dopo aver avviato la conversazione: è più adatto a contenere informazioni di servizio, come il riferimento a un sito o a un canale di supporto. Scriverli con contenuti identici è uno spreco di spazio informativo.
Per l'immagine di profilo, BotFather accetta il caricamento di un file immagine dalla chat. La pratica comune è usare un'immagine quadrata, leggibile anche in formato ridotto, perché l'avatar viene mostrato in dimensioni molto piccole nell'elenco delle chat. Non esistono qui formati «giusti» universali: conta la leggibilità a dimensione ridotta. Un'osservazione empirica ricorrente è che i loghi con testo esteso diventano illeggibili nell'elenco chat, mentre le icone semplici restano riconoscibili.
Impostare i comandi con /setcommands
L'elenco dei comandi è una delle configurazioni con il rapporto valore/sforzo più favorevole. Quando è impostato, l'utente che digita la barra nella chat vede un menu con i comandi disponibili e la relativa descrizione; senza di esso, l'utente deve indovinare quali comandi esistono. Il comando /setcommands accetta un elenco in cui ogni riga ha la forma comando - descrizione.
start - Avvia il bot e mostra il menu principale help - Elenco dei comandi disponibili orari - Orari di apertura del servizio
Tre aspetti meritano attenzione. Primo: i comandi devono corrispondere a ciò che il tuo backend gestisce realmente. Un menu che elenca comandi non implementati è peggio di un menu assente, perché genera aspettative che si traducono in messaggi senza risposta. Secondo: la descrizione deve stare in poche parole, perché lo spazio nell'interfaccia è limitato e il testo in eccesso viene troncato. Terzo: se il bot parla più lingue, l'elenco dei comandi ammette varianti per lingua, così che l'utente veda le descrizioni nella lingua del proprio client.
Quando non usare questa funzione: se il bot ha un solo comando evidente e non ha senso esporre un menu, l'elenco aggiunge rumore. Allo stesso modo, se i comandi cambiano frequentemente in base allo stato della conversazione, un elenco statico rischia di diventare fuorviante. In quel caso è più onesto non pubblicare alcun menu e guidare l'utente con messaggi e pulsanti contestuali.
Impostazioni avanzate: inline, gruppi, privacy, geolocalizzazione
Oltre all'identità, BotFather espone una serie di interruttori che cambiano il comportamento del bot. Sono tutti opzionali e tutti reversibili, ma ciascuno ha implicazioni pratiche che vale la pena comprendere prima di attivarli.
Modalità inline
Con la modalità inline attiva, l'utente può richiamare il bot digitandone lo username seguito da una query in qualsiasi chat, anche in conversazioni con altre persone, e inserire il risultato come messaggio. Il comando di riferimento è /setinline. Questo apre scenari interessanti — ricerca di contenuti, generazione di citazioni, conversione di unità — ma comporta anche una riflessione sulla privacy: i risultati inline vengono prodotti in risposta a una query che il bot riceve, quindi il bot vede ciò che l'utente sta digitando in quel contesto.
Il confine d'uso è chiaro: attiva la modalità inline se il valore del bot sta nel produrre un contenuto a partire da un input testuale breve. Non attivarla se il bot gestisce dati sensibili legati all'utente, perché il contesto inline è per definizione «senza conversazione».
Aggiunta ai gruppi e modalità privacy
Il comando /setjoingroups stabilisce se il bot può essere aggiunto a gruppi e supergruppi. Il comando /setprivacy governa invece un aspetto più sottile: la modalità privacy, quando è attiva, fa sì che il bot riceva soltanto i messaggi che lo menzionano esplicitamente, i comandi indirizzati a lui e le risposte ai suoi messaggi. Quando è disattivata, il bot riceve tutti i messaggi del gruppo.
Questa è una delle decisioni progettuali più rilevanti per un bot destinato ai gruppi. Un bot di moderazione ha bisogno di vedere tutto il flusso e quindi richiede la modalità privacy disattivata; un bot di servizio che risponde solo su comando non ne ha bisogno e, lasciando la modalità privacy attiva, riduce drasticamente la quantità di dati che transita nel proprio backend. Dal punto di vista della conformità, quest'ultima è quasi sempre la scelta preferibile: meno dati ricevuti significa meno dati da conservare, proteggere e cancellare su richiesta.
Va ricordato che esistono casi in cui un bot, pur con modalità privacy attiva, vede comunque i messaggi: per esempio quando è amministratore del gruppo, o quando la modalità privacy è stata disattivata prima che il bot entrasse nel gruppo. Se il comportamento osservato non corrisponde all'impostazione attesa, la verifica da fare è rimuovere e riaggiungere il bot al gruppo dopo aver modificato l'impostazione.
Geolocalizzazione inline
Il comando /setinlinegeo consente di richiedere la posizione dell'utente per i risultati inline. È una funzione che ha senso per bot di tipo geografico — ricerca di punti di interesse, meteo locale, servizi nelle vicinanze — e che va evitata in tutti gli altri casi. La richiesta di posizione è un attrito per l'utente e, se non strettamente necessaria, riduce l'utilizzo del bot.
Dall'API al primo messaggio: polling e webhook
A questo punto il bot esiste e ha un'identità, ma non fa nulla. Per renderlo operativo serve collegare il token a del codice. L'API Bot di Telegram è raggiungibile via HTTPS e segue uno schema prevedibile: l'URL di base contiene il token, il metodo identifica l'operazione, i parametri viaggiano come query string o come JSON.
curl -s "https://api.telegram.org/bot/getMe"
La chiamata getMe è il test di sanità da eseguire subito dopo aver ottenuto il token: restituisce l'identità del bot e conferma che la credenziale è valida. Se la risposta contiene un errore di autorizzazione, il problema è nel token; se la richiesta non arriva, il problema è di rete o di DNS.
Per ricevere gli aggiornamenti esistono due modelli. Il primo è il polling: il tuo programma chiama periodicamente getUpdates e ottiene i messaggi accumulati dall'ultima chiamata. Il secondo è il webhook: dichiari a Telegram un URL HTTPS e la piattaforma invia a quell'URL ogni aggiornamento non appena si verifica. Il comando per configurare il webhook è setWebhook, mentre getWebhookInfo permette di verificarne lo stato.
| Criterio | Polling | Webhook |
|---|---|---|
| Complessità iniziale | Bassa | Media: serve un endpoint raggiungibile |
| Latenza percepita | Dipende dall'intervallo di interrogazione | Generalmente più contenuta |
| Requisiti infrastrutturali | Funziona anche da rete domestica | Richiede certificato valido e porta raggiungibile |
| Adatto a | Prototipi, sviluppo locale, volumi contenuti | Produzione, volumi elevati |
Una nota pratica importante: i due modelli sono mutuamente esclusivi. Se un webhook è configurato, le chiamate a getUpdates restituiscono un conflitto. È l'errore più frequente per chi sviluppa in locale e pubblica in produzione: si dimentica un webhook attivo e ci si chiede perché il codice locale non riceva nulla. La verifica è immediata con getWebhookInfo.
Prestazioni e costi: cosa misurare davvero
Quando si parla di prestazioni di un bot Telegram, il collo di bottiglia raramente è BotFather o l'API di piattaforma. Le variabili che contano sono tre: i limiti di frequenza imposti dalla piattaforma, la latenza del tuo backend e il modo in cui gestisci le code di invio. Affrontarli separatamente aiuta a capire dove intervenire.
Limiti di frequenza e pianificazione degli invii
La documentazione ufficiale dell'API descrive limiti di frequenza differenziati a seconda del destinatario: sono più permissivi verso le chat private e più restrittivi verso gruppi e canali, dove un singolo invio raggiunge molte persone. I valori esatti cambiano nel tempo e vanno verificati nella documentazione corrente al momento dell'implementazione.
Dal punto di vista progettuale, questo significa che un bot di notifica a larga scala non può limitarsi a ciclare su una lista di destinatari e inviare in sequenza senza controllo. Serve una coda con limitazione di velocità, che distribuisca gli invii nel tempo e gestisca in modo esplicito la risposta di errore che indica di aver superato la soglia. Un caso tipico: un servizio con un canale da alcune decine di migliaia di iscritti e un volume di pubblicazioni giornaliere nell'ordine delle centinaia. In questa configurazione, la differenza tra un sistema che ignora i limiti e uno che li rispetta non è la velocità di punta, ma la stabilità nel tempo: il primo produce errori intermittenti e messaggi persi, il secondo una distribuzione prevedibile.
Latenza del backend e timeout
Se si usa un webhook, il tempo di risposta del tuo endpoint diventa parte dell'esperienza utente. Endpoint che impiegano troppo a rispondere possono portare a ritentativi da parte della piattaforma, con il rischio di elaborare due volte lo stesso aggiornamento. La contromisura standard è rendere l'endpoint il più rapido possibile: accodare l'aggiornamento e rispondere subito, elaborando il contenuto in un processo separato. È un pattern banale ma spesso trascurato nei prototipi.
Un secondo aspetto è la gestione dei duplicati. Se il tuo codice non è idempotente — cioè se elaborare due volte lo stesso aggiornamento produce due effetti distinti, per esempio due messaggi inviati all'utente — i ritentativi si trasformano in spam percepito. La verifica riproducibile è semplice: registra l'identificatore univoco di ogni aggiornamento elaborato e controlla se ne arriva uno già visto. Se il numero di duplicati rilevati è diverso da zero, il sistema va reso idempotente.
Costi: cosa è a carico tuo e cosa no
La creazione e la gestione di un bot tramite BotFather non comportano costi diretti verso la piattaforma. I costi emergono dal lato infrastruttura: l'hosting del backend, il database, la banda e — se il webhook è esposto su internet — la gestione di certificati e protezione dagli abusi. Va inoltre considerata la voce di costo meno visibile: il tempo di sviluppo e manutenzione. Le funzionalità che richiedono integrazione con servizi esterni, come i pagamenti, aggiungono complessità di conformità che va valutata prima di iniziare.
Quando non vale la pena: se il tuo fabbisogno è una notifica occasionale a poche decine di persone, un bot con polling su una macchina di piccole dimensioni è più che sufficiente e l'adozione di un'architettura distribuita aggiunge solo complessità. La soglia oltre la quale conviene investire in code, monitoraggio e idempotenza dipende dal volume e dalla criticità del messaggio: se un messaggio perso non ha conseguenze, la tolleranza all'errore può essere alta; se il messaggio è un avviso transazionale, la tolleranza deve essere bassa.
Integrazione con servizi di terze parti e minimo privilegio
Molti bot esistono per collegare Telegram a qualcos'altro: un gestionale, un calendario, un sistema di ticketing, un archivio documentale. In questi scenari il principio guida è il minimo privilegio: concedere al bot solo i permessi strettamente necessari per la funzione richiesta, e nient'altro.
Applicato alla pratica, il principio si traduce in alcune decisioni concrete. Se il bot deve leggere i messaggi di un gruppo solo per rispondere a comandi, la modalità privacy resta attiva. Se il bot deve inviare messaggi a un canale, gli si concede il ruolo di amministratore di quel canale e niente più. Se il bot deve accedere a un servizio esterno, si crea un'utenza dedicata con permessi limitati, invece di riutilizzare le credenziali di un amministratore umano.
Un esempio ricorrente riguarda l'integrazione con servizi di archiviazione di terze parti: un bot di terze parti che salva i file inviati dagli utenti richiede tipicamente l'accesso ai messaggi e ai documenti. Prima di autorizzarlo, la domanda da porsi è se esista una modalità di funzionamento che richieda meno permessi — per esempio un comando esplicito che l'utente invoca per salvare un singolo file, invece di un accesso continuo a tutto ciò che passa nella chat. La risposta non è quasi mai ovvia, ma la domanda è sempre legittima.
Nota sulla conformità: un bot che riceve messaggi da utenti europei ricade, a seconda del caso, negli obblighi di protezione dei dati applicabili. La scelta architetturale di ricevere meno dati è anche la scelta che semplifica gli adempimenti successivi. Vale la pena documentare per iscritto quali dati il bot riceve, dove li conserva e per quanto tempo.
Mini App, pagamenti e Login Widget: confini operativi
BotFather ospita anche la configurazione di funzionalità che estendono il bot oltre la chat. Sono opzioni potenti ma con prerequisiti tecnici e di conformità che vanno conosciuti prima di imboccarle.
Le Mini App sono applicazioni web che si aprono all'interno di Telegram, avviate da un bot. La gestione avviene tramite BotFather, che mette a disposizione comandi per registrare l'applicazione e associarla al bot; nella documentazione ufficiale l'insieme di questi comandi è descritto con nomi che possono variare nel tempo, quindi conviene consultare la sezione dedicata della documentazione corrente invece di affidarsi alla memoria. Il punto pratico è che una Mini App richiede comunque un'applicazione web funzionante e ospitata: BotFather non genera il contenuto, registra soltanto il collegamento.
I pagamenti richiedono un passaggio ulteriore: la piattaforma prevede che il bot sia collegato a un provider di pagamento abilitato, e la configurazione avviene attraverso il menu di gestione del bot in BotFather, dove si seleziona il provider e si completano i dati richiesti. Non è una funzione che si attiva con un singolo comando, e non tutte le configurazioni commerciali sono disponibili in tutte le aree geografiche. Se il tuo progetto prevede transazioni, verifica la disponibilità per il tuo paese e per il tipo di attività prima di promettere la funzionalità agli utenti.
Il Login Widget, infine, consente di usare Telegram come metodo di autenticazione su un sito esterno. Anche in questo caso serve un passaggio in BotFather per associare il dominio autorizzato, perché la piattaforma deve sapere quali siti possono richiedere l'autenticazione a nome di quel bot. La verifica riproducibile consiste nell'aprire il widget su un dominio associato e su uno non associato: il primo deve funzionare, il secondo deve essere rifiutato.
Il confine da tenere presente è che nessuna di queste tre funzionalità è «gratuita» in termini di complessità. Ognuna aggiunge superficie di attacco, obblighi di sicurezza e dipendenze esterne. La domanda da porsi non è «posso farlo», ma «il valore aggiunto giustifica la manutenzione».
Risoluzione problemi: sintomo, causa, verifica, soluzione
Gli inconvenienti più comuni nella gestione di un bot si riconoscono da pochi sintomi ricorrenti. La tabella seguente organizza i casi più frequenti in modo da poter procedere per esclusione, senza tentativi casuali.
Il bot non risponde ai messaggi
Sintomo: l'utente scrive e non riceve nulla. Cause possibili, in ordine di probabilità: nessun processo in ascolto sul backend; token non valido o revocato; webhook configurato verso un URL non più attivo; errore nel codice che interrompe l'elaborazione prima dell'invio. Verifica: chiamare getMe per confermare la validità del token, poi getWebhookInfo per vedere se esiste un webhook e quale sia il suo stato. Se il webhook risulta attivo ma l'endpoint non è raggiungibile, la piattaforma lo segnala nella risposta. Soluzione: correggere l'endpoint oppure rimuovere il webhook e passare temporaneamente al polling per isolare il problema.
Il bot non riceve i messaggi nel gruppo
Sintomo: in chat privata il bot funziona, nel gruppo sembra sordo. La causa più comune è la modalità privacy attiva: il bot riceve solo i messaggi che lo menzionano o i comandi. Verifica: inviare un comando esplicito e controllare se il bot risponde; poi inviare un messaggio normale senza menzione e verificare che non risponda. Se il comportamento è questo, la modalità privacy è attiva. Soluzione: se serve che il bot veda tutti i messaggi, modificare l'impostazione e poi rimuovere e riaggiungere il bot al gruppo, perché la modifica non sempre ha effetto retroattivo sull'appartenenza in corso.
Conflitto tra polling e webhook
Sintomo: il codice locale che funzionava smette di ricevere aggiornamenti, oppure restituisce un errore che segnala un webhook già attivo. Causa: un webhook è configurato per quel bot, quindi getUpdates viene rifiutato. Verifica: getWebhookInfo. Soluzione: se stai sviluppando in locale, rimuovi il webhook con setWebhook senza parametri di URL; quando torni in produzione, riconfiguralo. Tenere due bot distinti, uno per lo sviluppo e uno per la produzione, elimina il problema alla radice ed è la pratica consigliata su progetti non banali.
Il token è stato esposto
Sintomo: il token è finito in un repository pubblico, in uno screenshot o in un log condiviso. Causa: gestione non sicura del segreto. Verifica: cercare la stringa del token nei repository e nei file di log accessibili; controllare se il bot ha inviato messaggi non previsti verso chat sconosciute. Soluzione: revocare immediatamente il token dal menu di gestione del bot, aggiornare le variabili d'ambiente con il nuovo valore e riavviare i processi. La revoca è istantanea e non richiede di ricreare il bot.
Differenze di versione e raccomandazioni di migrazione
Uno degli equivoci più comuni è credere che BotFather abbia versioni numerate come un'applicazione desktop. BotFather è un servizio lato piattaforma: cambia quando cambia Telegram, senza che l'utente debba installare nulla. Ciò che si aggiorna sui dispositivi è il client, non il bot di gestione.
Questa distinzione ha conseguenze pratiche. Se un comando di BotFather non è disponibile, la causa più probabile è che il client sia datato e non mostri correttamente la risposta, oppure che il comando non sia previsto per quel tipo di bot. Se invece un comando che usavi prima non funziona più, la causa può essere un cambiamento nell'interfaccia di gestione. In entrambi i casi, il riferimento da consultare è la documentazione ufficiale aggiornata, non un articolo scritto mesi prima.
Sul fronte della migrazione, la raccomandazione generale è non costruire dipendenze da dettagli dell'interfaccia di BotFather. I comandi stabili nel tempo sono quelli storici e documentati: creazione, elenco, token, revoca, impostazione di nome, descrizione, immagine, comandi, inline, privacy, gruppi. Se il tuo processo operativo si appoggia a questi, è improbabile che debba essere riscritto. Se invece si appoggia a menu e percorsi visivi specifici, ogni riorganizzazione dell'interfaccia diventa un problema. La contromisura è documentare internamente i comandi usati, con la data dell'ultima verifica, così che un futuro cambiamento sia facile da individuare.
Metodo di verifica: una volta ogni tanto, apri la chat con BotFather, esegui la sequenza dei comandi che usi abitualmente e annota se tutti rispondono come previsto. Bastano pochi minuti e ti evita di scoprire un cambiamento nel momento peggiore, cioè durante un'emergenza.
Metodi di verifica e osservazione riproducibili
Un articolo tecnico è utile solo se le sue indicazioni sono verificabili. Questa sezione raccoglie controlli concreti, ordinati dal più semplice al più strutturato, che puoi eseguire senza strumenti particolari.
Il primo controllo è l'identità del bot. Interroga l'API con getMe e confronta lo username restituito con quello che hai scelto. Se non coincidono, stai usando il token di un altro bot: capita più spesso di quanto si pensi quando si gestiscono più progetti nello stesso file di configurazione.
Il secondo controllo riguarda la ricezione degli aggiornamenti. Invia un messaggio al bot dalla tua chat, poi interroga lo stato del webhook. Se stai usando il polling, controlla che il payload degli aggiornamenti contenga il messaggio appena inviato e che l'identificatore dell'aggiornamento sia superiore a quello precedente. Questo conferma che il canale di ricezione è integro e che non stai rileggendo aggiornamenti vecchi.
Il terzo controllo riguarda l'invio. Invia un messaggio di prova verso una chat di tua proprietà e osserva la risposta dell'API. Una risposta di successo contiene l'identificativo del messaggio creato; una risposta di errore contiene un codice e una descrizione. Annota i codici che incontri: la loro frequenza nel tempo è un indicatore più utile di qualsiasi metrica di vanità, perché dice quante volte il tuo sistema ha provato a fare qualcosa che la piattaforma ha rifiutato.
Il quarto controllo riguarda la configurazione della privacy nei gruppi. Crea un gruppo di prova, aggiungi il bot, invia un messaggio che non lo menziona, poi invia un comando. Registra il comportamento osservato. Ripeti dopo aver modificato l'impostazione e aver riaggiunto il bot. Questo esperimento richiede pochi minuti e chiarisce in modo definitivo un aspetto che altrimenti resta ambiguo.
Un'osservazione empirica ricorrente è che la maggior parte dei problemi segnalati come «il bot non funziona» si risolve in uno di questi quattro controlli. Vale la pena trasformarli in una checklist eseguita prima di ogni rilascio, invece di affrontarli come diagnostica di emergenza.
Checklist: quando usare BotFather e quando no
Non ogni esigenza di comunicazione richiede un bot. Questa sezione definisce criteri di ammissione e di esclusione, per evitare di costruire automazioni là dove bastava un canale o un gruppo.
| Scenario | Un bot è adatto? | Alternativa |
|---|---|---|
| Notifiche transazionali a singoli utenti | Sì | — |
| Pubblicazione di contenuti a un vasto pubblico | Spesso no | Canale |
| Moderazione di una community | Sì, con privacy disattivata | Moderazione manuale |
| Interfaccia verso un servizio interno | Sì | — |
| Pagina informativa statica | No | Canale o sito |
I criteri di ammissione sono tre. Primo, esiste un input dell'utente a cui il sistema deve reagire in modo automatico. Secondo, esiste un canale di distribuzione individuale, cioè il messaggio va a una persona specifica e non a un pubblico indistinto. Terzo, esiste una capacità tecnica o organizzativa di mantenere il backend nel tempo: un bot abbandonato è peggio di nessun bot, perché gli utenti lo percepiscono come un servizio rotto.
I criteri di esclusione sono speculari. Se non c'è automazione, se il pubblico è indifferenziato, o se non c'è nessuno che possa occuparsi della manutenzione, il bot non è lo strumento giusto. Un caso intermedio frequente: piccoli team che vogliono automatizzare un flusso interno senza avere competenze di sviluppo. In questa situazione la scelta ragionevole non è scrivere codice da zero, ma adottare una soluzione già esistente e verificarne i permessi richiesti, accettando il compromesso tra flessibilità e costo di manutenzione.
Best practice: regole decisionali rapide
Le indicazioni seguenti sono formulate come regole decisionali, da applicare nell'ordine in cui sono presentate. Non sostituiscono la documentazione ufficiale, ma coprono le decisioni che si prendono prima di scrivere la prima riga di codice.
Separa sempre l'ambiente di sviluppo da quello di produzione, creando due bot distinti tramite BotFather. Il costo è una manciata di minuti, il beneficio è l'eliminazione di una classe intera di errori, dal conflitto webhook alla sovrascrittura del token. Se il progetto cresce, questa separazione è la prima cosa che rimpiangerai di non aver fatto.
Definisci l'elenco dei comandi solo dopo aver implementato il comportamento corrispondente. Un menu pubblicato prima del codice è una promessa che non puoi mantenere, e gli utenti la verificano immediatamente. Se hai bisogno di tempo, pubblica un unico comando di avvio e amplia l'elenco in seguito.
Lascia la modalità privacy attiva come impostazione predefinita nei gruppi, e disattivala solo se hai una ragione documentata per farlo. Ogni messaggio in più che il bot riceve è un dato che devi proteggere e, se richiesto, cancellare. Il principio del minimo privilegio vale anche per i dati, non solo per i permessi.
Tratta il token come un segreto di produzione fin dal primo minuto, anche se il bot è un esperimento. Le abitudini prese sui prototipi si trasferiscono ai progetti reali. Se usi un gestore di segreti per altri servizi, usalo anche qui; se non ne usi, questo è un buon momento per iniziare.
Prevedi fin dall'inizio un meccanismo per cancellare i dati degli utenti su richiesta. Anche se oggi non ti sembra necessario, la domanda arriverà. Un bot che non sa cancellare ciò che ha ricevuto si trova in una posizione scomoda nel momento in cui la richiesta diventa formale.
Conclusione e passi successivi
La creazione di un bot Telegram tramite BotFather è un'operazione rapida che richiede pochi minuti, ma le decisioni che la circondano determinano la qualità del risultato nel medio periodo. Il comando di creazione è banale; la scelta dell'username, la gestione del token, la configurazione della privacy nei gruppi e la separazione tra ambienti sono le decisioni che fanno la differenza tra un esperimento e un servizio.
Se hai appena completato i passaggi descritti, il prossimo passo ragionevole non è aggiungere funzionalità, ma completare la verifica: chiama getMe, invia un messaggio di prova, controlla lo stato del webhook, verifica il comportamento del bot in un gruppo di prova. Solo dopo aver confermato che questi quattro controlli passano, ha senso scrivere logica di business.
Se invece stai valutando se imboccare questa strada, torna alla checklist degli scenari applicabili e non applicabili. La domanda decisiva non è tecnica: c'è qualcuno che si prenderà cura del bot tra sei mesi? Se la risposta è no, qualsiasi altra considerazione passa in secondo piano.
Infine, un promemoria valido per ogni fase del progetto: la piattaforma evolve e la documentazione ufficiale è l'unica fonte che riflette lo stato corrente. Le versioni dei client cambiano, i comandi di gestione possono essere riorganizzati, i limiti possono essere aggiornati. Un processo di verifica periodico, anche solo pochi minuti ogni tanto, è il modo più economico per restare allineati senza dover rincorrere i problemi.
Domande frequenti
Serve saper programmare per creare un bot con BotFather?
No. La creazione e la configurazione iniziale avvengono interamente in chat e non richiedono competenze di sviluppo. La programmazione diventa necessaria solo quando si vuole che il bot risponda agli utenti o si colleghi a un servizio esterno, perché in quel caso serve un processo che riceva gli aggiornamenti dall'API e invii le risposte.
Posso cambiare lo username di un bot dopo averlo creato?
Il nome visualizzato è modificabile in qualsiasi momento tramite il menu di gestione del bot in BotFather. Lo username segue regole più rigide: il vincolo del suffisso obbligatorio e la disponibilità globale restano validi anche in fase di modifica. Se il nuovo username non è disponibile, la modifica non va a buon fine e il bot mantiene quello precedente.
Cosa succede se perdo il token del bot?
Il token può essere recuperato dalla chat con BotFather, selezionando il bot interessato tra quelli elencati. Se il sospetto è che il token sia stato esposto, la procedura corretta è revocarlo e generarne uno nuovo: da quel momento le chiamate con il vecchio token vengono rifiutate, mentre il bot conserva identità, username e utenti.
Perché il bot non risponde ai messaggi nel gruppo ma funziona in chat privata?
La causa più probabile è la modalità privacy attiva, che limita la ricezione ai comandi, alle menzioni esplicite e alle risposte ai messaggi del bot. Per ricevere tutto il flusso la modalità va disattivata e, in molti casi, il bot va rimosso e riaggiunto al gruppo affinché la nuova impostazione abbia effetto sull'appartenenza in corso.
Meglio usare il polling o il webhook?
Il polling è più semplice da avviare e funziona anche in ambienti senza indirizzo pubblico, quindi è adatto a prototipi e sviluppo locale. Il webhook riduce la latenza e regge volumi maggiori, ma richiede un endpoint raggiungibile con certificato valido. I due modelli non possono coesistere sullo stesso bot: se un webhook è configurato, le chiamate di lettura degli aggiornamenti vengono rifiutate.