A Mini App Button Sits Under the System Bar—Which Telegram Docs Matter?
Use the official WebApp API to separate viewport height, device safe area, Telegram content safe area and fullscreen support before routing a layout screenshot.
Signals to watch
- The requester provides Telegram WebApp version and platform alongside the screenshot
- Viewport and stable viewport values are separated from device and content safe-area insets
- A fullscreen or orientation event can be reproduced on an owned test surface
If a Telegram Mini App button sits behind a notch, system bar or Telegram control, open the official WebApp API (application programming interface) and identify five observations before assigning the repair: version and platform, viewportHeight and viewportStableHeight, safeAreaInset, contentSafeAreaInset, and any fullscreen result. A screenshot shows the symptom; it does not identify which boundary moved.
This source path is for a project coordinator at a Mini App development agency watching authorised founder, product and developer groups. The useful Signal is a reproducible client-specific layout problem, not every image captioned “UI broken.” A day can matter when a launch owner is choosing who will investigate, but a fast quote based on one screenshot can send CSS, application and client-compatibility questions to the wrong specialist.
Start at WebApp.version and WebApp.platform
Telegram’s official Mini Apps documentation lists version and platform on the WebApp object. version is the Bot API version available in the user’s Telegram app; platform is the name of that Telegram app platform.
Those values belong beside the screenshot. “iPhone” is not enough, because the requester may be using a web surface, an older client or a different launch path. “Works on Android” is also incomplete without the app context and the same UI state.
The coordinator does not need private credentials or production user data. Ask for an owned test path, the two WebApp values, the launch surface and a reproduction time. If the requester cannot produce those basics, the record is a compatibility report that needs evidence, not yet an implementation brief.
Choose the viewport property that matches the question
The API defines two visible-height properties that should not be treated as interchangeable.
viewportHeight is the current visible height. It changes as a user expands or collapses the Mini App. Telegram specifically warns that its refresh rate is not sufficient to make an interface element smoothly follow the moving lower border.
viewportStableHeight is the height at the last stable state. Telegram documents it as the more appropriate value for pinning elements to the bottom. The related viewportChanged event includes isStateStable, which tells the application whether resizing is finished or still underway.
This creates a concrete routing question. If a button jumps only during a drag animation but lands correctly, investigate the unstable-versus-stable viewport use. If the button remains under a control after the viewport settles, continue to safe-area fields and the application’s CSS. The same screenshot cannot distinguish those moments unless the state and values were recorded.
Device safe area and Telegram content safe area are separate
safeAreaInset represents device safe-area margins that account for system UI such as notches and navigation bars. contentSafeAreaInset represents the area for content that is free from overlap by Telegram interface elements.
The difference matters in fullscreen and edge-to-edge layouts. A control can clear the physical notch yet still sit under Telegram’s own interface. Conversely, adding both insets blindly can produce excessive padding. The coordinator should ask what the code currently applies and capture the four inset values at the moment of failure.
The official event table provides the corresponding observation points:
safeAreaChangedfires when device safe-area insets change, such as after an orientation or screen adjustment;contentSafeAreaChangedfires when the Telegram-safe content area changes;- both are marked Bot API 8.0+ in the current documentation and expose their current values through the matching WebApp properties.
The event handler itself receives no inset payload according to the documentation. The application reads the updated property. That small detail helps a coordinator avoid asking for an imaginary event body in the handoff.
Fullscreen has a result, not just a visual state
For Bot API 8.0+, Telegram documents requestFullscreen(), the isFullscreen property and two events: fullscreenChanged and fullscreenFailed.
fullscreenChanged indicates that the Mini App entered or left fullscreen; the current state is read from isFullscreen. fullscreenFailed can report UNSUPPORTED or ALREADY_FULLSCREEN. An image with no Telegram header may look fullscreen, but it does not prove which method ran or whether a failure event occurred.
Ask for the action that requested fullscreen, the event observed, the isFullscreen value, and the version/platform pair. If fullscreenFailed reports UNSUPPORTED, the project has a documented compatibility boundary. If no event was instrumented, the next task is observation, not a claim that Telegram ignored the request.
A five-line handoff is more useful than ten screenshots
An implementation-ready record can be short:
- Launch: exact owned test link or bot surface, with secrets removed.
- Client:
WebApp.version,WebApp.platform, device orientation and time. - Viewport: current and stable heights plus
isStateStablewhen the issue appears. - Insets:
safeAreaInsetandcontentSafeAreaInsetvalues before and after the change. - Fullscreen: request action,
isFullscreen, and changed or failed event result.
Add one screenshot or short screen recording only after these labels exist. Redact accounts, private chats and unrelated group content. The objective is not to publish a user’s screen; it is to connect a visible overlap to an observable API state.
Consider this illustrative fragment from an authorised developer discussion:
Composite message: “bottom checkout button sits under the bar on ios when full screen. desktop ok. anyone know which inset?”
The fragment names a platform family and symptom but not the client version, launch surface, viewport state, inset values, orientation, CSS, repository access, project owner or permission to contact. It is worth triage because the question maps to official fields. It is not yet evidence that one particular inset or Telegram defect caused the overlap.
Route the request by the first missing observation
When version/platform are missing, route to reproduction intake. When the failure appears only during resize, route to viewport-state handling. When device and content insets differ from the CSS assumptions, route to layout engineering. When fullscreen reports an explicit unsupported result, route to compatibility design rather than promising identical behaviour on that surface.
TOP Prospect can retain authorised group fragments, source, time, repeated symptoms and explicit unknowns so a project coordinator reviews the reproducible thread before a context-free screenshot. It cannot inspect the Mini App, run client JavaScript, access a repository, verify an identity or contact the author. Its current production matching-target interface stores new configurations but does not automatically generate new candidates.
The developer-group evidence article helps distinguish first-hand reproduction details from repeated hearsay. The original-message link check protects the source reference, while the forum-topic context guide keeps a technical reply inside the right thread. Product access is described on pricing.
Key facts
versionandplatformdescribe the Telegram WebApp API surface available to the client.viewportHeightcan change during gestures;viewportStableHeightrepresents the last stable state.- Telegram warns against using
viewportHeightto pin controls smoothly to a moving lower edge. safeAreaInsetcovers device system UI;contentSafeAreaInsetcovers Telegram UI overlap.- Safe-area and fullscreen events documented as Bot API 8.0+ provide observable state changes or failures.
- A screenshot cannot establish root cause, ownership or purchase authority.
FAQ
Where are the safe-area fields documented?
In Telegram’s official Mini Apps WebApp API, alongside the WebApp properties and the events available to Mini Apps.
Are the two safe-area fields interchangeable?
No. One describes device system UI margins; the other describes content space free from Telegram interface overlap.
Which height should a bottom control use?
Telegram points to viewportStableHeight for bottom-pinned elements and warns that viewportHeight is not refreshed quickly enough to follow the moving edge smoothly.
How is fullscreen incompatibility observed?
On Bot API 8.0+, fullscreenFailed can report UNSUPPORTED. Save the event plus the client version and platform rather than inferring it from appearance.
Editorial review completed 26 August 2026 against Telegram’s official Mini Apps WebApp API documentation.
Frequently asked questions
Where are Telegram Mini App safe-area fields documented?
In the official Telegram Mini Apps WebApp API, under the WebApp properties for safeAreaInset and contentSafeAreaInset and the related event table.
Are safeAreaInset and contentSafeAreaInset the same?
No. The first accounts for device system UI; the second describes the content area free from overlap by Telegram interface elements.
Should a bottom button follow viewportHeight?
Telegram warns that viewportHeight is not refreshed quickly enough to pin controls smoothly to a moving lower edge and points to viewportStableHeight for that use.
What proves fullscreen is unsupported?
On Bot API 8.0+ the fullscreenFailed event can report UNSUPPORTED. A screenshot alone does not establish that event or the client version.
Sources and further reading
How a Signal worth attention is found
See how Top Prospect finds and organizes Signals worth checking, keeps the original Telegram context, removes duplicates, and helps you decide what to review first. You decide whether to follow up and what to do next.