Telegram Mini Apps
With Mini Apps developers can use JavaScript to create infinitely flexible interfaces that can be launched right inside Telegram — and can completely replace any website.
Like bots, Mini Apps support seamless authorization, integrated payments via 20 payment providers (with Google Pay and Apple Pay out of the box), delivering tailored push notifications to users, and much more.
To see a Mini App in action, try our sample @DurgerKingBot.
Recent changes
December 29, 2023
Bot API 7.0
- Added the field SettingsButton to the class WebApp.
- Added the fields header_bg_color, accent_text_color, section_bg_color, section_header_text_color, subtitle_text_color, destructive_text_color to the class ThemeParams.
- Mini Apps no longer close when the method WebApp.openTelegramLink is called.
September 22, 2023
Bot API 6.9
- Added the field CloudStorage to the class WebApp.
- Added the methods requestWriteAccess and requestContact to the class WebApp.
- Added the fields added_to_attachment_menu and allows_write_to_pm to the class WebAppUser.
- Added the events writeAccessRequested and contactRequested.
- Added the ability to set any header color using the setHeaderColor method.
April 21, 2023
Bot API 6.7
- Added support for launching Mini Apps from inline query results and from a direct link.
- Added the method switchInlineQuery to the class WebApp.
December 30, 2022
Bot API 6.4
- Added the field platform, the optional parameter options to the method openLink and the methods showScanQrPopup, closeScanQrPopup, readTextFromClipboard to the class WebApp.
- Added the events qrTextReceived, clipboardTextReceived.
August 12, 2022
Bot API 6.2
- Added the field isClosingConfirmationEnabled and the methods enableClosingConfirmation, disableClosingConfirmation, showPopup, showAlert, showConfirm to the class WebApp.
- Added the field is_premium to the class WebAppUser.
- Added the event popupClosed.
June 20, 2022
Bot API 6.1
- Added the ability to use bots added to the attachment menu in group, supergroup and channel chats.
- Added support for t.me links that can be used to select the chat in which the attachment menu with the bot will be opened.
- Added the fields version, headerColor, backgroundColor, BackButton, HapticFeedback and the methods isVersionAtLeast, setHeaderColor, setBackgroundColor, openLink, openTelegramLink, openInvoice to the class WebApp.
- Added the field secondary_bg_color to the class ThemeParams.
- Added the method offClick to the class MainButton.
- Added the fields chat, can_send_after to the class WebAppInitData.
- Added the events backButtonClicked, settingsButtonClicked, invoiceClosed.
Designing Mini Apps
Color Schemes
Mini Apps always receive data about the user's current color theme in real time, so you can adjust the appearance of your interfaces to match it. For example, when users switch between Day and Night modes or use various custom themes.
Design Guidelines
Telegram apps are known for being snappy, smooth and following a consistent cross-platform design. Your Mini App should ideally reflect these principles.
- All elements should be responsive and designed with a mobile-first approach.
- Interactive elements should mimic the style, behavior and intent of UI components that already exist.
- All included animations should be smooth, ideally 60fps.
- All inputs and images should contain labels for accessibility purposes.
- The app should deliver a seamless experience by monitoring the dynamic theme-based colors provided by the API and using them accordingly.
Implementing Mini Apps
Telegram currently supports six different ways of launching Mini Apps: from a keyboard button, from an inline button, from the bot menu button, via inline mode, from a direct link – and even from the attachment menu.
Keyboard Button Mini Apps
TL;DR: Mini Apps launched from a web_app type keyboard button can send data back to the bot in a service message using Telegram.WebApp.sendData. This makes it possible for the bot to produce a response without communicating with any external servers.
Users can interact with bots using custom keyboards, buttons under bot messages, as well as by sending freeform text messages or any of the attachment types supported by Telegram: photos and videos, files, locations, contacts and polls. For even more flexibility, bots can utilize the full power of HTML5 to create user-friendly input interfaces.
You can send a web_app type KeyboardButton that opens a Mini App from the specified URL.
To transmit data from the user back to the bot, the Mini App can call the Telegram.WebApp.sendData method. Data will be transmitted to the bot as a String in a service message. The bot can continue communicating with the user after receiving it.
Good for:
- Сustom data input interfaces (a personalized calendar for selecting dates; selecting data from a list with advanced search options; a randomizer that lets the user “spin a wheel” and chooses one of the available options, etc.)
- Reusable components that do not depend on a particular bot.
Inline Button Mini Apps
TL;DR: For more interactive Mini Apps like @DurgerKingBot, use a web_app type Inline KeyboardButton, which gets basic user information and can be used to send a message on behalf of the user to the chat with the bot.
If receiving text data alone is insufficient or you need a more advanced and personalized interface, you can open a Mini App using a web_app type Inline KeyboardButton.
From the button, a Mini App will open with the URL specified in the button. In addition to the user's theme settings, it will receive basic user information (ID, name, username, language_code) and a unique identifier for the session, query_id, which allows messages on behalf of the user to be sent back to the bot.
The bot can call the Bot API method answerWebAppQuery to send an inline message from the user back to the bot and close the Mini App. After receiving the message, the bot can continue communicating with the user.
Good for:
- Fully-fledged web services and integrations of any kind.
- The use cases are effectively unlimited.
Launching Mini Apps from the Menu Button
TL;DR: Mini Apps can be launched from a customized menu button. This simply offers a quicker way to access the app and is otherwise identical to launching a mini app from an inline button.
By default, chats with bots always show a convenient menu button that provides quick access to all listed commands. With Bot API 6.0, this button can be used to launch a Mini App instead.
To configure the menu button, you must specify the text it should show and the Mini App URL. There are two ways to set these parameters:
- To customize the button for all users, use @BotFather (the
/setmenubuttoncommand or Bot Settings > Menu Button). - To customize the button for both all users and specific users, use the setChatMenuButton method in the Bot API. For example, change the button text according to the user's language, or show links to different Mini Apps based on a user's settings in your bot.
Apart from this, Mini Apps opened via the menu button work in the exact same way as when using inline buttons.
@DurgerKingBot allows launching its Mini App both from an inline button and from the menu button.
Inline Mode Mini Apps
TL;DR: Mini Apps launched via web_app type InlineQueryResultsButton can be used anywhere in inline mode. Users can create content in a web interface and then seamlessly send it to the current chat via inline mode.
You can use the button parameter in the answerInlineQuery method to display a special 'Switch to Mini App' button either above or in place of the inline results. This button will open a Mini App from the specified URL. Once done, you can call the Telegram.WebApp.switchInlineQuery method to send the user back to inline mode.
Inline Mini Apps have no access to the chat – they can't read messages or send new ones on behalf of the user. To send messages, the user must be redirected to inline mode and actively pick a result.
Good for:
- Fully-fledged web services and integrations in inline mode.
Direct Link Mini Apps
TL;DR: Mini App Bots can be launched from a direct link in any chat. They support a startapp parameter and are aware of the current chat context.
You can use direct links to open a Mini App directly in the current chat. If a non-empty startapp parameter is included in the link, it will be passed to the Mini App in the start_param field and in the GET parameter tgWebAppStartParam.
In this mode, Mini Apps can use the chat_type and chat_instance parameters to keep track of the current chat context. This introduces support for concurrent and shared usage by multiple chat members – to create live whiteboards, group orders, multiplayer games and similar apps.
Mini Apps opened from a direct link have no access to the chat – they can't read messages or send new ones on behalf of the user. To send messages, the user must be redirected to inline mode and actively pick a result.
Examples
https://t.me/botusername/appnamehttps://t.me/botusername/appname?startapp=command
Good for:
- Fully-fledged web services and integrations that any user can open in one tap.
- Cooperative, multiplayer or teamwork-oriented services within a chat context.
- The use cases are effectively unlimited.
Launching Mini Apps from the Attachment Menu
TL;DR: Mini App Bots can request to be added directly to a user's attachment menu, allowing them to be quickly launched from any chat. To try this mode, open this attachment menu link for @DurgerKingBot, then use the
menu in any type of chat.
Mini App Bots can request to be added directly to a user's attachment menu, allowing them to be quickly launched from any type of chat. You can configure in which types of chats your mini app can be started from the attachment menu (private, groups, supergroups or channels).
Attachment menu integration is currently only available for major advertisers on the Telegram Ad Platform. However, all bots can use it in the test server environment.
To enable this feature for your bot, open @BotFather from an account on the test server and send the /setattach command – or go to Bot Settings > Configure Attachment Menu. Then specify the URL that will be opened to launch the bot's Mini App via its icon in the attachment menu.
You can add a 'Settings' item to the context menu of your Mini App using @BotFather. When users select this option from the menu, your bot will receive a settingsButtonClicked event.
In addition to the user's theme settings, the bot will receive basic user information (ID, name, username, language_code, photo), as well as public info about the chat partner (ID, name, username, photo) or the chat info (ID, type, title, username, photo) and a unique identifier for the web view session query_id, which allows messages of any type to be sent to the chat on behalf of the user that opened the bot.
The bot can call the Bot API method answerWebAppQuery, which sends an inline message from the user via the bot to the chat where it was launched and closes the Mini App.
You can read more about adding bots to the attachment menu here.
Initializing Mini Apps
To connect your Mini App to the Telegram client, place the script telegram-web-app.js in the <head> tag before any other scripts, using this code:
<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:
| 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 Telegram app. |
| platform | String | The name of the platform of the user's Telegram app. |
| colorScheme | String | The color scheme currently used in the Telegram app. Either “light” or “dark”. Also available as the CSS variable var(--tg-color-scheme). |
| themeParams | ThemeParams | An object containing the current theme settings used in the Telegram 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(--tg-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 Telegram interface. |
| MainButton | MainButton | An object for controlling the main button, which is displayed at the bottom of the Mini App in the Telegram interface. |
| SettingsButton NEW | SettingsButton | An object for controlling the Settings item in the context menu of the Mini App in the Telegram interface. |
| HapticFeedback | HapticFeedback | An object for controlling haptic feedback. |
| CloudStorage | CloudStorage | An object for controlling cloud storage. |
| isVersionAtLeast(version) | Function | 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. |
| setHeaderColor(color) | Function | 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. |
| setBackgroundColor(color) | Function | Bot API 6.1+ 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 | Bot API 6.2+ A method that enables a confirmation dialog while the user is trying to close the Mini App. |
| disableClosingConfirmation() | Function | Bot API 6.2+ 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 | 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. 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) |
| openTelegramLink(url) | Function | A method that opens a telegram link inside the Telegram app. The Mini App will not be closed after this method is called. Up to Bot API 7.0 The Mini App will be closed after this method is called. |
| openInvoice(url[, callback]) | Function | Bot API 6.1+ A method that opens an invoice using the link url. The Mini 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. |
| showPopup(params[, callback]) | Function | Bot API 6.2+ 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 | 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. |
| showConfirm(message[, callback]) | Function | 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. |
| showScanQrPopup(params[, callback]) | Function | 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. |
| closeScanQrPopup() | Function | 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. |
| readTextFromClipboard([callback]) | Function | Bot API 6.4+ 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 | 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. |
| requestContact([callback]) | Function | 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. |
| ready() | Function | A method that informs the Telegram 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 Telegram.WebApp.isExpanded parameter |
| close() | Function | A method that closes the Mini App. |
ThemeParams
Mini 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:
| Field | Type | Description |
|---|---|---|
| bg_color | String | Optional. Background color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-bg-color). |
| text_color | String | Optional. Main text color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-text-color). |
| hint_color | String | Optional. Hint text color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-hint-color). |
| link_color | String | Optional. Link color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-link-color). |
| button_color | String | Optional. Button color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-button-color). |
| button_text_color | String | Optional. Button text color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-button-text-color). |
| secondary_bg_color | String | Optional. Bot API 6.1+ Secondary background color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-secondary-bg-color). |
| header_bg_color NEW | String | Optional. Bot API 7.0+ Header background color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-header-bg-color). |
| accent_text_color NEW | String | Optional. Bot API 7.0+ Accent text color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-accent-text-color). |
| section_bg_color NEW | String | Optional. 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_header_text_color NEW | String | Optional. 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). |
| subtitle_text_color NEW | String | Optional. Bot API 7.0+ Subtitle text color in the #RRGGBB format.Also available as the CSS variable var(--tg-theme-subtitle-text-color). |
| destructive_text_color NEW | String | Optional. 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). |
PopupParams
This object describes the native popup.
| Field | Type | Description |
|---|---|---|
| title | String | Optional. The text to be displayed in the popup title, 0-64 characters. |
| message | String | The message to be displayed in the body of the popup, 1-256 characters. |
| buttons | Array of PopupButton | Optional. List of buttons to be displayed in the popup, 1-3 buttons. Set to [{“type”:“close”}] by default. |
ScanQrPopupParams
This object describes the native popup for scanning QR codes.
| Field | Type | Description |
|---|---|---|
| text | String | Optional. The text to be displayed under the 'Scan QR' heading, 0-64 characters. |
PopupButton
This object describes the native popup button.
| Field | Type | Description |
|---|---|---|
| id | String | Optional. 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. |
| type | String | Optional. Type of the button. Set to default by default. Can be one of these values: - default, a button with the default style, - ok, a button with the localized text “OK”, - close, a button with the localized text “Close”, - cancel, a button with the localized text “Cancel”, - destructive, a button with a style that indicates a destructive action (e.g. “Remove”, “Delete”, etc.). |
| text | String | Optional. The text to be displayed on the button, 0-64 characters. Required if type is default or destructive. Irrelevant for other types. |
BackButton
This object controls the back button, which can be displayed in the header of the Mini App in the Telegram interface.
| Field | Type | Description |
|---|---|---|
| isVisible | Boolean | Shows whether the button is visible. Set to false by default. |
| onClick(callback) | Function | Bot API 6.1+ A method that sets the button press event handler. An alias for Telegram.WebApp.onEvent('backButtonClicked', callback) |
| offClick(callback) | Function | Bot API 6.1+ A method that removes the button press event handler. An alias for Telegram.WebApp.offEvent('backButtonClicked', callback) |
| show() | Function | Bot API 6.1+ A method to make the button active and visible. |
| hide() | Function | Bot API 6.1+ A method to hide the button. |
All these methods return the BackButton object so they can be chained.
MainButton
This object controls the main button, which is displayed at the bottom of the Mini App in the Telegram interface.
| 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 Telegram.WebApp.onEvent('mainButtonClicked', callback) |
| offClick(callback) | Function | A method that removes the button press event handler. An alias for Telegram.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. |
| enable() | 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. |
All these methods return the MainButton object so they can be chained.
SettingsButton
NEW This object controls the Settings item in the context menu of the Mini App in the Telegram interface.
| Field | Type | Description |
|---|---|---|
| isVisible | Boolean | Shows whether the context menu item is visible. Set to false by default. |
| onClick(callback) | Function | Bot API 7.0+ A method that sets the press event handler for the Settings item in the context menu. An alias for Telegram.WebApp.onEvent('settingsButtonClicked', callback) |
| offClick(callback) | Function | Bot API 7.0+ A method that removes the press event handler from the Settings item in the context menu. An alias for Telegram.WebApp.offEvent('settingsButtonClicked', callback) |
| show() | Function | Bot API 7.0+ A method to make the Settings item in the context menu visible. |
| hide() | Function | Bot API 7.0+ A method to hide the Settings item in the context menu. |
All these methods return the SettingsButton object so they can be chained.
HapticFeedback
This object controls haptic feedback.
| Field | Type | Description |
|---|---|---|
| impactOccurred(style) | Function | Bot API 6.1+ A method tells that an impact occurred. The Telegram app may play the appropriate haptics based on style value passed. Style can be one of these values: - light, indicates a collision between small or lightweight UI objects, - medium, indicates a collision between medium-sized or medium-weight UI objects, - heavy, indicates a collision between large or heavyweight UI objects, - rigid, indicates a collision between hard or inflexible UI objects, - soft, indicates a collision between soft or flexible UI objects. |
| notificationOccurred(type) | Function | Bot API 6.1+ A method tells that a task or action has succeeded, failed, or produced a warning. The Telegram app may play the appropriate haptics based on type value passed. Type can be one of these values: - error, indicates that a task or action has failed, - success, indicates that a task or action has completed successfully, - warning, indicates that a task or action produced a warning. |
| selectionChanged() | Function | Bot API 6.1+ A method tells that the user has changed a selection. The Telegram app may play the appropriate haptics. Do not use this feedback when the user makes or confirms a selection; use it only when the selection changes. |
All these methods return the HapticFeedback object so they can be chained.
CloudStorage
This object controls the cloud storage. Each bot can store up to 1024 items per user in the cloud storage.
| Field | Type | Description |
|---|---|---|
| setItem(key, value[, callback]) | Function | Bot API 6.9+ A method that stores a value in the cloud storage using the specified key. The key should contain 1-128 characters, only A-Z, a-z, 0-9, _ and - are allowed. The value should contain 0-4096 characters. You can store up to 1024 keys in the cloud storage. If an optional callback parameter was passed, the callback function will be called. In case of an error, the first argument will contain the error. In case of success, the first argument will be null and the second argument will be a boolean indicating whether the value was stored. |
| getItem(key, callback) | Function | Bot API 6.9+ A method that receives a value from the cloud storage using the specified key. The key should contain 1-128 characters, only A-Z, a-z, 0-9, _ and - are allowed. In case of an error, the callback function will be called and the first argument will contain the error. In case of success, the first argument will be null and the value will be passed as the second argument. |
| getItems(keys, callback) | Function | Bot API 6.9+ A method that receives values from the cloud storage using the specified keys. The keys should contain 1-128 characters, only A-Z, a-z, 0-9, _ and - are allowed. In case of an error, the callback function will be called and the first argument will contain the error. In case of success, the first argument will be null and the values will be passed as the second argument. |
| removeItem(key[, callback]) | Function | Bot API 6.9+ A method that removes a value from the cloud storage using the specified key. The key should contain 1-128 characters, only A-Z, a-z, 0-9, _ and - are allowed. If an optional callback parameter was passed, the callback function will be called. In case of an error, the first argument will contain the error. In case of success, the first argument will be null and the second argument will be a boolean indicating whether the value was removed. |
| removeItems(keys[, callback]) | Function | Bot API 6.9+ A method that removes values from the cloud storage using the specified keys. The keys should contain 1-128 characters, only A-Z, a-z, 0-9, _ and - are allowed. If an optional callback parameter was passed, the callback function will be called. In case of an error, the first argument will contain the error. In case of success, the first argument will be null and the second argument will be a boolean indicating whether the values were removed. |
| getKeys(callback) | Function | Bot API 6.9+ A method that receives the list of all keys stored in the cloud storage. In case of an error, the callback function will be called and the first argument will contain the error. In case of success, the first argument will be null and the list of keys will be passed as the second argument. |
All these methods return the CloudStorage object, so they can be chained.
WebAppInitData
This object contains data that is transferred to the Mini App when it is opened. It is empty if the Mini App was launched from a keyboard button or from inline mode.
| Field | Type | Description |
|---|---|---|
| query_id | String | Optional. A unique identifier for the Mini App session, required for sending messages via the answerWebAppQuery method. |
| user | WebAppUser | Optional. An object containing data about the current user. |
| receiver | WebAppUser | Optional. An object containing data about the chat partner of the current user in the chat where the bot was launched via the attachment menu. Returned only for private chats and only for Mini Apps launched via the attachment menu. |
| chat | WebAppChat | Optional. An object containing data about the chat where the bot was launched via the attachment menu. Returned for supergroups, channels and group chats – only for Mini Apps launched via the attachment menu. |
| chat_type | String | Optional. Type of the chat from which the Mini App was opened. Can be either “sender” for a private chat with the user opening the link, “private”, “group”, “supergroup”, or “channel”. Returned only for Mini Apps launched from direct links. |
| chat_instance | String | Optional. Global identifier, uniquely corresponding to the chat from which the Mini App was opened. Returned only for Mini Apps launched from a direct link. |
| start_param | String | Optional. The value of the startattach parameter, passed via link. Only returned for Mini Apps when launched from the attachment menu via link. The value of the start_param parameter will also be passed in the GET-parameter tgWebAppStartParam, so the Mini App can load the correct interface right away. |
| can_send_after | Integer | Optional. Time in seconds, after which a message can be sent via the answerWebAppQuery method. |
| auth_date | Integer | Unix time when the form was opened. |
| hash | String | A hash of all passed parameters, which the bot server can use to check their validity. |
WebAppUser
This object contains the data of the Mini App user.
| Field | Type | Description |
|---|---|---|
| id | Integer | A unique identifier for the user or bot. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. It has at most 52 significant bits, so a 64-bit integer or a double-precision float type is safe for storing this identifier. |
| 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. |
| is_premium | True | Optional. True, if this user is a Telegram Premium user. |
| added_to_attachment_menu | True | Optional. True, if this user added the bot to the attachment menu. |
| allows_write_to_pm | True | Optional. True, if this user allowed the bot to message them. |
| 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. |
WebAppChat
This object represents a chat.
| Field | Type | Description |
|---|---|---|
| id | Integer | Unique identifier for this chat. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a signed 64-bit integer or double-precision float type are safe for storing this identifier. |
| type | String | Type of chat, can be either “group”, “supergroup” or “channel” |
| title | String | Title of the chat |
| username | String | Optional. Username of the chat |
| photo_url | String | Optional. URL of the chat’s photo. The photo can be in .jpeg or .svg formats. Only returned for Mini Apps launched from the attachment menu. |
Validating data received via the Mini App
To validate data received via the Mini App, one should send the data from the Telegram.WebApp.initData field to the bot's backend. The data is a query string, which is composed of a series of field-value pairs.
You can verify the integrity of the data received by comparing the received hash parameter with the hexadecimal representation of the HMAC-SHA-256 signature of the data-check-string with the secret key, which is the HMAC-SHA-256 signature of the bot's token with the constant string WebAppData used as a key.
Data-check-string is a chain of all received fields, sorted alphabetically, in the format key=<value> with a line feed character ('\n', 0x0A) used as separator – e.g., 'auth_date=<auth_date>\nquery_id=<query_id>\nuser=<user>'.
The full check might look like:
data_check_string = ...
secret_key = HMAC_SHA256(<bot_token>, "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
// data is from Telegram
}To prevent the use of outdated data, you can additionally check the auth_date field, which contains a Unix timestamp of when it was received by the Mini App.
Once validated, the data may be used on your server. Complex data types are represented as JSON-serialized objects.
Events Available for Mini Apps
The Mini App can receive events from the Telegram app, onto which a handler can be attached using the Telegram.WebApp.onEvent(eventType, eventHandler) method. Inside eventHandler the this object refers to Telegram.WebApp, the set of parameters sent to the handler depends on the event type. Below is a list of possible events:
| eventType | Description |
|---|---|
themeChanged |
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. |
viewportChanged |
Occurs when the visible section of the Mini App is changed. eventHandler receives an object with the single field isStateStable. If isStateStable is true, the resizing of the Mini App is finished. If it is false, the resizing is ongoing (the user is expanding or collapsing the Mini App or an animated object is playing). The current value of the visible section’s height is available in this.viewportHeight. |
mainButtonClicked |
Occurs when the main button is pressed. eventHandler receives no parameters. |
backButtonClicked |
Bot API 6.1+ Occurrs when the back button is pressed. eventHandler receives no parameters. |
settingsButtonClicked |
Bot API 6.1+ Occurrs when the Settings item in context menu is pressed. eventHandler receives no parameters. |
invoiceClosed |
Bot API 6.1+ 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. |
popupClosed |
Bot API 6.2+ 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. |
qrTextReceived |
Bot API 6.4+ 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. |
clipboardTextReceived |
Bot API 6.4+ 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 Mini App has no access to the clipboard, the field data will be null. |
writeAccessRequested |
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. |
contactRequested |
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. |
Adding Bots to the Attachment Menu
Attachment menu integration is currently only available for major advertisers on the Telegram Ad Platform. However, all bots can use it in the test server environment. Talk to Botfather on the test server to set up the integration.
A special link is used to add bots to the attachment menu:
https://t.me/botusername?startattach
orhttps://t.me/botusername?startattach=command
For example, open this attachment menu link for @DurgerKingBot, then use the
Opening the link prompts the user to add the bot to their attachment menu. If the bot has already been added, the attachment menu will open in the current chat and redirect to the bot there (if the link is opened from a 1-on-1 chat). If a non-empty startattach parameter was included in the link, it will be passed to the Mini App in the start_param field and in the GET parameter tgWebAppStartParam.
The following link formats are also supported:
https://t.me/username?attach=botusernamehttps://t.me/username?attach=botusername&startattach=commandhttps://t.me/+1234567890?attach=botusernamehttps://t.me/+1234567890?attach=botusername&startattach=command
These links open the Mini App in the attachment menu in the chat with a specific user. If the bot wasn't already added to the attachment menu, the user will be prompted to do so. If a non-empty startattach parameter was included in the link, it will be passed to the Mini App in the start_param field and in the GET parameter tgWebAppStartParam.
Bot API 6.1+ supports a new link format:
https://t.me/botusername?startattach&choose=users+botshttps://t.me/botusername?startattach=command&choose=groups+channels
Opening such a link prompts the user to choose a specific chat and opens the attachment menu in that chat. If the bot wasn't already added to the attachment menu, the user will be prompted to do so. 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 separated by a + sign. If a non-empty startattach parameter was included in the link, it will be passed to the Mini App in the start_param field and in the GET parameter tgWebAppStartParam.
Testing Mini Apps
Using bots in the test environment
To log in to the test environment, use either of the following:
- iOS: tap 10 times on the Settings icon > Accounts > Login to another account > Test.
- Telegram Desktop: open ☰ Settings > Shift + Alt + Right click ‘Add Account’ and select ‘Test Server’.
- macOS: click the Settings icon 10 times to open the Debug Menu, ⌘ + click ‘Add Account’ and log in via phone number.
The test environment is completely separate from the main environment, so you will need to create a new user account and a new bot with @BotFather.
After receiving your bot token, you can send requests to the Bot API in this format:
https://api.telegram.org/bot<token>/test/METHOD_NAMENote: When working with the test environment, you may use HTTP links without TLS to test your Mini App.
Debug Mode for Mini Apps
Use these tools to find app-specific issues in your Mini App:
Android
- Enable USB-Debugging on your device.
- In Telegram Settings, scroll all the way down, press and hold on the version number two times.
- Choose Enable WebView Debug in the Debug Settings.
- Connect your phone to your computer and open
chrome://inspect/#devicesin Chrome – you will see your Mini App there when you launch it on your phone.
Telegram Desktop on Windows and Linux
- Download and launch the Beta Version of Telegram Desktop on Windows or Linux (not supported on Telegram Desktop for macOS yet).
- Go to Settings > Advanced > Experimental settings > Enable webview inspection.
- Right click in the WebView and choose Inspect.
Telegram macOS
- Download and launch the Beta Version of Telegram macOS.
- Quickly click 5 times on the Settings icon to open the debug menu and enable “Debug Mini Apps”.
- Right click in the Mini App and choose Inspect Element.