Net Apps for Bots
Telegram bots can utterly change any web site. They help seamless authorization, integrated payments by way of 20 fee suppliers (with Google Pay and Apple Pay out of the field), delivering tailor-made push notifications to customers, and much more.
With Net Apps, bots get an entire new dimension. Bot builders can create infinitely versatile interfaces with JavaScript, essentially the most extensively used programming language on this planet.
To see a Net App in motion, strive our pattern @DurgerKingBot.
Current modifications
April 21, 2023
Bot API 6.7
- Added help for launching Net Apps from inline question outcomes and from a direct hyperlink.
- Added the tactic switchInlineQuery to the category WebApp.
December 30, 2022
Bot API 6.4
- Added the sector platform, the optionally available parameter choices to the tactic openLink and the strategies showScanQrPopup, closeScanQrPopup, readTextFromClipboard to the category WebApp.
- Added the occasions qrTextReceived, clipboardTextReceived.
August 12, 2022
Bot API 6.2
- Added the sector isClosingConfirmationEnabled and the strategies enableClosingConfirmation, disableClosingConfirmation, showPopup, showAlert, showConfirm to the category WebApp.
- Added the sector is_premium to the category WebAppUser.
- Added the occasion popupClosed.
June 20, 2022
Bot API 6.1
- Added the power to make use of bots added to the attachment menu in group, supergroup and channel chats.
- Added help for t.me links that can be utilized to pick out the chat during which the attachment menu with the bot will likely be opened.
- Added the fields model, headerColor, backgroundColor, BackButton, HapticFeedback and the strategies isVersionAtLeast, setHeaderColor, setBackgroundColor, openLink, openTelegramLink, openInvoice to the category WebApp.
- Added the sector secondary_bg_color to the category ThemeParams.
- Added the tactic offClick to the category MainButton.
- Added the fields chat, can_send_after to the category WebAppInitData.
- Added the events backButtonClicked, settingsButtonClicked, invoiceClosed.
Designing Net Apps
Coloration Schemes
Net Apps all the time obtain information concerning the consumer’s present shade theme in actual time, so you’ll be able to modify the looks of your interfaces to match it. For instance, when customers change between Day and Evening modes or use varied custom themes.
Design Tips
Telegram apps are recognized for being snappy, clean and following a constant cross-platform design. Your Net App ought to ideally replicate these rules.
- All parts ought to be responsive and designed with a mobile-first method.
- Interactive parts ought to mimic the fashion, habits and intent of UI parts that exist already.
- All included animations ought to be clean, ideally 60fps.
- All inputs and pictures ought to include labels for accessibility functions.
- The app ought to ship a seamless expertise by monitoring the dynamic theme-based colors supplied by the API and utilizing them accordingly.
Implementing Net Apps
Telegram at present helps six alternative ways of launching Net Apps: from a keyboard button, from an inline button, from the bot menu button, by way of inline mode, from a direct link – and even from the attachment menu.
Keyboard Button Net Apps
TL;DR: Net Apps launched from a web_app kind keyboard button can ship information again to the bot in a service message utilizing Telegram.WebApp.sendData. This makes it potential for the bot to provide a response with out speaking with any exterior servers.
Customers can work together with bots utilizing custom keyboards, buttons under bot messages, in addition to by sending freeform textual content messages or any of the attachment sorts supported by Telegram: images and movies, recordsdata, areas, contacts and polls. For much more flexibility, bots can make the most of the complete energy of HTML5 to create user-friendly enter interfaces.
You possibly can ship a web_app kind KeyboardButton that opens a Net App from the desired URL.
To transmit information from the consumer again to the bot, the Net App can name the Telegram.WebApp.sendData methodology. Knowledge will likely be transmitted to the bot as a String in a service message. The bot can proceed speaking with the consumer after receiving it.
Good for:
- Сustom information enter interfaces (a customized calendar for choosing dates; deciding on information from a listing with superior search choices; a randomizer that lets the consumer “spin a wheel” and chooses one of many accessible choices, and so on.)
- Reusable parts that don’t depend upon a selected bot.
Inline Button Net Apps
TL;DR: For extra interactive Net Apps like @DurgerKingBot, use a web_app kind Inline KeyboardButton, which will get fundamental consumer data and can be utilized to ship a message on behalf of the consumer to the chat with the bot.
If receiving textual content information alone is inadequate otherwise you want a extra superior and personalised interface, you’ll be able to open a Net App utilizing a web_app kind Inline KeyboardButton.
From the button, a Net App will open with the URL specified within the button. Along with the consumer’s theme settings, it can obtain fundamental consumer data (ID, title, username, language_code) and a novel identifier for the session, query_id, which permits messages on behalf of the consumer to be despatched again to the bot.
The bot can name the Bot API methodology answerWebAppQuery to ship an inline message from the consumer again to the bot and shut the Net App. After receiving the message, the bot can proceed speaking with the consumer.
Good for:
- Totally-fledged net companies and integrations of any variety.
- The use instances are successfully limitless.
Launching Net Apps from the Menu Button
TL;DR: Net Apps might be launched from a personalized menu button. This merely gives a faster method to entry the app and is in any other case similar to launching a Web App from an inline button.
By default, chats with bots all the time present a handy menu button that gives fast entry to all listed commands. With Bot API 6.0, this button can be utilized to launch a Net App as a substitute.
To configure the menu button, you need to specify the textual content it ought to present and the Net App URL. There are two methods to set these parameters:
- To customise the button for all customers, use @BotFather (the
/setmenubuttoncommand or Bot Settings > Menu Button). - To customise the button for each all customers and particular customers, use the setChatMenuButton methodology within the Bot API. For instance, change the button textual content in accordance with the consumer’s language, or present hyperlinks to completely different Net Apps based mostly on a consumer’s settings in your bot.
Aside from this, Net Apps opened by way of the menu button work in the very same means as when using inline buttons.
@DurgerKingBot permits launching its Net App each from an inline button and from the menu button.
Inline Mode Net Apps
TL;DR: Net Apps launched by way of switch_web_app can be utilized wherever in inline mode. Customers can create content material in an online interface after which seamlessly ship it to the present chat by way of inline mode.
NEW You need to use the switch_web_app parameter within the answerInlineQuery methodology to show a particular ‘Swap to Net App’ button both above or instead of the inline outcomes. This button will open a Net App from the desired URL. As soon as accomplished, you’ll be able to name the Telegram.WebApp.switchInlineQuery methodology to ship the consumer again to inline mode.
Inline Net Apps have no entry to the chat – they can not learn messages or ship new ones on behalf of the consumer. To ship messages, the consumer should be redirected to inline mode and actively decide a end result.
Good for:
- Totally-fledged net companies and integrations in inline mode.
Direct Hyperlink Net Apps
TL;DR: Net App Bots might be launched from a direct hyperlink in any chat. They help a startapp parameter and are conscious of the present chat context.
NEW You need to use direct hyperlinks to open a Net App straight within the present chat. If a non-empty startapp parameter is included within the hyperlink, it is going to be handed to the Net App within the start_param subject and within the GET parameter tgWebAppStartParam.
On this mode, Net Apps can use the chat_type and chat_instance parameters to maintain observe of the present chat context. This introduces help for concurrent and shared utilization by a number of chat members – to create stay whiteboards, group orders, multiplayer video games and comparable apps.
Net Apps opened from a direct hyperlink have no entry to the chat – they can not learn messages or ship new ones on behalf of the consumer. To ship messages, the consumer should be redirected to inline mode and actively decide a end result.
Examples
https://t.me/botusername/appnamehttps://t.me/botusername/appname?startapp=command
Good for:
- Totally-fledged net companies and integrations that any consumer can open in a single faucet.
- Cooperative, multiplayer or teamwork-oriented companies inside a chat context.
- The use instances are successfully limitless.
Launching Net Apps from the Attachment Menu
TL;DR: Net App Bots can request to be added on to a consumer’s attachment menu, permitting them to be rapidly launched from any chat. To do that mode, open this attachment menu link for @DurgerKingBot, then use the
menu in any kind of chat.
menu in any kind of chat.
Net App Bots can request to be added on to a consumer’s attachment menu, permitting them to be rapidly launched from any kind of chat. You possibly can configure during which sorts of chats your net app might be began from the attachment menu (non-public, teams, supergroups or channels).
Attachment menu integration is at present solely accessible for main advertisers on the Telegram Ad Platform. Nonetheless, all bots can use it within the test server environment.
To allow this characteristic to your bot, open @BotFather from an account on the test server and ship the /setattach command – or go to Bot Settings > Configure Attachment Menu. Then specify the URL that will likely be opened to launch the bot’s Net App by way of its icon within the attachment menu.
You possibly can add a ‘Settings’ merchandise to the context menu of your Net App utilizing @BotFather. When customers choose this feature from the menu, your bot will obtain a settingsButtonClicked occasion.
Along with the consumer’s theme settings, the bot will obtain fundamental consumer data (ID, title, username, language_code, picture), in addition to public information concerning the chat companion (ID, title, username, picture) or the chat information (ID, kind, title, username, picture) and a novel identifier for the net view session query_id, which permits messages of any kind to be despatched to the chat on behalf of the consumer that opened the bot.
The bot can name the Bot API methodology answerWebAppQuery, which sends an inline message from the consumer by way of the bot to the chat the place it was launched and closes the Net App.
You possibly can learn extra about including bots to the attachment menu here.
Initializing Net Apps
To attach your Net App to the Telegram shopper, place the script telegram-web-app.js within the <head> tag earlier than every other scripts, utilizing this code:
<script src="https://telegram.org/js/telegram-web-app.js"></script>As soon as the script is related, a window.Telegram.WebApp object will grow to be accessible with the next fields:
| Subject | Sort | Description |
|---|---|---|
| initData | String | A string with uncooked information transferred to the Net App, handy for validating data. WARNING: Validate data from this subject earlier than utilizing it on the bot’s server. |
| initDataUnsafe | WebAppInitData | An object with enter information transferred to the Net App. WARNING: Knowledge from this subject shouldn’t be trusted. You need to solely use information from initData on the bot’s server and solely after it has been validated. |
| model | String | The model of the Bot API accessible within the consumer’s Telegram app. |
| platform | String | The title of the platform of the consumer’s Telegram app. |
| colorScheme | String | The colour scheme at present used within the Telegram app. Both “gentle” or “darkish”. Additionally accessible because the CSS variable var(--tg-color-scheme). |
| themeParams | ThemeParams | An object containing the present theme settings used within the Telegram app. |
| isExpanded | Boolean | True, if the Net App is expanded to the utmost accessible peak. False, if the Net App occupies a part of the display and might be expanded to the complete peak utilizing the develop() methodology. |
| viewportHeight | Float | The present peak of the seen space of the Net App. Additionally accessible in CSS because the variable var(--tg-viewport-height).
The applying can show simply the highest a part of the Net App, with its decrease half remaining exterior the display space. From this place, the consumer can “pull” the Net App to its most peak, whereas the bot can do the identical by calling the develop() methodology. Because the place of the Net App modifications, the present peak worth of the seen space will likely be up to date in actual time. Please notice that the refresh fee of this worth will not be ample to easily observe the decrease border of the window. It shouldn’t be used to pin interface parts to the underside of the seen space. It is extra acceptable to make use of the worth of the |
| viewportStableHeight | Float | The peak of the seen space of the Net App in its final secure state. Additionally accessible in CSS as a variable var(--tg-viewport-stable-height).
The applying can show simply the highest a part of the Net App, with its decrease half remaining exterior the display space. From this place, the consumer can “pull” the Net App to its most peak, whereas the bot can do the identical by calling the develop() methodology. Not like the worth of Be aware the event |
| headerColor | String | Present header shade within the #RRGGBB format. |
| backgroundColor | String | Present background shade within the #RRGGBB format. |
| isClosingConfirmationEnabled | Boolean | True, if the affirmation dialog is enabled whereas the consumer is making an attempt to shut the Net App. False, if the affirmation dialog is disabled. |
| BackButton | BackButton | An object for controlling the again button which might be displayed within the header of the Net App within the Telegram interface. |
| MainButton | MainButton | An object for controlling the primary button, which is displayed on the backside of the Net App within the Telegram interface. |
| HapticFeedback | HapticFeedback | An object for controlling haptic suggestions. |
| isVersionAtLeast(model) | Perform | Returns true if the consumer’s app helps a model of the Bot API that is the same as or greater than the model handed because the parameter. |
| setHeaderColor(shade) | Perform | Bot API 6.1+ A technique that units the app header shade. You possibly can solely cross Telegram.WebApp.themeParams.bg_color or Telegram.WebApp.themeParams.secondary_bg_color as a shade or you should use key phrases bg_color, secondary_bg_color as a substitute. |
| setBackgroundColor(shade) | Perform | Bot API 6.1+ A technique that units the app background shade within the #RRGGBB format or you should use key phrases bg_color, secondary_bg_color as a substitute. |
| enableClosingConfirmation() | Perform | Bot API 6.2+ A technique that permits a affirmation dialog whereas the consumer is making an attempt to shut the Net App. |
| disableClosingConfirmation() | Perform | Bot API 6.2+ A technique that disables the affirmation dialog whereas the consumer is making an attempt to shut the Net App. |
| onEvent(eventType, eventHandler) | Perform | A technique that units the app occasion handler. Verify the list of available events. |
| offEvent(eventType, eventHandler) | Perform | A technique that deletes a beforehand set occasion handler. |
| sendData(information) | Perform | A technique used to ship information to the bot. When this methodology known as, a service message is shipped to the bot containing the information information of the size as much as 4096 bytes, and the Net App is closed. See the sector web_app_data within the class Message.
This methodology is barely accessible for Net Apps launched by way of a Keyboard button. |
| switchInlineQuery(question[, choose_chat_types]) NEW | Perform | Bot API 6.7+ A technique that inserts the bot’s username and the desired inline question within the present chat’s enter subject. Question could also be empty, during which case solely the bot’s username will likely be inserted. If an optionally available choose_chat_types parameter was handed, the shopper prompts the consumer to decide on a particular chat, then opens that chat and inserts the bot’s username and the desired inline question within the enter subject. You possibly can specify which sorts of chats the consumer will be capable to select from. It may be a number of of the next sorts: customers, bots, teams, channels. |
| openLink(url[, options]) | Perform | A technique that opens a hyperlink in an exterior browser. The Net App will not be closed. Bot API 6.4+ If the optionally available choices parameter is handed with the sector try_instant_view=true, the hyperlink will likely be opened in Instant View mode if potential. Be aware that this methodology might be known as solely in response to consumer interplay with the Net App interface (e.g. a click on contained in the Net App or on the primary button) |
| openTelegramLink(url) | Perform | A technique that opens a telegram hyperlink inside Telegram app. The Net App will be closed. |
| openInvoice(url[, callback]) | Perform | Bot API 6.1+ A technique that opens an bill utilizing the hyperlink url. The Net App will obtain the event invoiceClosed when the bill is closed. If an optionally available callback parameter was handed, the callback operate will likely be known as and the bill standing will likely be handed as the primary argument. |
| showPopup(params[, callback]) | Perform | Bot API 6.2+ A technique that reveals a local popup described by the params argument of the sort PopupParams. The Net App will obtain the event popupClosed when the popup is closed. If an optionally available callback parameter was handed, the callback operate will likely be known as and the sector id of the pressed button will likely be handed as the primary argument. |
| showAlert(message[, callback]) | Perform | Bot API 6.2+ A technique that reveals message in a easy alert with a ‘Shut’ button. If an optionally available callback parameter was handed, the callback operate will likely be known as when the popup is closed. |
| showConfirm(message[, callback]) | Perform | Bot API 6.2+ A technique that reveals message in a easy affirmation window with ‘OK’ and ‘Cancel’ buttons. If an optionally available callback parameter was handed, the callback operate will likely be known as when the popup is closed and the primary argument will likely be a boolean indicating whether or not the consumer pressed the ‘OK’ button. |
| showScanQrPopup(params[, callback]) | Perform | Bot API 6.4+ A technique that reveals a local popup for scanning a QR code described by the params argument of the sort ScanQrPopupParams. The Net App will obtain the event qrTextReceived each time the scanner catches a code with textual content information. If an optionally available callback parameter was handed, the callback operate will likely be known as and the textual content from the QR code will likely be handed as the primary argument. Returning true inside this callback operate causes the popup to be closed. |
| closeScanQrPopup() | Perform | Bot API 6.4+ A technique that closes the native popup for scanning a QR code opened with the showScanQrPopup methodology. Run it in case you obtained legitimate information within the event qrTextReceived. |
| readTextFromClipboard([callback]) | Perform | Bot API 6.4+ A technique that requests textual content from the clipboard. The Net App will obtain the event clipboardTextReceived. If an optionally available callback parameter was handed, the callback operate will likely be known as and the textual content from the clipboard will likely be handed as the primary argument.
Be aware: this methodology might be known as just for Net Apps launched from the attachment menu and solely in response to a consumer interplay with the Net App interface (e.g. a click on contained in the Net App or on the primary button). |
| prepared() | Perform | A technique that informs the Telegram app that the Net App is able to be displayed. It is suggested to name this methodology as early as potential, as quickly as all important interface parts are loaded. As soon as this methodology known as, the loading placeholder is hidden and the Net App is proven. If the tactic will not be known as, the placeholder will likely be hidden solely when the web page is absolutely loaded. |
| develop() | Perform | A technique that expands the Net App to the utmost accessible peak. To seek out out if the Net App is expanded to the utmost peak, check with the worth of the Telegram.WebApp.isExpanded parameter |
| shut() | Perform | A technique that closes the Net App. |
ThemeParams
Net Apps can adjust the appearance of the interface to match the Telegram consumer’s app in actual time. This object accommodates the consumer’s present theme settings:
| Subject | Sort | Description |
|---|---|---|
| bg_color | String | Non-compulsory. Background shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-bg-color). |
| text_color | String | Non-compulsory. Essential textual content shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-text-color). |
| hint_color | String | Non-compulsory. Trace textual content shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-hint-color). |
| link_color | String | Non-compulsory. Hyperlink shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-link-color). |
| button_color | String | Non-compulsory. Button shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-button-color). |
| button_text_color | String | Non-compulsory. Button textual content shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-button-text-color). |
| secondary_bg_color | String | Non-compulsory. Bot API 6.1+ Secondary background shade within the #RRGGBB format.Additionally accessible because the CSS variable var(--tg-theme-secondary-bg-color). |
PopupParams
This object describes the native popup.
| Subject | Sort | Description |
|---|---|---|
| title | String | Non-compulsory. The textual content to be displayed within the popup title, 0-64 characters. |
| message | String | The message to be displayed within the physique of the popup, 1-256 characters. |
| buttons | Array of PopupButton | Non-compulsory. Listing of buttons to be displayed within the popup, 1-3 buttons. Set to [{“type”:“close”}] by default. |
ScanQrPopupParams
This object describes the native popup for scanning QR codes.
| Subject | Sort | Description |
|---|---|---|
| textual content | String | Non-compulsory. The textual content to be displayed beneath the ‘Scan QR’ heading, 0-64 characters. |
PopupButton
This object describes the native popup button.
| Subject | Sort | Description |
|---|---|---|
| id | String | Non-compulsory. Identifier of the button, 0-64 characters. Set to empty string by default. If the button is pressed, its id is returned within the callback and the popupClosed occasion. |
| kind | String | Non-compulsory. Sort of the button. Set to default by default. May be certainly one of these values: – default, a button with the default fashion, – okay, a button with the localized textual content “OK”, – shut, a button with the localized textual content “Shut”, – cancel, a button with the localized textual content “Cancel”, – harmful, a button with a method that signifies a harmful motion (e.g. “Take away”, “Delete”, and so on.). |
| textual content | String | Non-compulsory. The textual content to be displayed on the button, 0-64 characters. Required if kind is default or harmful. Irrelevant for different sorts. |
BackButton
This object controls the again button, which might be displayed within the header of the Net App within the Telegram interface.
| Subject | Sort | Description |
|---|---|---|
| isVisible | Boolean | Reveals whether or not the button is seen. Set to false by default. |
| onClick(callback) | Perform | Bot API 6.1+ A technique that units the button press occasion handler. An alias for Telegram.WebApp.onEvent('backButtonClicked', callback) |
| offClick(callback) | Perform | Bot API 6.1+ A technique that removes the button press occasion handler. An alias for Telegram.WebApp.offEvent('backButtonClicked', callback) |
| present() | Perform | Bot API 6.1+ A technique to make the button lively and visual. |
| conceal() | Perform | Bot API 6.1+ A technique to cover the button. |
All these strategies return the BackButton object to allow them to be chained.
MainButton
This object controls the primary button, which is displayed on the backside of the Net App within the Telegram interface.
| Subject | Sort | Description |
|---|---|---|
| textual content | String | Present button textual content. Set to CONTINUE by default. |
| shade | String | Present button shade. Set to themeParams.button_color by default. |
| textColor | String | Present button textual content shade. Set to themeParams.button_text_color by default. |
| isVisible | Boolean | Reveals whether or not the button is seen. Set to false by default. |
| isActive | Boolean | Reveals whether or not the button is lively. Set to true by default. |
| isProgressVisible | Boolean | Readonly. Reveals whether or not the button is displaying a loading indicator. |
| setText(textual content) | Perform | A technique to set the button textual content. |
| onClick(callback) | Perform | A technique that units the button press occasion handler. An alias for Telegram.WebApp.onEvent('mainButtonClicked', callback) |
| offClick(callback) | Perform | A technique that removes the button press occasion handler. An alias for Telegram.WebApp.offEvent('mainButtonClicked', callback) |
| present() | Perform | A technique to make the button seen. Be aware that opening the Net App from the attachment menu hides the primary button till the consumer interacts with the Net App interface. |
| conceal() | Perform | A technique to cover the button. |
| allow() | Perform | A technique to allow the button. |
| disable() | Perform | A technique to disable the button. |
| showProgress(leaveActive) | Perform | A technique to point out a loading indicator on the button. It is suggested to show loading progress if the motion tied to the button might take a very long time. By default, the button is disabled whereas the motion is in progress. If the parameter leaveActive=true is handed, the button stays enabled. |
| hideProgress() | Perform | A technique to cover the loading indicator. |
| setParams(params) | Perform | A technique to set the button parameters. The params parameter is an object containing one or a number of fields that must be modified: textual content – button textual content; shade – button shade; text_color – button textual content shade; is_active – allow the button; is_visible – present the button. |
All these strategies return the MainButton object to allow them to be chained.
HapticFeedback
This object controls haptic suggestions.
| Subject | Sort | Description |
|---|---|---|
| impactOccurred(fashion) | Perform | Bot API 6.1+ A technique tells that an influence occurred. The Telegram app might play the suitable haptics based mostly on fashion worth handed. Model might be certainly one of these values: – gentle, signifies a collision between small or light-weight UI objects, – medium, signifies a collision between medium-sized or medium-weight UI objects, – heavy, signifies a collision between massive or heavyweight UI objects, – inflexible, signifies a collision between laborious or rigid UI objects, – comfortable, signifies a collision between comfortable or versatile UI objects. |
| notificationOccurred(kind) | Perform | Bot API 6.1+ A technique tells {that a} activity or motion has succeeded, failed, or produced a warning. The Telegram app might play the suitable haptics based mostly on kind worth handed. Sort might be certainly one of these values: – error, signifies {that a} activity or motion has failed, – success, signifies {that a} activity or motion has accomplished efficiently, – warning, signifies {that a} activity or motion produced a warning. |
| selectionChanged() | Perform | Bot API 6.1+ A technique tells that the consumer has modified a variety. The Telegram app might play the suitable haptics.
Don’t use this suggestions when the consumer makes or confirms a variety; use it solely when the choice modifications. |
All these strategies return the HapticFeedback object to allow them to be chained.
WebAppInitData
This object accommodates information that’s transferred to the Net App when it’s opened. It’s empty if the Net App was launched from a keyboard button or from inline mode.
| Subject | Sort | Description |
|---|---|---|
| query_id | String | Non-compulsory. A novel identifier for the Net App session, required for sending messages by way of the answerWebAppQuery methodology. |
| consumer | WebAppUser | Non-compulsory. An object containing information concerning the present consumer. |
| receiver | WebAppUser | Non-compulsory. An object containing information concerning the chat companion of the present consumer within the chat the place the bot was launched by way of the attachment menu. Returned just for non-public chats and just for Net Apps launched by way of the attachment menu. |
| chat | WebAppChat | Non-compulsory. An object containing information concerning the chat the place the bot was launched by way of the attachment menu. Returned for supergroups, channels and group chats – just for Net Apps launched by way of the attachment menu. |
| chat_type NEW | String | Non-compulsory. Sort of the chat from which the Net App was opened. May be both “sender” for a personal chat with the consumer opening the hyperlink, “non-public”, “group”, “supergroup”, or “channel”. Returned just for Net Apps launched from direct hyperlinks. |
| chat_instance NEW | String | Non-compulsory. World identifier, uniquely equivalent to the chat from which the Net App was opened. Returned just for Net Apps launched from a direct hyperlink. |
| start_param | String | Non-compulsory. The worth of the startattach parameter, handed via link. Solely returned for Net Apps when launched from the attachment menu by way of hyperlink.
The worth of the |
| can_send_after | Integer | Non-compulsory. Time in seconds, after which a message might be despatched by way of the answerWebAppQuery methodology. |
| auth_date | Integer | Unix time when the shape was opened. |
| hash | String | A hash of all handed parameters, which the bot server can use to check their validity. |
WebAppUser
This object accommodates the information of the Net App consumer.
| Subject | Sort | Description |
|---|---|---|
| id | Integer | A novel identifier for the consumer or bot. This quantity might have greater than 32 important bits and a few programming languages might have problem/silent defects in deciphering it. It has at most 52 important bits, so a 64-bit integer or a double-precision float kind is protected for storing this identifier. |
| is_bot | Boolean | Non-compulsory. True, if this consumer is a bot. Returns within the receiver subject solely. |
| first_name | String | First title of the consumer or bot. |
| last_name | String | Non-compulsory. Final title of the consumer or bot. |
| username | String | Non-compulsory. Username of the consumer or bot. |
| language_code | String | Non-compulsory. IETF language tag of the consumer’s language. Returns in consumer subject solely. |
| is_premium | True | Non-compulsory. True, if this consumer is a Telegram Premium consumer |
| photo_url | String | Non-compulsory. URL of the consumer’s profile picture. The picture might be in .jpeg or .svg codecs. Solely returned for Net Apps launched from the attachment menu. |
WebAppChat
This object represents a chat.
| Subject | Sort | Description |
|---|---|---|
| id | Integer | Distinctive identifier for this chat. This quantity might have greater than 32 important bits and a few programming languages might have problem/silent defects in deciphering it. However it has at most 52 important bits, so a signed 64-bit integer or double-precision float kind are protected for storing this identifier. |
| kind | String | Sort of chat, might be both “group”, “supergroup” or “channel” |
| title | String | Title of the chat |
| username | String | Non-compulsory. Username of the chat |
| photo_url | String | Non-compulsory. URL of the chat’s picture. The picture might be in .jpeg or .svg codecs. Solely returned for Net Apps launched from the attachment menu. |
Validating information obtained by way of the Net App
To validate information obtained by way of the Net App, one ought to ship the information from the Telegram.WebApp.initData subject to the bot’s backend. The information is a question string, which consists of a collection of field-value pairs.
You possibly can confirm the integrity of the information obtained by evaluating the obtained hash parameter with the hexadecimal illustration of the HMAC-SHA-256 signature of the data-check-string with the key key, which is the HMAC-SHA-256 signature of the bot’s token with the fixed string WebAppData used as a key.
Knowledge-check-string is a series of all obtained fields, sorted alphabetically, within the format key=<worth> with a line feed character (‘n’, 0x0A) used as separator – e.g., 'auth_date=<auth_date>nquery_id=<query_id>nuser=<consumer>'.
The complete verify may seem like:
data_check_string = ...
secret_key = HMAC_SHA256(<bot_token>, "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
// information is from Telegram
}To stop the usage of outdated information, you’ll be able to moreover verify the auth_date subject, which accommodates a Unix timestamp of when it was obtained by the Net App.
As soon as validated, the information could also be used in your server. Complicated information sorts are represented as JSON-serialized objects.
Occasions Out there for Net Apps
The Net App can obtain occasions from the Telegram app, onto which a handler might be connected utilizing the Telegram.WebApp.onEvent(eventType, eventHandler) methodology. Inside eventHandler the this object refers to Telegram.WebApp, the set of parameters despatched to the handler relies on the occasion kind. Under is a listing of potential occasions:
| eventType | Description |
|---|---|
themeChanged |
Happens at any time when theme settings are modified within the consumer’s Telegram app (together with switching to nighttime mode). eventHandler receives no parameters, new theme settings and shade scheme might be obtained by way of this.themeParams and this.colorScheme respectively. |
viewportChanged |
Happens when the seen part of the Net App is modified. eventHandler receives an object with the only subject isStateStable. If isStateStable is true, the resizing of the Net App is completed. Whether it is false, the resizing is ongoing (the consumer is increasing or collapsing the Net App or an animated object is enjoying). The present worth of the seen part’s peak is obtainable in this.viewportHeight. |
mainButtonClicked |
Happens 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 merchandise in context menu is pressed. eventHandler receives no parameters. |
invoiceClosed |
Bot API 6.1+ Occurrs when the opened bill is closed. eventHandler receives an object with the 2 fields: url – bill hyperlink supplied and standing – one of many bill statuses: – paid – bill was paid efficiently, – cancelled – consumer closed this bill with out paying, – failed – consumer tried to pay, however the fee was failed, – pending – the fee remains to be processing. The bot will obtain a service message a couple of successful payment when the fee is efficiently paid. |
popupClosed |
Bot API 6.2+ Occurrs when the opened popup is closed. eventHandler receives an object with the only subject button_id – the worth of the sector id of the pressed button. If no buttons have been pressed, the sector button_id will likely be null. |
qrTextReceived |
Bot API 6.4+ Happens when the QR code scanner catches a code with textual content information. eventHandler receives an object with the only subject information containing textual content information from the QR code. |
clipboardTextReceived |
Bot API 6.4+ Occurrs when the readTextFromClipboard methodology known as.eventHandler receives an object with the only subject information containing textual content information from the clipboard. If the clipboard accommodates non-text information, the sector information will likely be an empty string. If the Net App has no entry to the clipboard, the sector information will likely be null. |
Including Bots to the Attachment Menu
Attachment menu integration is at present solely accessible for main advertisers on the Telegram Ad Platform. Nonetheless, all bots can use it within the test server environment. Discuss to Botfather on the check server to set up the integration.
A particular hyperlink is used so as to add bots to the attachment menu:
https://t.me/botusername?startattach
orhttps://t.me/botusername?startattach=command
For instance, open this attachment menu link for @DurgerKingBot, then use the
Opening the hyperlink prompts the consumer so as to add the bot to their attachment menu. If the bot has already been added, the attachment menu will open within the present chat and redirect to the bot there (if the hyperlink is opened from a 1-on-1 chat). If a non-empty startattach parameter was included within the hyperlink, it is going to be handed to the Net App within the start_param subject and within the GET parameter tgWebAppStartParam.
The next hyperlink codecs are additionally supported:
https://t.me/username?connect=botusernamehttps://t.me/username?connect=botusername&startattach=commandhttps://t.me/+1234567890?connect=botusernamehttps://t.me/+1234567890?connect=botusername&startattach=command
These hyperlinks open the Net App within the attachment menu within the chat with a particular consumer. If the bot wasn’t already added to the attachment menu, the consumer will likely be prompted to take action. If a non-empty startattach parameter was included within the hyperlink, it is going to be handed to the Net App within the start_param subject and within the GET parameter tgWebAppStartParam.
Bot API 6.1+ helps a brand new hyperlink format:
https://t.me/botusername?startattach&select=customers+botshttps://t.me/botusername?startattach=command&select=teams+channels
Opening such a hyperlink prompts the consumer to decide on a particular chat and opens the attachment menu in that chat. If the bot wasn’t already added to the attachment menu, the consumer will likely be prompted to take action. You possibly can specify which sorts of chats the consumer will be capable to select from. It may be a number of of the next sorts: customers, bots, teams, channels separated by a + signal. If a non-empty startattach parameter was included within the hyperlink, it is going to be handed to the Net App within the start_param subject and within the GET parameter tgWebAppStartParam.
Testing Net Apps
Utilizing bots within the check setting
To log in to the check setting, use both of the next:
- iOS: faucet 10 occasions on the Settings icon > Accounts > Login to a different account > Check.
- Telegram Desktop: open ☰ Settings > Shift + Alt + Proper click on ‘Add Account’ and choose ‘Check Server’.
- macOS: click on the Settings icon 10 occasions to open the Debug Menu, ⌘ + click on ‘Add Account’ and log in by way of cellphone quantity.
The check setting is totally separate from the primary setting, so you will want to create a new consumer account and a new bot with @BotFather.
After receiving your bot token, you’ll be able to ship requests to the Bot API on this format:
https://api.telegram.org/bot<token>/check/METHOD_NAMEBe aware: When working with the check setting, chances are you’ll use HTTP hyperlinks with out TLS to check your Net App.
Debug Mode for Net Apps
Use these instruments to search out app-specific points in your Net App:
Android
- Enable USB-Debugging in your machine.
- In Telegram Settings, scroll all the best way down, press and maintain on the model quantity two occasions.
- Select Allow WebView Debug within the Debug Settings.
- Join your cellphone to your laptop and open
chrome://examine/#unitsin Chrome – you will note your Net App there whenever you launch it in your cellphone.
Telegram Desktop on Home windows and Linux
- Obtain and launch the Beta Version of Telegram Desktop on Home windows or Linux (not supported on Telegram Desktop for macOS but).
- Go to Settings > Superior > Experimental settings > Allow webview inspection.
- Proper click on within the WebView and select Examine.
Telegram macOS
- Obtain and launch the Beta Version of Telegram macOS.
- Shortly click on 5 occasions on the Settings icon to open the debug menu and allow “Debug Net Apps”.
- Proper click on within the net app and select Examine Aspect.