telegram-webapps
Version:
Typings for Telegram Mini Apps
1,266 lines (1,261 loc) • 93.9 kB
TypeScript
interface BasePopupButton {
/**
* Identifier of the button, 0-64 characters. Set to empty string by
* default.
*
* If the button is pressed, its *id* is returned in the callback and the
* *popupClosed* event.
*/
id?: string
}
interface DefaultDestructivePopupButton extends BasePopupButton {
/**
* Type of the button. Set to *default* by default.
*
* Can be one of these values:
* - *default*, a button with the default style,
* - *destructive*, a button with a style that indicates a destructive action (e.g.
* “Remove”, “Delete”, etc.).
*/
type?: 'default' | 'destructive'
/**
* The text to be displayed on the button, 0-64 characters.
*/
text: string
}
interface OkCloseCancelPopupButton extends BasePopupButton {
/**
* Type of the button.
*
* Can be one of these values:
* - *ok*, a button with the localized text “OK”,
* - *close*, a button with the localized text “Close”,
* - *cancel*, a button with the localized text “Cancel”.
*/
type: 'ok' | 'close' | 'cancel'
}
export declare namespace TelegramWebApps {
/**
* To connect your Web App to the Telegram client, place the script telegram-web-app.js
* in the `<head>` tag before any other scripts, using this code:
* ```html
* <script src="https://telegram.org/js/telegram-web-app.js"></script>
* ```
* Once the script is connected, a `window.Telegram.WebApp` object will become available
* with the following fields
*/
interface WebApp {
/**
* A string with raw data transferred to the Web App, convenient for validating data.
*
* **WARNING:** Validate data from this field before using it on the bot's server.
*/
readonly initData: string
/**
* An object with input data transferred to the Web App.
*
* **WARNING:** Data from this field should not be trusted. You should only use data
* from initData on the bot's server and only after it has been validated.
*/
readonly initDataUnsafe: WebAppInitData
/**
* The version of the Bot API available in the user's Telegram app.
*/
readonly version: string
/**
* The name of the platform of the user's Telegram app.
*/
readonly platform:
| 'android'
| 'android_x'
| 'ios'
| 'macos'
| 'tdesktop'
| 'weba'
| 'webk'
| 'unigram'
| 'unknown'
/**
* The color scheme currently used in the Telegram app.
*
* Also available as the CSS variable `var(--tg-color-scheme)`.
*/
readonly colorScheme: ColorScheme
/**
* An object containing the current theme settings used in the Telegram app.
*/
readonly themeParams: ThemeParams
/**
* `Bot API 8.0+` *True*, if the Mini App is currently active. *False*, if the Mini
* App is minimized.
*/
readonly isActive: boolean
/**
* *True*, if the Web App is expanded to the maximum available height. *False*, if the
* Web App occupies part of the screen and can be expanded to the full height using
* the **expand()** method.
*/
readonly isExpanded: string
/**
* The current height of the visible area of the Web App. Also available in CSS as
* the variable `var(--tg-viewport-height)`.
*
* The application can display just the top part of the Web App, with its lower part
* remaining outside the screen area. From this position, the user can “pull” the Web
* App to its maximum height, while the bot can do the same by calling the
* **expand()** method. As the position of the Web App changes, the current height
* value of the visible area will be updated in real time.
*
* Please note that the refresh rate of this value is not sufficient to smoothly
* follow the lower border of the window. It should not be used to pin interface
* elements to the bottom of the visible area. It's more appropriate to use the value
* of the `viewportStableHeight` field for this purpose.
*/
readonly viewportHeight: number
/**
* The height of the visible area of the Web App in its last stable state. Also
* available in CSS as a variable `var(--tg-viewport-stable-height)`.
*
* The application can display just the top part of the Web App, with its lower part
* remaining outside the screen area. From this position, the user can “pull” the Web
* App to its maximum height, while the bot can do the same by calling the
* **expand()** method. Unlike the value of `viewportHeight`, the value of
* `viewportStableHeight` does not change as the position of the Web App changes with
* user gestures or during animations. The value of `viewportStableHeight` will be
* updated after all gestures and animations are completed and the Web App reaches its
* final size.
*
* *Note the event `viewportChanged` with the passed parameter `isStateStable=true`,
* which will allow you to track when the stable state of the height of the visible
* area changes.*
*/
readonly viewportStableHeight: number
/**
* Current header color in the `#RRGGBB` format.
*/
readonly headerColor: string
/**
* Current background color in the `#RRGGBB` format.
*/
readonly backgroundColor: string
/**
* Current bottom bar color in the `#RRGGBB` format.
*/
readonly bottomBarColor: string
/**
* *True*, if the confirmation dialog is enabled while the user is trying to close the
* Web App. *False*, if the confirmation dialog is disabled.
*/
readonly isClosingConfirmationEnabled: boolean
/**
* An object representing the device's safe area insets, accounting for system UI
* elements like notches or navigation bars.
*/
readonly safeAreaInset: SafeAreaInset
/**
* An object representing the safe area for displaying content within the app, free
* from overlapping Telegram UI elements.
*/
readonly contentSafeAreaInset: ContentSafeAreaInset
/**
* An object for controlling the back button which can be displayed in the header of
* the Web App in the Telegram interface.
*/
readonly BackButton: BackButton
/**
* An object for controlling the main button, which is displayed at the bottom of the
* Web App in the Telegram interface.
*/
readonly MainButton: BottomButton
/**
* An object for controlling the secondary button, which is displayed at the bottom of
* the Mini App in the Telegram interface.
*/
readonly SecondaryButton: BottomButton
/**
* An object for controlling the Settings item in the context menu of the Mini App in
* the Telegram interface.
*/
readonly SettingsButton: SettingsButton
/**
* An object for controlling haptic feedback.
*/
readonly HapticFeedback: HapticFeedback
/**
* An object for controlling cloud storage.
*/
readonly CloudStorage: CloudStorage
/**
* An object for controlling biometrics on the device.
*/
readonly BiometricManager: BiometricManager
/**
* An object for accessing accelerometer data on the device.
*/
readonly Accelerometer: Accelerometer
/**
* An object for accessing device orientation data on the device.
*/
readonly DeviceOrientation: DeviceOrientation
/**
* An object for accessing gyroscope data on the device.
*/
readonly Gyroscope: Gyroscope
/**
* An object for controlling location on the device
*/
readonly LocationManager: LocationManager
/**
* `Bot API 9.0+` An object for controlling local storage on the device
*/
readonly DeviceStorage: DeviceStorage
/**
* `Bot API 9.0+` An object for controlling secure storage on the device
*/
readonly SecureStorage: SecureStorage
/**
* Returns true if the user's app supports a version of the Bot API that is equal to
* or higher than the version passed as the parameter.
*/
isVersionAtLeast(version: string): boolean
/**
* `Bot API 6.1+` A method that sets the app header color in the `#RRGGBB` format. You
* can also use keywords *bg_color* and *secondary_bg_color*.
*
* Up to `Bot API 6.9` You can only pass *Telegram.WebApp.themeParams.bg_color* or
* *Telegram.WebApp.themeParams.secondary_bg_color* as a color or *bg_color*,
* *secondary_bg_color* keywords.
*/
setHeaderColor(color: string): void
/**
* `Bot API 6.1+` A method that sets the app background color in the `#RRGGBB` format
* or you can use keywords *bg_color*, *secondary_bg_color* instead.
*/
setBackgroundColor(color: string): void
/**
* `Bot API 7.10+` A method that sets the app's bottom bar color in the `#RRGGBB`
* format. You can also use the keywords *bg_color*, *secondary_bg_color* and
* *bottom_bar_bg_color*.
*/
setBottomBarColor(color: string): void
/**
* `Bot API 6.2+` A method that enables a confirmation dialog while the user is trying
* to close the Web App.
*/
enableClosingConfirmation(): void
/**
* `Bot API 6.2+` A method that disables the confirmation dialog while the user is
* trying to close the Web App.
*/
disableClosingConfirmation(): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the Mini App becomes active (e.g., opened from minimized
* state or selected among tabs).
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'activated', callback: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the Mini App becomes inactive (e.g., minimized or moved
* to an inactive tab).
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'deactivated', callback: () => void): void
/**
* A method that sets the app event handler.
*
* Event occurs whenever theme settings are changed in the user's Telegram app (including
* switching to night mode).
*
* *eventHandler* receives no parameters, new theme settings and color scheme can be
* received via *this.themeParams* and *this.colorScheme* respectively.
*/
onEvent(
eventType: 'themeChanged',
eventHandler: (this: { themeParams: ThemeParams; colorScheme: ColorScheme }) => void
): void
/**
* A method that sets the app event handler.
*
* Event occurs when the visible section of the Web App is changed.
*
* *eventHandler* receives an object with the single field *isStateStable*. If
* *isStateStable* is true, the resizing of the Web App is finished. If it is false,
* the resizing is ongoing (the user is expanding or collapsing the Web App or an
* animated object is playing). The current value of the visible section’s height is
* available in *this.viewportHeight*.
*/
onEvent(eventType: 'viewportChanged', eventHandler: ViewportChangedEventHandler): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the device's safe area insets change (e.g., due to
* orientation change or screen adjustments).
*
* *eventHandler* receives no parameters. The current inset values can be accessed via
* *this.safeAreaInset*.
*/
onEvent(eventType: 'safeAreaChanged', eventHandler: SafeAreaChangedEventHandler): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the safe area for content changes (e.g., due to
* orientation change or screen adjustments).
*
* *eventHandler* receives no parameters. The current inset values can be accessed via
* *this.contentSafeAreaInset*.
*/
onEvent(
eventType: 'contentSafeAreaChanged',
eventHandler: ContentSafeAreaChangedEventHandler
): void
/**
* A method that sets the app event handler.
*
* Event occurs when the main button is pressed.
*/
onEvent(eventType: 'mainButtonClicked', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 7.10+` Occurs when the secondary button is pressed.
*/
onEvent(eventType: 'secondaryButtonClicked', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.1+` Event occurrs when the back button is pressed.
*/
onEvent(eventType: 'backButtonClicked', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.1+` Event occurrs when the Settings item in context menu is pressed.
*/
onEvent(eventType: 'settingsButtonClicked', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.1+` Event occurrs when the opened invoice is closed.
*
* *eventHandler* receives an object with the two fields: *url* – invoice link
* provided and *status* – one of the invoice statuses:
* - **paid** – invoice was paid successfully,
* - **cancelled** – user closed this invoice without paying,
* - **failed** – user tried to pay, but the payment was failed,
* - **pending** – the payment is still processing. The bot will receive a service
* message about a successful payment when the payment is successfully paid.
*/
onEvent(eventType: 'invoiceClosed', eventHandler: InvoiceClosedEventHandler): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.2+` Event occurrs when the opened popup is closed.
*
* *eventHandler* receives an object with the single field *button_id* – the value of
* the field *id* of the pressed button. If no buttons were pressed, the field
* *button_id* will be *null*.
*/
onEvent(eventType: 'popupClosed', eventHandler: PopupClosedEventHandler): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.4+` Event occurs when the QR code scanner catches a code with text data.
*
* *eventHandler* receives an object with the single field *data* containing text data
* from the QR code.
*/
onEvent(eventType: 'qrTextReceived', eventHandler: QrTextReceivedEventHandler): void
/**
* `Bot API 7.7+` Occurs when the QR code scanner popup is closed by the user.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'scanQrPopupClosed', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.4+` Event occurrs when the `readTextFromClipboard` method is called.
*
* *eventHandler* receives an object with the single field *data* containing text data
* from the clipboard. If the clipboard contains non-text data, the field *data* will
* be an empty string. If the Web App has no access to the clipboard, the field *data*
* will be *null*.
*/
onEvent(
eventType: 'clipboardTextReceived',
eventHandler: ClipboardTextReceivedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.9+` Occurs when the write permission was requested.
*
* *eventHandler* receives an object with the single field *status* containing one of
* the statuses:
* - **allowed** – user granted write permission to the bot,
* - **cancelled** – user declined this request.
*/
onEvent(
eventType: 'writeAccessRequested',
eventHandler: (status: 'allowed' | 'cancelled') => void
): void
/**
* A method that sets the app event handler.
*
* `Bot API 6.9+` Occurrs when the user's phone number was requested.
*
* *eventHandler* receives an object with the single field status containing one of
* the statuses:
* - **sent** – user shared their phone number with the bot,
* - **cancelled** – user declined this request.
*/
onEvent(
eventType: 'contactRequested',
eventHandler: (status: 'sent' | 'cancelled') => void
): void
/**
* A method that sets the app event handler.
*
* `Bot API 7.2+` Occurs whenever `BiometricManager` object is changed
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'biometricManagerUpdated', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 7.2+` Occurs whenever biometric authentication was requested.
*
* *eventHandler* receives an object with the field *isAuthenticated* containing a
* boolean indicating whether the user was authenticated successfully. If
* *isAuthenticated* is true, the field *biometricToken() will contain the biometric
* token stored in secure storage on the device.
*/
onEvent(
eventType: 'biometricAuthRequested',
eventHandler: BiometricAuthRequestedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 7.2+` Occurs whenever the biometric token was updated.
*
* *eventHandler* receives an object with the single field *isUpdated*, containing a
* boolean indicating whether the token was updated.
*/
onEvent(
eventType: 'biometricTokenUpdated',
eventHandler: BiometricTokenUpdatedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs whenever the Mini App enters or exits fullscreen mode.
*
* *eventHandler* receives no parameters. The current fullscreen state can be checked
* via *this.isFullscreen*.
*/
onEvent(
eventType: 'fullscreenChanged',
eventHandler: FullscreenChangedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs if a request to enter fullscreen mode fails.
*
* *eventHandler* receives an object with the single field *error, describing the
* reason for the failure. Possible values for error are:
* - **UNSUPPORTED** – Fullscreen mode is not supported on this device or platform.
* - **ALREADY_FULLSCREEN** – The Mini App is already in fullscreen mode.
*/
onEvent(
eventType: 'fullscreenFailed',
eventHandler: FullscreenFailedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the Mini App is successfully added to the home screen.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'homeScreenAdded', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs after checking the home screen status.
*
* *eventHandler* receives an object with the field *status*, which is a string
* indicating the current home screen status. Possible values for *status* are:
* - **unsupported** – the feature is not supported, and it is not possible to add the
* icon to the home screen,
* - **unknown** – the feature is supported, and the icon can be added, but it is not
* possible to determine if the icon has already been added,
* - **added** – the icon has already been added to the home screen,
* - **missed** – the icon has not been added to the home screen.
*/
onEvent(
eventType: 'homeScreenChecked',
eventHandler: HomeScreenCheckedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when accelerometer tracking has started successfully.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'accelerometerStarted', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when accelerometer tracking has stopped.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'accelerometerStopped', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0`+ Occurs with the specified frequency after calling the `start`
* method, sending the current accelerometer data.
*
* *eventHandler* receives no parameters, the current acceleration values can be
* received via *this.x*, *this.y* and *this.z* respectively.
*/
onEvent(
eventType: 'accelerometerChanged',
eventHandler: AccelerometerChangedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs if a request to start accelerometer tracking fails.
*
* *eventHandler* receives an object with the single field *error*, describing the
* reason for the failure. Possible values for *error* are:
* - **UNSUPPORTED** – Accelerometer tracking is not supported on this device or
* platform.
*/
onEvent(
eventType: 'accelerometerFailed',
eventHandler: AccelerometerFailedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when device orientation tracking has started successfully.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'deviceOrientationStarted', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when device orientation tracking has stopped.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'deviceOrientationStopped', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs with the specified frequency after calling the `start`
* method, sending the current orientation data.
*
* *eventHandler* receives no parameters, the current device orientation values can
* be received via *this.alpha*, *this.beta* and *this.gamma* respectively.
*/
onEvent(
eventType: 'deviceOrientationChanged',
eventHandler: DeviceOrientationChangedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs if a request to start device orientation tracking fails.
*
* *eventHandler* receives an object with the single field *error*, describing the
* reason for the failure. Possible values for *error* are:
* - **UNSUPPORTED** – Device orientation tracking is not supported on this device or
* platform.
*/
onEvent(
eventType: 'deviceOrientationFailed',
eventHandler: DeviceOrientationFailedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when gyroscope tracking has started successfully.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'gyroscopeStarted', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when gyroscope tracking has stopped.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'gyroscopeStopped', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs with the specified frequency after calling the `start`
* method, sending the current gyroscope data.
*
* *eventHandler* receives no parameters, the current rotation rates can be received
* via *this.x*, *this.y* and *this.z* respectively.
*/
onEvent(
eventType: 'gyroscopeChanged',
eventHandler: GyroscopeChangedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs if a request to start gyroscope tracking fails.
*
* *eventHandler* receives an object with the single field *error*, describing the
* reason for the failure. Possible values for *error* are:
* - **UNSUPPORTED** – Gyroscope tracking is not supported on this device or platform.
*/
onEvent(eventType: 'gyroscopeFailed', eventHandler: GyroscopeFailedEventHandler): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs whenever LocationManager object is changed.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'locationManagerUpdated', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when location data is requested.
*
* *eventHandler* receives an object with the single field *locationData* of type
* LocationData, containing the current location information.
*/
onEvent(
eventType: 'locationRequested',
eventHandler: LocationRequestedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the message is successfully shared by the user.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'shareMessageSent', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs if sharing the message fails.
*
* *eventHandler* receives an object with the single field *error*, describing the
* reason for the failure. Possible values for *error* are:
* - **UNSUPPORTED** – The feature is not supported by the client.
* - **MESSAGE_EXPIRED** – The message could not be retrieved because it has expired.
* - **MESSAGE_SEND_FAILED** – An error occurred while attempting to send the message.
* - **USER_DECLINED** – The user closed the dialog without sharing the message.
* - **UNKNOWN_ERROR** – An unknown error occurred.
*/
onEvent(
eventType: 'shareMessageFailed',
eventHandler: ShareMessageFailedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the emoji status is successfully set.
*
* *eventHandler* receives no parameters.
*/
onEvent(eventType: 'emojiStatusSet', eventHandler: () => void): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs if setting the emoji status fails.
*
* *eventHandler* receives an object with the single field *error*, describing the
* reason for the failure. Possible values for *error* are:
* - **UNSUPPORTED** – The feature is not supported by the client.
* - **SUGGESTED_EMOJI_INVALID** – One or more emoji identifiers are invalid.
* - **DURATION_INVALID** – The specified duration is invalid.
* - **USER_DECLINED** – The user closed the dialog without setting a status.
* - **SERVER_ERROR** – A server error occurred when attempting to set the status.
* - **UNKNOWN_ERROR** – An unknown error occurred.
*/
onEvent(
eventType: 'emojiStatusFailed',
eventHandler: EmojiStatusFailedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the write permission was requested.
*
* *eventHandler* receives an object with the single field *status* containing one of
* the statuses:
* - **allowed** – user granted emoji status permission to the bot,
* - **cancelled** – user declined this request.
*/
onEvent(
eventType: 'emojiStatusAccessRequested',
eventHandler: EmojiStatusAccessRequestedEventHandler
): void
/**
* A method that sets the app event handler.
*
* `Bot API 8.0+` Occurs when the user responds to the file download request.
*
* *eventHandler* receives an object with the single field *status* containing one of
* the statuses:
* - **downloading** – the file download has started,
* - **cancelled** – user declined this request.
*/
onEvent(
eventType: 'fileDownloadRequested',
eventHandler: FileDownloadRequestedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType:
| 'activated'
| 'deactivated'
| 'themeChanged'
| 'mainButtonClicked'
| 'secondaryButtonClicked'
| 'backButtonClicked'
| 'settingsButtonClicked'
| 'biometricManagerUpdated'
| 'homeScreenAdded'
| 'accelerometerStarted'
| 'accelerometerStopped'
| 'deviceOrientationStarted'
| 'deviceOrientationStopped'
| 'gyroscopeStarted'
| 'gyroscopeStopped'
| 'locationManagerUpdated'
| 'shareMessageSent'
| 'emojiStatusSet',
eventHandler: () => void
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'viewportChanged',
eventHandler: ViewportChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'safeAreaChanged',
eventHandler: SafeAreaChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'contentSafeAreaChanged',
eventHandler: ContentSafeAreaChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(eventType: 'invoiceClosed', eventHandler: InvoiceClosedEventHandler): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(eventType: 'popupClosed', eventHandler: PopupClosedEventHandler): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(eventType: 'qrTextReceived', eventHandler: QrTextReceivedEventHandler): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'clipboardTextReceived',
eventHandler: ClipboardTextReceivedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'biometricAuthRequested',
eventHandler: BiometricAuthRequestedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'biometricTokenUpdated',
eventHandler: BiometricTokenUpdatedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'fullscreenChanged',
eventHandler: FullscreenChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'fullscreenFailed',
eventHandler: FullscreenFailedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'homeScreenChecked',
eventHandler: HomeScreenCheckedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'accelerometerChanged',
eventHandler: AccelerometerChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'accelerometerFailed',
eventHandler: AccelerometerFailedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'deviceOrientationChanged',
eventHandler: DeviceOrientationChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'deviceOrientationFailed',
eventHandler: DeviceOrientationFailedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'gyroscopeChanged',
eventHandler: GyroscopeChangedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'gyroscopeFailed',
eventHandler: GyroscopeFailedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'locationRequested',
eventHandler: LocationRequestedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'shareMessageFailed',
eventHandler: ShareMessageFailedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'emojiStatusFailed',
eventHandler: EmojiStatusFailedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'emojiStatusAccessRequested',
eventHandler: EmojiStatusAccessRequestedEventHandler
): void
/**
* A method that deletes a previously set event handler.
*/
offEvent(
eventType: 'fileDownloadRequested',
eventHandler: FileDownloadRequestedEventHandler
): void
/**
* A method used to send data to the bot. When this method is called, a service
* message is sent to the bot containing the data *data* of the length up to 4096
* bytes, and the Web App is closed. See the field *web_app_data* in the class
* Message.
*
* *This method is only available for Web Apps launched via a Keyboard button.*
*/
sendData(data: string): void
/**
* `Bot API 6.7+` A method that inserts the bot's username and the specified inline
* *query* in the current chat's input field. Query may be empty, in which case only
* the bot's username will be inserted. If an optional *choose_chat_types* parameter
* was passed, the client prompts the user to choose a specific chat, then opens that
* chat and inserts the bot's username and the specified inline query in the input
* field. You can specify which types of chats the user will be able to choose from.
*/
switchInlineQuery(
query: string,
choose_chat_types?: ('users' | 'bots' | 'groups' | 'channels')[]
): void
/**
* A method that opens a link in an external browser. The Web App will *not* be
* closed.
*
* `Bot API 6.4+` If the optional *options* parameter is passed with the field
* *try_instant_view=true*, the link will be opened in Instant View mode if possible.
*
* *Note that this method can be called only in response to user interaction with the
* Web App interface (e.g. a click inside the Web App or on the main button)*
*/
openLink(url: string, options?: { try_instant_view: boolean }): void
/**
* A method that opens a telegram link inside Telegram app. The Web App *will* be
* closed.
*/
openTelegramLink(url: string): void
/**
* `Bot API 6.1+` A method that opens an invoice using the link *url*. The Web App
* will receive the event *invoiceClosed* when the invoice is closed. If an optional
* *callback* parameter was passed, the *callback* function will be called and the
* invoice status will be passed as the first argument.
*/
openInvoice(
url: string,
callback?: (status: 'paid' | 'cancelled' | 'failed' | 'pending') => void
): void
/**
* `Bot API 7.8+` A method that opens the native story editor with the media specified
* in the *media_url* parameter as an HTTPS URL. An optional *params* argument of the
* type StoryShareParams describes additional sharing settings.
*/
shareToStory(media_url: string, params?: StoryShareParams): void
/**
* `Bot API 8.0+` A method that opens a dialog allowing the user to share a message
* provided by the bot. If an optional *callback* parameter is provided, the
* *callback* function will be called with a boolean as the first argument, indicating
* whether the message was successfully sent. The message id passed to this method
* must belong to a PreparedInlineMessage previously obtained via the Bot API method
* savePreparedInlineMessage.
*/
shareMessage(message_id: string, callback?: (sent: boolean) => void): void
/**
* `Bot API 8.0+` A method that opens a dialog allowing the user to set the specified
* custom emoji as their status. An optional *params* argument of type
* EmojiStatusParams specifies additional settings, such as duration. If an optional
* *callback* parameter is provided, the callback function will be called with a
* boolean as the first argument, indicating whether the status was set.
*
* *Note: this method opens a native dialog and cannot be used to set the emoji status
* without manual user interaction. For fully programmatic changes, you should instead
* use the Bot API method setUserEmojiStatus after obtaining authorization to do so
* via the Mini App method requestEmojiStatusAccess.*
*/
setEmojiStatus(
custom_emoji_id: string,
params?: EmojiStatusParams,
callback?: (set: boolean) => void
): void
/**
* `Bot API 8.0+` A method that shows a native popup requesting permission for the bot
* to manage user's emoji status. If an optional *callback* parameter was passed, the
* *callback* function will be called when the popup is closed and the first argument
* will be a boolean indicating whether the user granted this access.
*/
requestEmojiStatusAccess(callback?: (accessGranted: boolean) => void): void
/**
* `Bot API 8.0+` A method that displays a native popup prompting the user to download
* a file specified by the *params* argument of type DownloadFileParams. If an
* optional *callback* parameter is provided, the *callback* function will be called
* when the popup is closed, with the first argument as a boolean indicating whether
* the user accepted the download request.
*/
downloadFile(params: DownloadFileParams, callback?: (accepted: boolean) => void): void
/**
* `Bot API 6.2+` A method that shows a native popup described by the *params*
* argument of the type PopupParams. The Web App will receive the event *popupClosed*
* when the popup is closed. If an optional *callback* parameter was passed, the
* *callback* function will be called and the field *id* of the pressed button will be
* passed as the first argument.
*/
showPopup(params: PopupParams, callback?: (id: string) => void): void
/**
* `Bot API 6.2+` A method that shows *message* in a simple alert with a 'Close'
* button. If an optional *callback* parameter was passed, the *callback* function
* will be called when the popup is closed.
*/
showAlert(message: string, callback?: () => void): void
/**
* `Bot API 6.2+` A method that shows *message* in a simple confirmation window with
* 'OK' and 'Cancel' buttons. If an optional *callback* parameter was passed, the
* *callback* function will be called when the popup is closed and the first argument
* will be a boolean indicating whether the user pressed the 'OK' button.
*/
showConfirm(message: string, callback?: (okPressed: boolean) => void): void
/**
* `Bot API 6.4+` A method that shows a native popup for scanning a QR code described
* by the *params* argument of the type ScanQrPopupParams. The Mini App will receive
* the event *qrTextReceived* every time the scanner catches a code with text data. If
* an optional *callback* parameter was passed, the *callback* function will be called
* and the text from the QR code will be passed as the first argument. Returning
* *true* inside this callback function causes the popup to be closed. Starting from
* `Bot API 7.7`, the Mini App will receive the *scanQrPopupClosed* event if the user
* closes the native popup for scanning a QR code.
*/
showScanQrPopup(params: ScanQrPopupParams, callback?: (data: string) => boolean): void
/**
* `Bot API 6.4+` A method that closes the native popup for scanning a QR code opened
* with the *showScanQrPopup* method. Run it if you received valid data in the event
* *qrTextReceived*.
*/
closeScanQrPopup(): void
/**
* `Bot API 6.4+` A method that requests text from the clipboard. The Web App will
* receive the event *clipboardTextReceived*. If an optional *callback* parameter was
* passed, the *callback* function will be called and the text from the clipboard will
* be passed as the first argument.
*
* *Note: this method can be called only for Web Apps launched from the attachment
* menu and only in response to a user interaction with the Web App interface (e.g. a
* click inside the Web App or on the main button).*
*/
readTextFromClipboard(callback?: (text: string) => void): void
/**
* `Bot API 6.9+` A method that shows a native popup requesting permission for the bot
* to send messages to the user. If an optional *callback* parameter was passed, the
* *callback* function will be called when the popup is closed and the first argument
* will be a boolean indicating whether the user granted this access.
*/
requestWriteAccess(callback?: (accessGranted: boolean) => void): void
/**
* `Bot API 6.9+` A method that shows a native popup prompting the user for their
* phone number. If an optional *callback* parameter was passed, the *callback*
* function will be called when the popup is closed and the first argument will be a
* boolean indicating whether the user shared its phone number.
*/
requestContact(callback?: (phoneNumberShared: boolean) => void): void
/**
* A method that informs the Telegram app that the Web App is ready to be displayed.
*
* It is recommended to call this method as early as possible, as soon as all
* essential interface elements are loaded. Once this method is called, the loading
* placeholder is hidden and the Web App is shown.
*
* If the method is not called, the placeholder will be hidden only when the page is
* fully loaded.
*/
ready(): boolean
/**
* A method that expands the Web App to the maximum available height. To find out if
* the Web App is expanded to the maximum height, refer to the value of the
* *Telegram.WebApp.isExpanded* parameter
*/
expand(): void
/**
* A method that closes the Web App.
*/
close(): void
/**
* *True*, if the Mini App is currently being displayed in fullscreen mode.
*/
readonly isFullscreen: boolean
/**
* *True*, if the Mini App’s orientation is currently locked. *False*, if orientation
* changes freely based on the device’s rotation.
*/
readonly isOrientationLocked: boolean
/**
* *True*, if vertical swipes to close or minimize the Mini App are enabled. *False*,
* if vertical swipes to close or minimize the Mini App are disabled. In any case, the
* user will still be able to minimize and close the Mini App by swiping the Mini
* App's header.
*/
readonly isVerticalSwipesEnabled: boolean
/**
* `Bot API 7.7+` A method that enables vertical swipes to close or minimize the Mini
* App. For user convenience, it is recommended to always enable swipes unless they
* conflict with the Mini App's own gestures.
*/
enableVerticalSwipes(): void
/**
* `Bot API 7.7+` A method that disables vertical swipes to close or minimize the Mini
* App. This method is useful if your Mini App uses swipe gestures that may conflict
* with the gestures for minimizing and closing the app.
*/
disableVerticalSwipes(): void
/**
* `Bot API 8.0+` A method that requests opening the Mini App in fullscreen mode.
* Although the header is transparent in fullscreen mode, it is recommended that the
* Mini App sets the header color using the *setHeaderColor* method. This color helps
* determine a contrasting color for the status bar and other UI controls.
*/
requestFullscreen(): void
/**
* `Bot API 8.0+` A method that requests exiting fullscreen mode.
*/
exitFullscreen(): void
/**
* `Bot API 8.0+` A method that locks the Mini App’s orientation to its current mode
* (either portrait or landscape). Once locked, the orientation remains fixed,
* regardless of device rotation. This is useful if a stable orientation is needed
* during specific interactions.
*/
lockOrientation(): void
/**
* `Bot API 8.0+` A method that unlocks the Mini App’s orientation, allowing it to
* follow the device's rotation freely. Use this to restore automatic orientation
* adjustments based on the device orientation.
*/
unlockOrientation(): void
/**
* `Bot API 8.0+` A method that prompts the user to add the Mini App to the home
* screen. After successfully adding the icon, the `homeScreenAdded` event will be
* triggered if supported by the device. Note that if the device cannot determine the
* installation status, the event may not be received even if the icon has been added.
*/
addToHomeScreen(): void
/**
* `Bot API 8.0+` A method that checks if adding to the home screen is supported and
* if the Mini App has already been added. If an optional *callback* parameter is
* provided, the callback function will be called with a single argument *status*,
* which is a string indicating the home screen status. Possible values for *status*
* are:
* - **unsupported** – the feature is not supported, and it is not possible to add the
* icon to the home screen,
* - **unknown** – the feature is supported, and the icon can be added, but it is not
* possible to determine if the icon has already been added,
* - **added** – the icon has already been added to the home screen,
* - **missed** – the icon has not been added to the home screen.
*/
checkHomeScreenStatus(
callback?: (status: 'unsupported' | 'unknown' | 'added' | 'missed') => void
): void
/**
* `Bot API 9.1+` A method that hides the on-screen keyboard, if it is currently
* visible. Does nothing if the keyboard is not active.
*/
hideKeyboard(): void
}
/**
* Web Apps can adjust the appearance of the interface to match the Telegram user's app
* in real time. This object contains the user's current theme settings
*/
interface ThemeParams {
/**
* Background color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-bg-color)`.
*/
bg_color?: string
/**
* Main text color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-text-color)`.
*/
text_color: string
/**
* Hint text color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-hint-color)`.
*/
hint_color?: string
/**
* Link color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-link-color)`.
*/
link_color?: string
/**
* Button color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-button-color)`.
*/
button_color?: string
/**
* Button text color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-button-text-color)`.
*/
button_text_color?: string
/**
* `Bot API 6.1+` Secondary background color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-secondary-bg-color)`.
*/
secondary_bg_color?: string
/**
* `Bot API 7.0+` Header background color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-header-bg-color)`.
*/
header_bg_color?: string
/**
* `Bot API 7.10+` Bottom background color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-bottom-bar-bg-color)`.
*/
bottom_bar_bg_color?: string
/**
* `Bot API 7.0+` Accent text color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-accent-text-color)`.
*/
accent_text_color?: string
/**
* `Bot API 7.0+` Background color for the section in the `#RRGGBB` format. It is
* recommended to use this in conjunction with *secondary_bg_color*.
*
* Also available as the CSS variable `var(--tg-theme-section-bg-color)`.
*/
section_bg_color?: string
/**
* `Bot API 7.0+` Header text color for the section in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-section-header-text-color)`.
*/
section_header_text_color?: `#${string}`
/**
* `Bot API 7.6+` Section separator color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-section-separator-color)`.
*/
section_separator_color?: `#${string}`
/**
* `Bot API 7.0+` Subtitle text color in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-subtitle-text-color)`.
*/
subtitle_text_color?: string
/**
* `Bot API 7.0+` Text color for destructive actions in the `#RRGGBB` format.
*
* Also available as the CSS variable `var(--tg-theme-destructive-text-color)`.