Cos’è davvero una Telegram Mini App - e quando ne costruirei una

Una Telegram Mini App non è un bot con bottoni più carini. È una vera applicazione web - HTML, CSS, JavaScript - che Telegram apre in un pannello dentro la chat. L’utente non esce dal messenger, non va su uno store e spesso non digita una password. Questo è il prodotto: un compito chiuso dove la conversazione c’è già.

Si dice ancora «Telegram Web App» - il nome vecchio. La stessa cosa: una pagina HTTPS più il WebApp SDK più un bot che la apre. Incollare un sito marketing in quella webview non è una Mini App. È un sito stretto con header Telegram. Questo articolo è come tratterei davvero quella superficie.

1. Mini App, bot, sito e app dello store

Queste quattro superfici chiudono compiti diversi. Mischiarle è un bot che finge di essere uno shop, o una Mini App che vuole posizionarsi su Google.

• Bot: interfaccia di chat. Bene per comandi, avvisi, un pagamento unico, «mandami questo PDF». Male per cataloghi, calendari e moduli in più passi.
• Sito: URL pubblica, SEO, link da condividere, desktop. La porta per chi non è già nel vostro Telegram.
• App dello store: installazione, push, offline, tassa Apple/Google. Giusto quando servono privilegi del sistema. Sbagliato quando il compito è «prenota uno slot in 40 secondi».
• Mini App: interfaccia completa dentro Telegram, identità dalla chat, pagamento via Stars o fatture, aggiornamenti senza revisione dello store. Il prodotto vive dove il cliente vi scrive già.

2. Come è montato davvero

Tre pezzi, non uno. Ne manca uno: avete una demo, non un prodotto.

• Un bot. Tiene il bottone menu, KeyboardButton web_app, il bottone inline o il link diretto (t.me/bot/app). Senza bot nessuno apre il pannello.
• Una applicazione web HTTPS. Telegram carica il vostro URL in una webview. Next.js su Vercel (o qualsiasi host HTTPS) va bene. HTTP e trucchi localhost solo in sviluppo.
• Il WebApp SDK (`window.Telegram.WebApp`). Tema, viewport, MainButton, BackButton, haptic, CloudStorage, fattura, oggetto utente. Senza di esso indovinate il CSS al buio.

3. Identità: initData non è una schermata di accesso

Quando Telegram apre la pagina aggiunge `initData` firmato: id utente, nome, lingua, query opzionale, hash. Quella è la sessione. L’utente ha già dimostrato di possedere quell’account - è dentro l’app. Non bullonate «accedi con email» salvo che dobbiate legare un’area riservata già esistente.

Non fidatevi mai di `initData` nel browser. Chiunque apre i DevTools e falsifica un oggetto utente. Il server deve validare l’hash HMAC col token del bot, controllare che `auth_date` sia fresco, poi emettere il vostro cookie di sessione o JWT. Senza quel passo non avete autenticazione. Avete un costume.

4. UX che non sembra un sito in un cassetto

Telegram ha già la sua cornice: maniglia, safe area, tema chiaro/scuro. Lottate contro e l’app sembra straniera. Usatela e sembra nativa.

• MainButton è l’azione principale - paga, prenota, invia. Un bottone CSS in basso finisce sotto l’indicatore home e sembra un clone.
• BackButton per schermi annidati. Lo swipe verso il basso in Telegram chiude la Mini App - non rubate quel gesto per «passo precedente».
• Leggete `themeParams` e `colorScheme`. Una pagina bianca fissa in un Telegram scuro sembra un bug.
• Il viewport non è `100vh`. Usate `viewportStableHeight` e expand quando vi serve il pannello intero. Testate iOS e Android - non sono d’accordo.

5. Quando metterei davvero una Mini App in produzione

Ne costruirei una quando il cliente è già in Telegram - o lo sarà, perché così parla questo business - e il compito ha bisogno di un’interfaccia vera, non di una catena di messaggi.

• Prenotazione con calendario, non «rispondi con una data». Shop con filtri. Aree corsi. Calcolatori che diventano un contatto. Carte fedeltà. Tool interni per un team che vive già in un gruppo.
• Pagamento che non deve uscire dalla chat: Telegram Stars, fatture, o il vostro checkout già in piedi - aperto dalla Mini App, confermato nel bot.

6. Quando rifiuterei

Una Mini App non sostituisce un sito. Non si posiziona. È una cattiva porta unica se metà dei compratori arriva da Google. È anche un pessimo posto per scaricare un CRM desktop.

• SEO, blog, catalogo pubblico, «chi siamo», assunzioni - quello è un sito. Linkate alla Mini App da lì se il compito continua in chat.
• Grafica pesante, tabelle enormi, admin a più finestre. Il pannello è pensato per il telefono. Il vero admin fatelo sul web.
• Se l’unico requisito è «abbiamo sentito che le Mini App sono di tendenza» e non c’è audience Telegram - partite da un sito e un bot che fa un solo compito.

7. La stack con cui aprirei nel 2026

La stessa disciplina di un MVP: un codice che poi può essere anche il sito, un database noioso, un bot che apre solo la porta e conferma i pagamenti.

• Next.js + TypeScript + Tailwind per l’interfaccia. Un’app: route Mini App e, se serve, il sito marketing pubblico.
• PostgreSQL come fonte di riferimento. Utenti indicizzati per Telegram id. Redis se servono limiti di ritmo o bozze brevi.
• Un bot piccolo (grammY o Telegraf) per Menu Button, fatture e messaggi post-pagamento. Non mettete la logica di business solo nel bot se la Mini App ne ha bisogno anche - un modulo condiviso.
• Validate initData sul server a ogni richiesta privilegiata. Non salvate segreti nella webview.

La Mini App è una porta, non un brand

Trattatela come una superficie di prodotto con un contratto: aprire in fretta, sembrare Telegram, provare l’utente sul server, finire un compito, rimandare la ricevuta in chat. Se vi servono scoperta, SEO e una storia per sconosciuti - quello è ancora un sito. Se vi servono una conversazione più un’interfaccia vera - quella è una Mini App. Metterei la seconda in produzione quando l’audience è già nel messenger. Non perché il nome vecchio «Web App» sembrava più economico di una build App Store.