Bot web apps can be themed according to the following theme parameters, passed as a JSON object to the theme_params parameter of the messages.requestSimpleWebView and messages.requestWebView methods.
This JSON object has the the following keys, containing color theme information (hex string, RGB24) to pass to the web app:
bg_color - Background color secondary_bg_color - Secondary background color (layer 143+) text_color - Text color hint_color - Hint text color link_color - Link color button_color - Button color button_text_color - Button text colorbg_color - Background color secondary_bg_color - Secondary background color text_color - Text color hint_color - Hint text color link_color - Link color button_color - Button color button_text_color - Button text color'*'
web_app_setup_closing_behavior
Event data: a JSON object with a boolean need_confirmation.
-If equal to true, the app should require user confirmation before closing the webview, to avoid accidentally aborting a sensitive operation; otherwise no confirmation should be requested.
+If equal to true, the client should require user confirmation before closing the webview, to avoid accidentally aborting a sensitive operation; otherwise no confirmation should be requested.
web_app_set_background_color
Event data: a JSON object with a string color with a hex RGB color.
-Used to set the app background color.
+Used to set the web app background color.
web_app_set_header_color
-Event data: a JSON object with a string color with a hex RGB color.
-Used to set the app header color.
+Event data: a JSON object with a string color_key with a hex RGB color.
+Used to set the web app header color.
web_app_data_send
Event data: a JSON object with a string data field.
Used by simple webapps to send back data to the bot.
@@ -127,18 +127,22 @@ The GamingCommunication and bot web apps libraries by default will use '*'
Used to trigger haptic feedback for a user interaction in a webapp.
web_app_open_link
Event data: a JSON object with a string url field.
-Used to open a link in an external browser. The Web App will not be closed.
-Note that this method can be called only in response to the user interaction with the Web App interface (e.g. click inside the Web App or on the main button).
+Used to open a link in an external browser (or in a new tab for browser clients). The Web App will not be closed.
+Note that this method can be called only in response to the user interaction with the Web App interface (e.g. a click inside the Web App or on the main button).
+After opening the URL, further events of this type should be ignored until the user interacts again with the Web App interface (as above).
+Note that user interactions must have a TTL of 10 seconds: events of this type must be ignored if the last Web App user interaction happened more than 10 seconds ago.
web_app_open_tg_link
-Event data: a JSON object with a string path_full field, containing the path+query component of a t.me deep link.
-Used to open a t.me deep link. The Web App will be closed.
+Event data: a JSON object with a string path_full field, containing the path+query component of a t.me deep link (url = 'https://t.me' + path_full).
+Used to open a t.me deep link. The Web App must be closed.
web_app_open_invoice
Event data: a JSON object with a string slug field, containing an invoice deep link.
-Used to initiate payment of an invoice ». The Web App will not be closed.
-The payment status should be reported back to the web app using invoice_closed.
+Used to initiate payment of an invoice », by opening an invoice popup over the Web App: the Web App itself must not be closed.
+The payment status must be reported back to the web app using invoice_closed.
web_app_expand
No event payload.
-Expands the web app to the maximum available height.
+Expands the web app to the maximum available height.
+The web app must also be expanded when the user swipes up on the webview.
+This event must be ignored during a user swipe down, used to reduce the webview.
web_app_request_viewport
No event payload.
Used by web apps to request information about the viewport, clients should emit a viewport_changed event
@@ -147,7 +151,8 @@ The GamingCommunication and bot web apps libraries by default will use '*'
Used by web apps to request information about the current theme, clients should emit a theme_changed event.
web_app_ready
No event payload.
-Emitted by web apps when they are fully loaded.
+Emitted by web apps when they are fully loaded, signaling to client apps that the loading spinner placeholder can be removed.
+Note that there is no guarantee that this event will be emitted when the web app is fully loaded: clients should remove the loading spinner upon receiving this event or when the page finishes loading (native webview/iframe event), whichever event comes first.
web_app_setup_main_button
Event payload: JSON object with the following fields: