Una Telegram Mini App è un’applicazione web che si apre dentro Telegram, con l’utente già autenticato e nella chat giusta. È tutta qui la proposta: nessun nuovo account, nessun download, nessun reset della password. Le sviluppo come qualsiasi prodotto web di produzione: Next.js e TypeScript sul frontend, Node.js sul backend, più alcune regole specifiche di Telegram. L’ultima che ho consegnato, sotto NDA, era una Web App e Mini App fintech con carte virtuali e fisiche, realizzata con Next.js, Express e MongoDB.
Si parte dal bot. BotFather crea il bot e la Mini App. L’utente può aprirla dal pulsante del menu, da un pulsante inline o da un link diretto t.me con il parametro startapp, che permette di passare un codice referral o aprire uno schermo specifico. L’app viene servita tramite HTTPS da un hosting normale; in sviluppo, un tunnel collega Telegram a localhost, così posso provarla su un telefono vero e non solo nel browser desktop.
Sull’autenticazione non taglio mai gli angoli. Telegram passa all’app initData: id e nome utente, auth_date e hash. initDataUnsafe è esattamente ciò che suggerisce il nome: va bene per mostrare un nome, mai per fidarsi. Il backend convalida gli initData grezzi con una firma HMAC derivata dal token del bot, verifica che auth_date sia recente e solo allora emette la propria sessione. Il token del bot non lascia mai il server. In un prodotto fintech, quel controllo fa la differenza tra «accesso tramite Telegram» e «chiunque abbia gli strumenti per sviluppatori può fingersi chiunque».
Poi la Mini App deve sembrare nativa, non un sito incollato in una webview. Leggo themeParams e le variabili CSS di Telegram per seguire il tema chiaro o scuro dell’app; uso MainButton e BackButton invece di disegnarli da zero, aggiungo feedback aptico per le azioni importanti e rispetto viewport e safe area, così nulla finisce sotto l’intestazione o l’indicatore Home. Qui mobile-first non è uno slogan: la maggior parte delle sessioni avviene con un pollice sul telefono.
Bot e Mini App lavorano in coppia. Il bot invia notifiche, conferme e ricevute; la Mini App gestisce le schermate con un modulo, un elenco o un checkout. I webhook arrivano al backend Node.js, che resta l’unica fonte di verità per pagamenti e stato: il client chiede, non decide. I beni digitali all’interno di Telegram si pagano con Stars, mentre beni fisici e servizi possono passare da provider di pagamento. Chiarisco la scelta presto con il cliente perché determina l’intero flusso.
Non accetto di fidarmi di initDataUnsafe, comprimere un sito desktop in una webview, lasciare il checkout solo nel frontend o creare una Mini App senza accesso web se all’azienda servono anche SEO o un dashboard interno. Se vuoi lanciare un prodotto su Telegram, mandami l’azione che l’utente deve completare nella chat. Ti risponderò con il flusso del bot, le schermate della Mini App e ciò che deve restare sul server.
Dai al prossimo prodotto qualcuno che resti.
Pronto a iniziare? Scrivimi: posso cominciare subito e restare. Collaborazioni a lungo termine, non passaggi di consegne dopo due settimane. Parliamo del progetto, dei requisiti e del modo migliore per procedere.