Added the ability to set any header color using the setHeaderColor method.
+
Added the field CloudStorage and the methods requestWriteAccess, requestContact to the class WebApp.
+
Added the fields added_to_attachment_menu, allows_write_to_pm to the class WebAppUser.
+
Added the events writeAccessRequested, contactRequested.
+
April 21, 2023
Bot API 6.7
@@ -165,7 +173,7 @@
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.
-
NEW 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.
+
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:
@@ -175,7 +183,7 @@
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.
-
NEW 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.
+
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.
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.
@@ -296,12 +309,12 @@
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.
+
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 or you can use keywords bg_color, secondary_bg_color instead.
+
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()
@@ -329,7 +342,7 @@
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]) NEW
+
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.
@@ -379,6 +392,16 @@
Bot API 6.4+ A method that requests text from the clipboard. The Mini App will receive the eventclipboardTextReceived. 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]) NEW
+
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]) NEW
+
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.
@@ -683,6 +706,50 @@
All these methods return the HapticFeedback object so they can be chained.
+
CloudStorage
+
NEW 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.
@@ -715,12 +782,12 @@
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 NEW
+
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 NEW
+
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.
@@ -790,7 +857,17 @@
is_premium
True
-
Optional. True, if this user is a Telegram Premium user
+
Optional. True, if this user is a Telegram Premium user.
+
+
+
added_to_attachment_menu NEW
+
True
+
Optional. True, if this user added the bot to the attachment menu.
+
+
+
allows_write_to_pm NEW
+
True
+
Optional. True, if this user allowed the bot to message them.
photo_url
@@ -895,6 +972,14 @@ if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
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.
+
+
writeAccessRequestedNEW
+
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.
+
+
+
contactRequestedNEW
+
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.
Added the ability to set any header color using the setHeaderColor method.
+
Added the field CloudStorage and the methods requestWriteAccess, requestContact to the class WebApp.
+
Added the fields added_to_attachment_menu, allows_write_to_pm to the class WebAppUser.
+
Added the events writeAccessRequested, contactRequested.
+
April 21, 2023
Bot API 6.7
@@ -165,7 +173,7 @@
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.
-
NEW 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.
+
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:
@@ -175,7 +183,7 @@
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.
-
NEW 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.
+
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.
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.
@@ -296,12 +309,12 @@
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.
+
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 or you can use keywords bg_color, secondary_bg_color instead.
+
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()
@@ -329,7 +342,7 @@
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]) NEW
+
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.
@@ -379,6 +392,16 @@
Bot API 6.4+ A method that requests text from the clipboard. The Mini App will receive the eventclipboardTextReceived. 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]) NEW
+
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]) NEW
+
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.
@@ -683,6 +706,50 @@
All these methods return the HapticFeedback object so they can be chained.
+
CloudStorage
+
NEW 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.
@@ -715,12 +782,12 @@
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 NEW
+
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 NEW
+
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.
@@ -790,7 +857,17 @@
is_premium
True
-
Optional. True, if this user is a Telegram Premium user
+
Optional. True, if this user is a Telegram Premium user.
+
+
+
added_to_attachment_menu NEW
+
True
+
Optional. True, if this user added the bot to the attachment menu.
+
+
+
allows_write_to_pm NEW
+
True
+
Optional. True, if this user allowed the bot to message them.
photo_url
@@ -895,6 +972,14 @@ if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
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.
+
+
writeAccessRequestedNEW
+
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.
+
+
+
contactRequestedNEW
+
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
diff --git a/data/web/corefork.telegram.org/bots/webapps.html b/data/web/corefork.telegram.org/bots/webapps.html
index 0eddb099a6..7bb117f3f2 100644
--- a/data/web/corefork.telegram.org/bots/webapps.html
+++ b/data/web/corefork.telegram.org/bots/webapps.html
@@ -2,12 +2,12 @@
- Web Apps for Bots
+ Telegram Mini Apps
-
-
+
+
-
+
@@ -39,13 +39,13 @@
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 (mini 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.
+
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 Web App in action, try our sample @DurgerKingBot.
+
To see a Mini App in action, try our sample @DurgerKingBot.
Recent changes
-
September XX, 2023
+
September 14, 2023
Bot API 6.9
Added the ability to set any header color using the setHeaderColor method.
-
Added the field CloudStorage and the methods requestWriteAccess, requestContact to the class WebApp.
+
Added the field CloudStorage and the methods requestWriteAccess, requestContact to the class WebApp.
Added the fields added_to_attachment_menu, allows_write_to_pm to the class WebAppUser.
Added the events writeAccessRequested, contactRequested.
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.
+
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 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 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.
@@ -89,16 +89,16 @@
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 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 eventsbackButtonClicked, settingsButtonClicked, invoiceClosed.
+
Added the eventsbackButtonClicked, settingsButtonClicked, invoiceClosed.
-
Designing Web Apps
+
Designing Mini 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.
+
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.