Qué es de verdad una Telegram Mini App - y cuándo yo construiría una

Una Telegram Mini App no es un bot con botones más bonitos. Es una aplicación web de verdad - HTML, CSS, JavaScript - que Telegram abre en un panel dentro del chat. El usuario no sale del messenger, no va a una store y a menudo no escribe una contraseña. Eso es el producto: una tarea hecha donde ya está la conversación.

Siguen diciendo «Telegram Web App» - el nombre viejo. Lo mismo: una página HTTPS más el WebApp SDK más un bot que la abre. Pegar un sitio de marketing en ese webview no es una Mini App. Es un sitio apretado con cabecera de Telegram. Este artículo es cómo yo trataría de verdad esa superficie.

1. Mini App, bot, sitio y app de store

Estas cuatro superficies resuelven tareas distintas. Mezclarlas es un bot que finge ser tienda, o una Mini App que quiere posicionarse en Google.

• Bot: interfaz de chat. Bien para comandos, avisos, un pago único, «mándeme este PDF». Mal para catálogos, calendarios y formularios de varios pasos.
• Sitio: URL pública, SEO, enlaces para compartir, escritorio. La puerta para quien aún no está en su Telegram.
• App de store: instalar, push, sin conexión, impuesto de Apple/Google. Correcto cuando necesita privilegios del sistema. Incorrecto cuando la tarea es «reservar un hueco en 40 segundos».
• Mini App: interfaz completa dentro de Telegram, identidad del chat, pago por Stars o facturas, actualizaciones sin revisión de store. El producto vive donde el cliente ya le escribe.

2. Cómo está montado de verdad

Tres piezas, no una. Falta cualquiera y tiene una demo, no un producto.

• Un bot. Él sostiene el botón de menú, KeyboardButton web_app, el botón inline o el enlace directo (t.me/bot/app). Sin bot nadie abre el panel.
• Una aplicación web HTTPS. Telegram carga su URL en un webview. Next.js en Vercel (o cualquier host HTTPS) vale. HTTP y trucos de localhost, solo en desarrollo.
• El WebApp SDK (`window.Telegram.WebApp`). Tema, viewport, MainButton, BackButton, háptic, CloudStorage, factura, objeto de usuario. Sin él adivina CSS a oscuras.

3. Identidad: initData no es una pantalla de inicio de sesión

Cuando Telegram abre su página añade `initData` firmado: id de usuario, nombre, idioma, query opcional, hash. Esa es la sesión. El usuario ya demostró que posee esa cuenta: está dentro de la app. No atornille «entrar con email» salvo que deba vincular una cuenta existente.

Nunca confíe en `initData` en el navegador. Cualquiera abre DevTools y finge un objeto de usuario. El servidor debe validar el hash HMAC con el token del bot, comprobar que `auth_date` está fresco y emitir su propia cookie de sesión o JWT. Sin ese paso no hay autenticación. Hay un disfraz.

4. UX que no se siente como un sitio en un cajón

Telegram ya tiene su propia interfaz: asa, safe areas, tema claro/oscuro. Pelee contra eso y la app se siente extranjera. Úselo y se siente nativa.

• MainButton es la acción principal - pagar, reservar, enviar. Un botón CSS abajo queda bajo el indicador home y parece un clon.
• BackButton para pantallas anidadas. El desliz hacia abajo en Telegram cierra la Mini App - no robe ese gesto para «paso anterior».
• Lea `themeParams` y `colorScheme`. Una página blanca fija en Telegram oscuro parece un bug.
• El viewport no es `100vh`. Use `viewportStableHeight` y expand cuando necesite el panel entero. Pruebe iOS y Android - no coinciden.

5. Cuándo yo lanzaría de verdad una Mini App

Yo construiría una cuando el cliente ya está en Telegram - o lo estará, porque así habla este negocio - y la tarea necesita una interfaz de verdad, no una cadena de mensajes.

• Reserva con calendario, no «responde con una fecha». Tiendas con filtros. Áreas de cursos. Calculadoras que se vuelven un lead. Tarjetas de fidelidad. Herramientas internas para un equipo que ya vive en un grupo.
• Pago que no debe salir del chat: Telegram Stars, facturas, o su checkout actual - abierto desde la Mini App, confirmado en el bot.

6. Cuándo me negaría

Una Mini App no sustituye un sitio. No se posiciona. Es una mala puerta única si la mitad de los compradores llega de Google. También es un mal sitio para volcar un CRM de escritorio.

• SEO, blog, catálogo público, «sobre nosotros», empleo - eso es un sitio. Enlace a la Mini App desde ahí si la tarea sigue en el chat.
• Gráficos pesados, tablas enormes, admin de varias ventanas. El panel es primero teléfono. El admin de verdad, en la web.
• Si el único requisito es «hemos oído que las Mini Apps están de moda» y no hay audiencia en Telegram - empiece por un sitio y un bot que hace una sola tarea.

7. La stack con la que abriría en 2026

La misma disciplina que un MVP: un código que luego pueda ser también el sitio, una base aburrida, un bot que solo abre la puerta y confirma pagos.

• Next.js + TypeScript + Tailwind para la interfaz. Una app: rutas Mini App y, si hace falta, el sitio de marketing público.
• PostgreSQL como fuente de referencia. Usuarios indexados por Telegram id. Redis si necesita límites de ritmo o borradores cortos.
• Un bot pequeño (grammY o Telegraf) para Menu Button, facturas y mensajes post-pago. No deje la lógica de negocio solo en el bot si la Mini App también la necesita - un módulo compartido.
• Valide initData en el servidor en cada petición privilegiada. No guarde secretos en el webview.

La Mini App es una puerta, no una marca

Trátela como una superficie de producto con contrato: abrir rápido, parecer Telegram, probar al usuario en el servidor, terminar una tarea, devolver el recibo al chat. Si necesita descubrimiento, SEO e historia para extraños - eso sigue siendo un sitio. Si necesita una conversación más una interfaz de verdad - eso es una Mini App. Yo lanzaría la segunda cuando la audiencia ya está en el messenger. No porque el nombre viejo «Web App» sonara más barato que un build de App Store.