Telegram Bot API

Cómo probar una Mini App de Telegram: del navegador a Telegram real

· 7 min de lectura

Para probar una Mini App de Telegram, empieza en un navegador normal con un Telegram.WebApp simulado; después sirve tu build local por HTTPS, registra la URL en @BotFather y ábrela dentro de Telegram con DevTools conectado. El último paso ocurre en el servidor: valida initData antes de confiar en el usuario. Aquí tienes el flujo completo, de localhost a la checklist de producción.

Paso 1: prueba la interfaz en un navegador normal

Fuera de Telegram no hay ningún cliente detrás de Telegram.WebApp: no hay datos de inicio, ni tema, ni botones nativos. Aun así puedes construir casi toda la interfaz en el navegador de escritorio si tu código tolera esa situación:

const tg = window.Telegram?.WebApp;
const insideTelegram = Boolean(tg?.initData);

if (insideTelegram) {
  tg.ready();   // oculta el placeholder de carga lo antes posible
  tg.expand();
} else {
  console.info("Fuera de Telegram: usando datos mock");
}

Usa las variables del tema con un valor de respaldo, por ejemplo var(--tg-theme-bg-color, #fff), para que la página se lea bien en ambos entornos.

Para ver qué hace cada llamada de la API sin escribir código, abre Mini App Tester. En un navegador común funciona en modo mock y emula Telegram.WebApp: presiona MainButton y BackButton, abre popups, escribe en CloudStorage, cambia de tema y observa más de 45 eventos en el registro. Eso sí, los datos mock son solo un sustituto: su initData no está firmado por Telegram y fallará (con razón) la validación en el servidor.

Paso 2: corre la Mini App de Telegram desde localhost por HTTPS

Telegram abre Mini Apps solo desde URLs HTTPS (el entorno de prueba es la excepción) y, de todos modos, tu teléfono no puede llegar a http://localhost. La forma estándar de probar una Mini App de Telegram en localhost es un túnel que le dé a tu servidor de desarrollo una dirección HTTPS pública:

# inicia tu servidor de desarrollo, p. ej. Vite en el puerto 5173
npm run dev

# en otra terminal, usa uno de los túneles
ngrok http 5173
cloudflared tunnel --url http://localhost:5173

Cada herramienta imprime una URL pública https://. Dos tropiezos comunes:

Paso 3: registra la Mini App en @BotFather

Una Mini App siempre pertenece a un bot. Si todavía no tienes uno, sigue la guía cómo crear un bot en Telegram. Luego elige cómo abrirán los usuarios tu URL:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{"menu_button": {"type": "web_app", "text": "Abrir app",
       "web_app": {"url": "https://your-tunnel.example.com"}}}'

Sin chat_id, esto define el botón de menú por defecto para todos los usuarios. Cada vez que cambie la URL del túnel, repite la llamada en setChatMenuButton en Bot API Tester en vez de volver a escribir el curl.

Paso 4: usa el entorno de prueba de Telegram

Telegram mantiene un entorno de prueba separado donde los enlaces de Mini App pueden usar HTTP sin TLS, algo útil para probar en una red local. Requiere su propia cuenta y su propio bot:

Crea un bot con @BotFather dentro de la cuenta de prueba y envía las llamadas a https://api.telegram.org/bot<token>/test/METHOD_NAME. Los límites de flood no son más altos ahí e incluso pueden ser más estrictos, así que no sirve para pruebas de carga. La configuración completa, incluido el interruptor TEST de nuestro Bot API Tester, está en cómo usar el servidor de prueba de Telegram.

Paso 5: depura la Mini App dentro de Telegram

Muchos bugs que nunca aparecen en Chrome salen solo en el WebView real. Las instrucciones oficiales de Telegram, Debug Mode for Mini Apps, en resumen:

PlataformaCómo inspeccionar
iOSToca el ícono de Ajustes 10 veces y activa Allow Web View Inspection; conecta por USB y abre Develop → tu dispositivo en Safari en una Mac.
AndroidActiva la depuración USB; en Ajustes de Telegram baja hasta el final, mantén presionado el número de versión dos veces y elige Enable WebView Debug; abre chrome://inspect/#devices en Chrome.
Telegram Desktop (Windows, Linux)Instala la versión beta; Settings → Advanced → Experimental settings → Enable webview inspection; clic derecho → Inspect.
Telegram para macOSInstala la versión beta; haz clic 5 veces en el ícono de Ajustes y activa Debug Mini Apps; clic derecho → Inspect Element.

Para comparar clientes rápidamente, configura https://telegram-bot-api.info/telegram-mini-app-tester.html como URL de la Mini App de un bot de prueba. Dentro de Telegram, Mini App Tester usa la API real y muestra version, platform, colorScheme, themeParams, las safe areas y cada evento que dispara un cliente concreto. En tu propio código, condiciona las funciones nuevas con Telegram.WebApp.isVersionAtLeast("8.0") en lugar de suponer que todos tienen la última versión de la app.

Paso 6: valida initData en el servidor

Telegram.WebApp.initDataUnsafe sirve solo para mostrar datos. Envía la cadena cruda Telegram.WebApp.initData a tu backend y verifícala:

  1. Parsea el query string y quita hash.
  2. Ordena alfabéticamente los campos restantes y únelos como líneas key=value separadas por \n: esa es la data_check_string.
  3. Calcula secret_key = HMAC_SHA256(key="WebAppData", message=bot_token).
  4. Los datos son auténticos si hex(HMAC_SHA256(key=secret_key, message=data_check_string)) es igual a hash.
  5. Rechaza los datos viejos revisando auth_date.
import crypto from "node:crypto";

export function validateInitData(initData, botToken, maxAgeSec = 3600) {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash") ?? "";
  params.delete("hash");

  const dataCheckString = [...params.keys()].sort()
    .map((key) => `${key}=${params.get(key)}`)
    .join("\n");

  const secretKey = crypto.createHmac("sha256", "WebAppData").update(botToken).digest();
  const expected = crypto.createHmac("sha256", secretKey).update(dataCheckString).digest("hex");

  const valid = hash.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(expected));
  const age = Date.now() / 1000 - Number(params.get("auth_date"));
  if (!valid || !(age <= maxAgeSec)) return null;

  return { ...Object.fromEntries(params), user: JSON.parse(params.get("user") ?? "null") };
}

En el cliente, envía la cadena sin modificar, por ejemplo fetch("/api/session", { method: "POST", body: Telegram.WebApp.initData }), y valídala con el token del bot que abrió la app. Un tercero que no debe conocer tu token puede verificar en su lugar el campo signature con la clave pública Ed25519 de Telegram, como se explica en la documentación oficial.

Bot API 10.2: protección de origen de las Mini Apps

Bot API 10.2 prohibió llamar a los métodos de Mini App desde orígenes distintos al dominio original de la Mini App, y la protección se activó para todas las Mini Apps el 20 de julio de 2026. Durante las pruebas esto te afecta cuando la app redirige de la URL del túnel registrada a otro host, como un dominio de staging o una página de login: ahí las llamadas a Telegram.WebApp dejan de funcionar. Deja el código que habla con Telegram en el dominio registrado y vuelve a registrar la URL cada vez que cambie el host del túnel. Puedes desactivar la protección en la configuración de la Mini App en @BotFather, pero entonces te toca garantizar que la Mini App no tenga enlaces a sitios no confiables.

Checklist para probar una Mini App de Telegram

Tu código de validación depende del token del bot, así que mantenlo en secreto: revisa cómo obtener y proteger el token del bot. Si el mismo backend también recibe actualizaciones del bot, sigue con cómo configurar el webhook de un bot de Telegram. Y si solo necesitas un bloque interactivo pequeño dentro de un mensaje del chat, en lugar de una app web completa, mira los widgets de Telegram, que llegaron con Bot API 10.4.

Preguntas frecuentes

¿Cómo pruebo una Mini App de Telegram en localhost?

Telegram solo abre Mini Apps desde URLs HTTPS, así que expón tu servidor de desarrollo con un túnel HTTPS (por ejemplo ngrok o Cloudflare Tunnel) y registra esa URL en @BotFather o con setChatMenuButton. En el entorno de prueba se permiten enlaces HTTP.

¿Puedo probar una Mini App de Telegram sin Telegram?

En parte. Un navegador normal no tiene cliente de Telegram, así que necesitas un mock de Telegram.WebApp, como el modo mock de Mini App Tester. El initData real, los popups nativos y la vibración solo funcionan dentro de Telegram.

¿Cómo abro DevTools para una Mini App de Telegram?

En iOS activa Allow Web View Inspection (toca Ajustes 10 veces) y usa el menú Develop de Safari. En Android activa WebView Debug en los ajustes de depuración de Telegram y abre chrome://inspect/#devices. En escritorio y macOS usa las opciones de inspección de las versiones beta.

¿Por qué falla la validación de initData?

Causas habituales: validar initDataUnsafe en lugar de la cadena cruda initData, usar el token de otro bot, no decodificar los valores de la URL, dejar hash en la cadena de verificación, invertir la clave y el mensaje del HMAC o probar con datos mock que Telegram nunca firmó.

¿Por qué los métodos de Telegram.WebApp dejan de funcionar en otro dominio?

Desde Bot API 10.2, los métodos de Mini App se bloquean si se llaman desde un origen distinto al dominio de la Mini App; la protección se activó para todas las Mini Apps el 20 de julio de 2026. Mantén la app en su dominio registrado o desactiva la protección en @BotFather.

¿Existe un servidor de prueba para Mini Apps de Telegram?

Sí. El entorno de prueba está separado de producción: necesitas una cuenta y un bot nuevos ahí, las llamadas a la Bot API van a https://api.telegram.org/bot<token>/test/METHOD_NAME y los enlaces de la Mini App pueden usar HTTP sin TLS.

Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje

Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.

Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless

Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.

Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más

Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.

Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo

Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.

Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes

Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.

Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start

Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.

Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard

Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.

Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes

Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.

Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso

Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.

Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)

Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.

Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)

Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.

Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas

Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.

Bot inline de Telegram: cómo activar el modo inline y responder consultas

Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.

Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones

Acepta pagos con Telegram Stars en tu bot: sendInvoice con XTR, pre_checkout_query, successful_payment, reembolsos y suscripciones, con código.

Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas

Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.

Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir

Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.

API JavaScript de TelegramWidget: referencia, eventos, errores y límites

Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.

Ejemplos de widgets de Telegram: HTML completo y bot en Python

Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.

Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot

Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.