Ce qu'est vraiment une Telegram Mini App - et quand j'en ferais une

Une Telegram Mini App n'est pas un bot avec de plus jolis boutons. C'est une vraie application web - HTML, CSS, JavaScript - que Telegram ouvre en panneau dans le chat. L'utilisateur ne quitte pas la messagerie, ne va pas sur un store, et souvent ne tape pas de mot de passe. C'est le produit : une tâche finie là où la conversation a déjà lieu.

On dit encore « Telegram Web App » - l'ancien nom. La même chose : une page HTTPS plus le WebApp SDK plus un bot qui l'ouvre. Coller un site marketing dans cette webview, ce n'est pas une Mini App. C'est un site coincé avec un en-tête Telegram. Cet article, c'est comment je traiterais vraiment cette surface.

1. Mini App, bot, site et app du store

Ces quatre surfaces répondent à des tâches différentes. Les mélanger, c'est un bot qui joue au magasin, ou une Mini App qui veut apparaître sur Google.

• Bot : interface de chat. Bien pour les commandes, les alertes, un paiement unique, « envoie-moi ce PDF ». Mauvais pour les catalogues, les calendriers et les formulaires en plusieurs étapes.
• Site : URL publique, SEO, liens à partager, desktop. La porte d'entrée pour ceux qui ne sont pas déjà dans votre Telegram.
• App du store : installation, push, hors ligne, taxe Apple/Google. Juste quand il faut des droits OS. Faux quand la tâche est « réserver un créneau en 40 secondes ».
• Mini App : interface complète dans Telegram, identité depuis le chat, paiement via Stars ou factures, mises à jour sans passage store. Le produit vit là où le client vous écrit déjà.

2. Comment c’est vraiment monté

Trois pièces, pas une. Il en manque une : vous avez une démo, pas un produit.

• Un bot. C'est lui qui tient le bouton menu, KeyboardButton web_app, le bouton inline, ou le lien direct (t.me/bot/app). Sans bot, personne n'ouvre le panneau.
• Une application web HTTPS. Telegram charge votre URL dans une webview. Next.js sur Vercel (ou n'importe quel hôte HTTPS) suffit. HTTP et astuces localhost, seulement en développement.
• Le WebApp SDK (`window.Telegram.WebApp`). Thème, viewport, MainButton, BackButton, haptic, CloudStorage, facture, objet utilisateur. Sans lui, vous devinez le CSS dans le noir.

3. Identité : initData n’est pas un écran de connexion

Quand Telegram ouvre votre page, il ajoute `initData` signé : id utilisateur, nom, langue, query optionnelle, hash. C'est la session. L'utilisateur a déjà prouvé qu'il possède ce compte - il est dans l'app. N'ajoutez pas « se connecter par e-mail » sauf pour lier un espace client existant.

Ne faites jamais confiance à `initData` dans le navigateur. N'importe qui ouvre les DevTools et fabrique un objet utilisateur. Le serveur doit valider le hash HMAC avec le token du bot, vérifier que `auth_date` est frais, puis émettre votre cookie de session ou JWT. Sans ça, vous n'avez pas d'authentification. Vous avez un déguisement.

4. Un UX qui ne ressemble pas à un site dans un tiroir

Telegram a déjà son habillage : poignée, safe areas, thème clair/sombre. Luttez contre, l'app paraît étrangère. Utilisez-le, elle paraît native.

• MainButton, c'est l'action principale - payer, réserver, envoyer. Un bouton CSS en bas passe sous l'indicateur home et ressemble à un clone.
• BackButton pour les écrans imbriqués. Le glissement vers le bas dans Telegram ferme la Mini App - ne volez pas ce geste pour « étape précédente ».
• Lisez `themeParams` et `colorScheme`. Une page blanche en dur dans un Telegram sombre ressemble à un bug.
• Le viewport n'est pas `100vh`. Utilisez `viewportStableHeight` et expand quand il faut tout le panneau. Testez iOS et Android - ils ne sont pas d'accord.

5. Quand je mettrais vraiment une Mini App en prod

J'en ferais une quand le client est déjà dans Telegram - ou le sera, parce que c'est comme ça que ce business parle - et que la tâche a besoin d'une vraie interface, pas d'une chaîne de messages.

• Réservation avec calendrier, pas « réponds avec une date ». Boutiques avec filtres. Espaces cours. Calculateurs qui deviennent une demande. Cartes de fidélité. Outils internes pour une équipe déjà dans un groupe.
• Paiement qui ne doit pas quitter le chat : Telegram Stars, factures, ou votre checkout déjà en place - ouvert depuis la Mini App, confirmé dans le bot.

6. Quand je refuserais

Une Mini App ne remplace pas un site. Elle n'apparaît pas dans Google. Elle est une mauvaise porte unique si la moitié des acheteurs arrive de Google. C'est aussi un mauvais endroit pour déverser un CRM desktop.

• SEO, blog, catalogue public, « à propos », pages recrutement - c'est un site. Liez vers la Mini App depuis là si la tâche continue dans le chat.
• Graphismes lourds, énormes tableaux, admin multi-fenêtres. Le panneau est pensé téléphone d'abord. Faites le vrai admin sur le web.
• Si la seule exigence est « on a entendu que les Mini Apps sont tendance » et qu'il n'y a pas d'audience Telegram - partez d'un site et d'un bot qui fait une seule tâche.

7. La stack par laquelle j’ouvrirais en 2026

La même discipline qu'un MVP : une base de code qui pourra aussi être le site plus tard, une base ennuyeuse, un bot qui n'ouvre que la porte et confirme les paiements.

• Next.js + TypeScript + Tailwind pour l'interface. Une app : routes Mini App et, si besoin, le site marketing public.
• PostgreSQL comme référentiel. Utilisateurs indexés par Telegram id. Redis si vous avez besoin de limites de débit ou de brouillons courts.
• Un petit bot (grammY ou Telegraf) pour Menu Button, factures et messages après paiement. Ne mettez pas la logique métier seulement dans le bot si la Mini App en a besoin aussi - un module partagé.
• Validez initData côté serveur à chaque requête privilégiée. Ne stockez rien de secret dans la webview.

La Mini App est une porte, pas une marque

Traitez-la comme une surface produit avec un contrat : ouvrir vite, ressembler à Telegram, prouver l'utilisateur côté serveur, finir une tâche, renvoyer le reçu dans le chat. S'il vous faut de la découverte, du SEO et une histoire pour des inconnus - c'est encore un site. S'il vous faut une conversation plus une vraie interface - c'est une Mini App. Je mettrais la seconde en prod quand l'audience est déjà dans la messagerie. Pas parce que l'ancien nom « Web App » sonnait moins cher qu'un build App Store.