Un botón de Mini App queda bajo la barra: qué documentación de Telegram revisar
Distingue altura de viewport, área segura del dispositivo, área segura de Telegram y soporte de pantalla completa antes de asignar una captura de diseño.
Señales que conviene observar
- La versión y la plataforma de WebApp acompañan a la captura
- El viewport dinámico y estable se separa de las dos áreas seguras
- El evento de pantalla completa u orientación puede reproducirse en una superficie propia
Si un botón de Telegram Mini App queda detrás de una muesca, barra del sistema o control de Telegram, abre la API (interfaz de programación de aplicaciones) oficial de WebApp y registra cinco observaciones: version y platform, viewportHeight y viewportStableHeight, safeAreaInset, contentSafeAreaInset y el resultado de pantalla completa. La captura enseña el síntoma, no la frontera que cambió.
Esta ruta sirve al coordinador de una agencia que revisa grupos autorizados de fundadores y desarrolladores. La conversación útil describe un fallo reproducible en un cliente concreto. Llegar un día tarde puede dejar que otro proveedor organice la investigación; cotizar con una sola imagen puede enviar el trabajo al especialista equivocado.
Empieza por WebApp.version y WebApp.platform
La documentación oficial de Mini Apps enumera version y platform. La primera indica la versión de Bot API disponible en la aplicación Telegram del usuario; la segunda identifica la plataforma.
«Falla en iPhone» no basta: puede tratarse de otra superficie, cliente antiguo o modo de lanzamiento. Pide una ruta de prueba propia, ambos valores, la orientación y la hora. No hacen falta credenciales ni datos de usuarios. Sin esos elementos existe un informe de compatibilidad, no un encargo técnico completo.
Elige la propiedad de viewport que corresponde al problema
viewportHeight es la altura visible actual y cambia mientras el usuario expande o contrae la Mini App. Telegram advierte que su frecuencia de actualización no permite que un control siga suavemente el borde inferior móvil.
viewportStableHeight representa el último estado estable y es más apropiado para fijar elementos abajo. El evento viewportChanged incluye isStateStable: verdadero cuando terminó el cambio, falso durante el gesto o la animación.
Si el botón salta durante el movimiento y termina bien, revisa el uso de los dos estados. Si sigue cubierto después de estabilizarse, continúa con las áreas seguras y el CSS. Una imagen sin estado ni valores no distingue ambos casos.
El área del dispositivo y el área de contenido no son iguales
safeAreaInset contempla elementos del sistema, como muescas y barras de navegación. contentSafeAreaInset representa el espacio donde el contenido no queda debajo de elementos de la interfaz de Telegram.
La diferencia importa en diseños de borde a borde: un control puede evitar la muesca y seguir bajo un control de Telegram. Sumar ambos márgenes sin entenderlos también puede crear espacio excesivo. Registra los cuatro lados y qué utiliza el CSS.
safeAreaChangedocurre cuando cambia el área segura del dispositivo.contentSafeAreaChangedocurre cuando cambia el espacio seguro del contenido.- La documentación actual marca ambos como Bot API 8.0+ y los nuevos valores se leen en sus propiedades.
El controlador del evento no recibe los insets como carga. La aplicación lee la propiedad actualizada. Esta precisión evita pedir un campo de evento inexistente.
Pantalla completa tiene eventos observables
Para Bot API 8.0+, Telegram documenta requestFullscreen(), isFullscreen, fullscreenChanged y fullscreenFailed. El primer evento confirma entrada o salida; el segundo puede indicar UNSUPPORTED o ALREADY_FULLSCREEN.
Una pantalla sin cabecera puede parecer completa, pero no prueba qué método se ejecutó. Guarda la acción, el evento, isFullscreen, la versión y la plataforma. Un resultado UNSUPPORTED define una frontera de compatibilidad; si no hubo instrumentación, el siguiente trabajo es observar, no afirmar que Telegram ignoró la petición.
Cinco líneas superan diez capturas sin contexto
Un traspaso útil contiene:
- Entrada: enlace o superficie de prueba propios y redactados.
- Cliente:
version,platform, orientación y hora. - Viewport: altura actual, estable e
isStateStable. - Insets: valores de dispositivo y contenido antes y después.
- Pantalla completa: acción, estado y evento de éxito o fallo.
Después añade una captura o grabación breve, ocultando cuentas, chats privados y contenido ajeno. El objetivo es conectar el solapamiento con un estado observable, no publicar la pantalla del usuario.
Ejemplo compuesto: «en iOS el botón de checkout queda bajo la barra al entrar en full screen; desktop bien; ¿qué inset usamos?». No es un caso real. Faltan versión, superficie, valores, orientación, CSS, propietario y permiso de contacto. Merece clasificación porque remite a campos oficiales, pero no demuestra una causa.
Asigna según la primera observación que falta
Sin versión y plataforma, vuelve a reproducción. Si ocurre solo durante el cambio de tamaño, revisa el estado del viewport. Si los insets contradicen el CSS, asigna a diseño. Si pantalla completa devuelve incompatibilidad, prepara una variante compatible.
TOP Prospect puede reunir fragmentos autorizados, fuente, hora, síntomas y desconocidos para revisión humana. No puede ejecutar JavaScript, entrar al repositorio, verificar identidad ni contactar al autor; la configuración nueva de objetivos se guarda, pero todavía no genera candidatos automáticamente.
La diferencia entre Bot API y MTProto ayuda a separar superficies técnicas. La comprobación del enlace original conserva la fuente y la guía de temas del foro mantiene la respuesta en su hilo. Las opciones están en precios.
Datos clave
versionyplatformdescriben la superficie WebApp disponible.- La altura actual cambia; la estable conserva el último estado final.
- Telegram desaconseja fijar controles al borde móvil con
viewportHeight. - Un área segura contempla el dispositivo y la otra la interfaz de Telegram.
- Los eventos 8.0+ ofrecen cambios y fallos observables.
- Una captura no demuestra causa, propiedad ni autoridad de compra.
Preguntas frecuentes
¿Dónde están los campos de área segura?
En la API oficial WebApp y en la tabla de eventos de Mini Apps.
¿Son intercambiables las dos áreas?
No: una cubre la interfaz del sistema y otra los controles de Telegram.
¿Qué altura sirve para un botón inferior?
Telegram señala viewportStableHeight y advierte sobre el borde móvil de viewportHeight.
¿Cómo se observa incompatibilidad con pantalla completa?
fullscreenFailed puede devolver UNSUPPORTED; guarda también versión y plataforma.
Revisión editorial completada el 26 de agosto de 2026 con la documentación oficial de Telegram Mini Apps.
Preguntas frecuentes
¿Dónde documenta Telegram los campos de área segura?
En la API oficial WebApp de Telegram Mini Apps, dentro de las propiedades safeAreaInset y contentSafeAreaInset y su tabla de eventos.
¿safeAreaInset y contentSafeAreaInset son iguales?
No. El primero contempla la interfaz del sistema del dispositivo; el segundo, el espacio libre de controles de Telegram.
¿Debe un botón inferior seguir viewportHeight?
Telegram advierte que viewportHeight no se actualiza con suficiente rapidez y señala viewportStableHeight para elementos fijados abajo.
¿Qué demuestra que pantalla completa no es compatible?
En Bot API 8.0+, fullscreenFailed puede indicar UNSUPPORTED; una captura sola no demuestra ese evento.
Fuentes y lecturas adicionales
Cómo se descubre una Signal que merece atención
La metodología muestra cómo Top Prospect encuentra y organiza Signals que conviene revisar, conserva el contexto original de Telegram, elimina duplicados y ayuda a decidir qué mirar primero. Tú decides si hacer seguimiento y qué hacer después.