Telegram bots can completely replace any website. They 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.
With Web Apps, bots get a whole new dimension. Bot developers can create infinitely flexible interfaces with JavaScript, the most widely used programming language in the world.
To see a Web App in action, try our sample @DurgerKingBot.
Recent changes
April 21, 2023
Bot API 6.7
- Added support for launching Web 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 Web Apps
Color Schemes
Web 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 Web 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 Web Apps
Telegram currently supports six different ways of launching Web 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 Web Apps
TL;DR: Web 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 Web App from the specified URL.
To transmit data from the user back to the bot, the Web 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 Web Apps
TL;DR: For more interactive Web 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 Web App using a web_app type Inline KeyboardButton.
From the button, a Web 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 Web 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 Web Apps from the Menu Button
TL;DR: Web 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 Web 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 Web App instead.
To configure the menu button, you must specify the text it should show and the Web 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 Web Apps based on a user’s settings in your bot.
Apart from this, Web Apps opened via the menu button work in the exact same way as when using inline buttons.
@DurgerKingBot allows launching its Web App both from an inline button and from the menu button.
Inline Mode Web Apps
TL;DR: Web Apps launched via switch_web_app 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.
NEW You can use the switch_web_app parameter in the answerInlineQuery method to display a special ‘Switch to Web App’ button either above or in place of the inline results. This button will open a Web App from the specified URL. Once done, you can call the Telegram.WebApp.switchInlineQuery method to send the user back to inline mode.
Inline Web 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 Web Apps
TL;DR: Web 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.
NEW You can use direct links to open a Web App directly in the current chat. If a non-empty startapp parameter is included in the link, it will be passed to the Web App in the start_param field and in the GET parameter tgWebAppStartParam.
In this mode, Web 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.
Web 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 Web Apps from the Attachment Menu
TL;DR: Web 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.
Web 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 web 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 Web App via its icon in the attachment menu.
You can add a ‘Settings’ item to the context menu of your Web 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 Web App.
You can read more about adding bots to the attachment menu here.
Initializing Web Apps
To connect your Web App to the Telegram client, place the script telegram-web-app.js in the tag before any other scripts, using this code:
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 Web 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 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. |
| 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 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. |
| viewportHeight | Float | 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 | Float | 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 Note the event |
| 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 Web 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 Web App in the Telegram interface. |
| MainButton | MainButton | An object for controlling the main button, which is displayed at the bottom of the Web App in the Telegram interface. |
| HapticFeedback | HapticFeedback | An object for controlling haptic feedback. |
| 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. You can only pass Telegram.WebApp.themeParams.bg_color or Telegram.WebApp.themeParams.secondary_bg_color as a color or you can use keywords bg_color, secondary_bg_color instead. |
| setBackgroundColor(color) | Function | 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. |
| enableClosingConfirmation() | Function | Bot API 6.2+ A method that enables a confirmation dialog while the user is trying to close the Web App. |
| disableClosingConfirmation() | Function | Bot API 6.2+ A method that disables the confirmation dialog while the user is trying to close the Web 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 |
