API Reference

initData

String

A string with raw data transferred to the Mini App, convenient for validating data.
WARNING: Validate data from this field before using it on the bot's server.

initDataUnsafe

WebAppInitData

An object with input data transferred to the Mini 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.

version

String

The version of the Bot API available in the user's client app.

platform

String

The name of the platform of the user's client app.

colorScheme

ThemeParams

An object containing the current theme settings used in the client app.

isExpanded

Boolean

True, if the Mini App is expanded to the maximum available height. False, if the Mini App occupies part of the screen and can be expanded to the full height using the expand() method.

viewportHeight

Float

The current height of the visible area of the Mini App. Also available in CSS as the variable var(--tg-viewport-height).

The application can display just the top part of the Mini App, with its lower part remaining outside the screen area. From this position, the user can “pull” the Mini App to its maximum height, while the bot can do the same by calling the expand() method. As the position of the Mini 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.

viewportStableHeight

Float

The height of the visible area of the Mini App in its last stable state. Also available in CSS as a variable var(--dj-viewport-stable-height).

The application can display just the top part of the Mini App, with its lower part remaining outside the screen area. From this position, the user can “pull” the Mini 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 Mini App changes with user gestures or during animations. The value of viewportStableHeight will be updated after all gestures and animations are completed and the Mini 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.

headerColor

String

Current header color in the #RRGGBB format.

backgroundColor

String

Current background color in the #RRGGBB format.

isClosingConfirmationEnabled

Boolean

True, if the confirmation dialog is enabled while the user is trying to close the Mini App. False, if the confirmation dialog is disabled.

BackButton

BackButton

An object for controlling the back button which can be displayed in the header of the Mini App in the client app interface.

MainButton

MainButton

An object for controlling the main button, which is displayed at the bottom of the Mini App in the client app interface.

HapticFeedback

HapticFeedback

An object for controlling haptic feedback.

BiometricManager

BiometricManager

An object for controlling biometrics on the device.

setHeaderColor(color)

Function

You can pass OpenWeb3.WebApp.themeParams.bg_color or OpenWeb3.WebApp.themeParams.secondary_bg_color as a color or bg_color, secondary_bg_color keywords.

setBackgroundColor(color)

Function

A method that sets the app background color in the #RRGGBB format. You can also use keywords bg_color and secondary_bg_color.

enableClosingConfirmation()

Function

A method that enables a confirmation dialog while the user is trying to close the Mini App.

disableClosingConfirmation()

Function

A method that disables the confirmation dialog while the user is trying to close the Mini App.

onEvent(eventType, eventHandler)

Function

A method that sets the app event handler. Check the list of available events.

offEvent(eventType, eventHandler)

Function

A method that deletes a previously set event handler.

sendData(data)

Function

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 Mini App is closed. See the field web_app_data in the class Message.

This method is only available for Mini Apps launched via a Keyboard button.

switchInlineQuery(query[, choose_chat_types])

Function

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. It can be one or more of the following types: users, bots, groups, channels.

openLink(url[, options])

Function

A method that opens a link in an external browser. The Mini 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 Mini App interface (e.g. a click inside the Mini App or on the main button)

openWebAppLink(url)

Function

A method that opens a new web app link inside the your app. The Mini App will not be closed after this method is called.

The Mini App will be closed after this method is called.

showPopup(params[, callback])

Function

A method that shows a native popup described by the params argument of the type PopupParams. The Mini 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.

showAlert(message[, callback])

Function

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.

showConfirm(message[, callback])

Function

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.

showScanQrPopup(params[, callback])

Function

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.

closeScanQrPopup()

Function

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.

readTextFromClipboard([callback])

Function

A method that requests text from the clipboard. The Mini 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 Mini Apps launched from the attachment menu and only in response to a user interaction with the Mini App interface (e.g. a click inside the Mini App or on the main button).

requestWriteAccess([callback])

Function

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.

requestContact([callback])

Function

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.

ready()

Function

A method that informs your app that the Mini 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 Mini App is shown.
If the method is not called, the placeholder will be hidden only when the page is fully loaded.

expand()

Function

A method that expands the Mini App to the maximum available height. To find out if the Mini App is expanded to the maximum height, refer to the value of the OpenWeb3.WebApp.isExpanded parameter

isVerticalSwipesEnabled

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.

enableVerticalSwipes()

Function

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.

disableVerticalSwipes()

Function

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.

isActionBarVisible

Boolean

isActionBarVisible is a boolean attribute that indicates whether the action bar is currently visible in the Mini App's user interface. If the value is true, it means the action bar is visible, and if the value is false, it means the action bar is hidden.

enableActionBar()

Function

enableActionBar() is a method that allows the Mini App to enable the action bar in its user interface. The action bar typically contains important controls and navigation elements for the Mini App. By calling this method, the Mini App ensures that the action bar is displayed to the user.

disableActionBar()

Function

disableActionBar() is a method that allows the Mini App to disable the action bar in its user interface. By calling this method, the Mini App hides the action bar from the user, removing any associated controls and navigation elements.

isFullScreenEnabled

Boolean

isFullScreenEnabled is a boolean attribute that indicates whether the Mini App is currently in full-screen mode. If the value is true, it means the Mini App is displayed in full-screen mode, occupying the entire screen. If the value is false, it means the Mini App is not in full-screen mode and may have a different display area or size.

enableFullScreen()

Function

enableFullScreen() is a method that allows the Mini App to enter full-screen mode, expanding its display to occupy the entire screen. By calling this method, the Mini App provides a more immersive experience for the user, removing any surrounding elements or distractions from the screen.

disableFullScreen()

Function

disableFullScreen() is a method that allows the Mini App to exit full-screen mode and return to its default display mode. By calling this method, the Mini App restores its original display area and may show surrounding elements or user interface components.

text

String

Current button text. Set to CONTINUE by default.

color

String

Current button color. Set to themeParams.button_color by default.

textColor

String

Current button text color. Set to themeParams.button_text_color by default.

isVisible

Boolean

Shows whether the button is visible. Set to false by default.

isActive

Boolean

Shows whether the button is active. Set to true by default.

isProgressVisible

Boolean

Readonly. Shows whether the button is displaying a loading indicator.

setText(text)

Function

A method to set the button text.

onClick(callback)

Function

A method that sets the button press event handler. An alias for OpenWeb3.WebApp.onEvent('mainButtonClicked', callback)

offClick(callback)

Function

A method that removes the button press event handler. An alias for OpenWeb3.WebApp.offEvent('mainButtonClicked', callback)

show()

Function

A method to make the button visible.
Note that opening the Mini App from the attachment menu hides the main button until the user interacts with the Mini App interface.

hide()

Function

A method to hide the button.

hide()

Function

A method to enable the button.

disable()

Function

A method to disable the button.

showProgress(leaveActive)

Function

A method to show a loading indicator on the button.
It is recommended to display loading progress if the action tied to the button may take a long time. By default, the button is disabled while the action is in progress. If the parameter leaveActive=true is passed, the button remains enabled.

hideProgress()

Function

A method to hide the loading indicator.

setParams(params)

Function

A method to set the button parameters. The params parameter is an object containing one or several fields that need to be changed:
text - button text;
color - button color;
text_color - button text color;
is_active - enable the button;
is_visible - show the button.

isInited

Boolean

Shows whether biometrics object is initialized.

isBiometricAvailable

Boolean

A Shows whether biometrics is available on the current device.

biometricType

String

The type of biometrics currently available on the device. Can be one of these values:

• finger, fingerprint-based biometrics,
• face, face-based biometrics,
• unknown, biometrics of an unknown type.

isAccessRequested

Function

Shows whether permission to use biometrics has been requested.

isAccessGranted

Function

Shows whether permission to use biometrics has been granted.

isBiometricTokenSaved

Boolean

Shows whether the token is saved in secure storage on the device.

deviceId

String

A unique device identifier that can be used to match the token to the device.

init([callback])

Function

A method that initializes the BiometricManager object. It should be called before the object's first use. If an optional callback parameter was passed, the callback function will be called when the object is initialized.

requestAccess(params[, callback])

Function

A method that requests permission to use biometrics according to the params argument of type BiometricRequestAccessParams. If an optional callback parameter was passed, the callback function will be called and the first argument will be a boolean indicating whether the user granted access.

authenticate(params[, callback])

Function

A method that authenticates the user using biometrics according to the params argument of type BiometricAuthenticateParams. If an optional callback parameter was passed, the callback function will be called and the first argument will be a boolean indicating whether the user authenticated successfully. If so, the second argument will be a biometric token.

updateBiometricToken(token, [callback])

Function

A method that updates the biometric token in secure storage on the device. To remove the token, pass an empty string. If an optional callback parameter was passed, the callback function will be called and the first argument will be a boolean indicating whether the token was updated.

openSettings()

Function

A method that opens the biometric access settings for bots. Useful when you need to request biometrics access to users who haven't granted it yet.

Note that this method can be called only in response to user interaction with the Mini App interface (e.g. a click inside the Mini App or on the main button)