Events

Mini Apps communicate with the client through an event system. Use Telegram.WebApp.onEvent() to subscribe and Telegram.WebApp.offEvent() to unsubscribe.

// Subscribe to event
Telegram.WebApp.onEvent(eventType, eventHandler);

// Unsubscribe
Telegram.WebApp.offEvent(eventType, eventHandler);

Lifecycle Events

activated

Triggered when the Mini App enters the active state. Bot API 8.0+

deactivated

Triggered when the Mini App enters the inactive state. Bot API 8.0+

View Events

themeChanged

Triggered when the client theme changes.

Telegram.WebApp.onEvent('themeChanged', () => {
  console.log('New theme:', Telegram.WebApp.colorScheme);
  console.log('Theme params:', Telegram.WebApp.themeParams);
});

viewportChanged

Triggered when the Mini App viewport size changes.

Callback parameter: Object

Field	Type	Description
isStateStable	Boolean	Whether the viewport change has stabilized

Telegram.WebApp.onEvent('viewportChanged', (event) => {
  if (event.isStateStable) {
    console.log('Viewport height:', Telegram.WebApp.viewportHeight);
  }
});

safeAreaChanged

Triggered when the device safe area changes. Bot API 8.0+

contentSafeAreaChanged

Triggered when the content safe area changes. Bot API 8.0+

fullscreenChanged

Triggered when the fullscreen mode state changes. Bot API 8.0+

fullscreenFailed

Triggered when a fullscreen request fails. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
error	String	Error reason: "UNSUPPORTED" or "ALREADY_FULLSCREEN"

Button Events

backButtonClicked

Triggered when the back button is clicked.

Telegram.WebApp.onEvent('backButtonClicked', () => {
  window.history.back();
});

mainButtonClicked

Triggered when the main button is clicked.

secondaryButtonClicked

Triggered when the secondary button is clicked. Bot API 7.10+

settingsButtonClicked

Triggered when the settings button is clicked. Bot API 7.0+

Interaction Events

popupClosed

Triggered when a popup is closed.

Callback parameter: Object

Field	Type	Description
button_id	String | null	ID of the button clicked by the user, or null if the popup was dismissed

qrTextReceived

Triggered when a QR code is successfully scanned. Bot API 6.9+

Callback parameter: Object

Field	Type	Description
data	String	Scanned text content

scanQrPopupClosed

Triggered when the QR code scanning popup is closed. Bot API 7.7+

clipboardTextReceived

Triggered when clipboard reading is complete. Bot API 6.9+

Callback parameter: Object

Field	Type	Description
data	String | null	Clipboard text content, or null if reading failed

invoiceClosed

Triggered when the invoice payment interface is closed.

Callback parameter: Object

Field	Type	Description
url	String	Invoice link
status	String	Payment status: "paid", "cancelled", "failed", "pending"

writeAccessRequested

Result of a write access permission request. Bot API 6.9+

Callback parameter: Object

Field	Type	Description
status	String	Result: "allowed" or "cancelled"

contactRequested

Result of a contact information request. Bot API 6.9+

Callback parameter: Object

Field	Type	Description
status	String	Result: "sent" or "cancelled"

Sharing Events

shareMessageSent

Triggered when a message is shared successfully. Bot API 8.0+

shareMessageFailed

Triggered when a message sharing fails. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
error	String	Error reason: "UNSUPPORTED", "MESSAGE_EXPIRED", "MESSAGE_SEND_FAILED", "USER_DECLINED"

emojiStatusSet

Triggered when an emoji status is set successfully. Bot API 8.0+

emojiStatusFailed

Triggered when setting an emoji status fails. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
error	String	Error reason: "UNSUPPORTED", "SUGGESTED_EMOJI_INVALID", "DURATION_INVALID", "USER_DECLINED"

emojiStatusAccessRequested

Result of an emoji status permission request. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
status	String	Result: "allowed" or "cancelled"

fileDownloadRequested

File download request result. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
status	String	Result: "downloading" or "cancelled"

Sensor Events

accelerometerStarted

Triggered when the accelerometer starts collecting data. Bot API 8.0+

accelerometerStopped

Triggered when the accelerometer stops collecting data. Bot API 8.0+

accelerometerChanged

Triggered when accelerometer data updates. Bot API 8.0+

accelerometerFailed

Triggered when the accelerometer fails to start. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
error	String	Error reason: "UNSUPPORTED"

deviceOrientationStarted

Triggered when the device orientation sensor starts collecting data. Bot API 8.0+

deviceOrientationStopped

Triggered when the device orientation sensor stops collecting data. Bot API 8.0+

deviceOrientationChanged

Triggered when device orientation data updates. Bot API 8.0+

deviceOrientationFailed

Triggered when the device orientation sensor fails to start. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
error	String	Error reason: "UNSUPPORTED"

gyroscopeStarted

Triggered when the gyroscope starts collecting data. Bot API 8.0+

gyroscopeStopped

Triggered when the gyroscope stops collecting data. Bot API 8.0+

gyroscopeChanged

Triggered when gyroscope data updates. Bot API 8.0+

gyroscopeFailed

Triggered when the gyroscope fails to start. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
error	String	Error reason: "UNSUPPORTED"

Location Events

locationManagerUpdated

Triggered when the location manager state updates. Bot API 8.0+

locationRequested

Location request result. Bot API 8.0+

Callback parameter: Object

Field	Type	Description
locationData	LocationData	Location data object, null if the request failed

Biometric Events

biometricManagerUpdated

Triggered when the biometric manager state updates. Bot API 7.2+

biometricAuthRequested

Biometric authentication result. Bot API 7.2+

Callback parameter: Object

Field	Type	Description
isAuthenticated	Boolean	Whether authentication was successful
biometricToken	String	Token returned on successful authentication

biometricTokenUpdated

Biometric token update result. Bot API 7.2+

Callback parameter: Object

Field	Type	Description
isUpdated	Boolean	Whether the token was updated successfully

Usage Example

const tg = Telegram.WebApp;

// Listen to multiple events
tg.onEvent('viewportChanged', (e) => {
  if (e.isStateStable) {
    adjustLayout();
  }
});

tg.onEvent('themeChanged', () => {
  applyTheme(tg.themeParams);
});

tg.onEvent('popupClosed', (e) => {
  if (e.button_id === 'confirm') {
    handleConfirm();
  }
});

tg.onEvent('invoiceClosed', (e) => {
  if (e.status === 'paid') {
    showSuccess();
  }
});