Once the script is connected, a window.OpenWeb3.WebApp object will become available with the following fields:
WebApp
| Field | Type | Description |
|---|---|---|
| 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. |
WebAppInitData
| Parameter | Type | Description |
|---|---|---|
| auth_date | Number | The date the initialization data was created. Is a number representing a Unix timestamp. |
| hash | String | Initialization data signature. |
| start_param | String | Optional. The value of the startattach or startapp query parameter specified in the link. It is returned only for Mini Apps opened through the attachment menu. |
| user | WebAppUser | Optional. An object containing data about the current user. |
WebAppUser
| Parameter | Type | Description |
|---|---|---|
| id | number | A unique identifier for the user or bot or OpenWeb3 Id. |
| is_bot | Boolean | Optional. True, if this user is a bot. Returns in the receiver field only. |
| first_name | String | First name of the user or bot. |
| last_name | String | Optional. Last name of the user or bot. |
| username | String | Optional. Username of the user or bot. |
| language_code | String | Optional. IETF language tag of the user's language. Returns in user field only. |
| photo_url | String | Optional. URL of the user’s profile photo. The photo can be in .jpeg or .svg formats. Only returned for Mini Apps launched from the attachment menu. |
BackButton
| Field | Type | Description |
|---|---|---|
| isVisible | Boolean | Shows whether the button is visible. Set to false by default. |
| onClick(callback) | Function | A method that sets the button press event handler. An alias for OpenWeb3.WebApp.onEvent('backButtonClicked', callback) |
| offClick(callback) | Function | A method that removes the button press event handler. An alias for OpenWeb3.WebApp.offEvent('backButtonClicked', callback) |
| show() | Function | A method to make the button active and visible. |
| hide() | Function | A method to hide the button. |
MainButton
| Field | Type | Description |
|---|---|---|
| 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. |
BiometricManager
| Field | Type | Description |
|---|---|---|
| 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) |