Web events

When interacting with HTML5 games, websites of payment gateways and bot web apps, Telegram apps should expose APIs to allow receiving data and events from the websites.

Event APIs

Games, payment gateways and bot web apps can generate events that are meant to be received by the Telegram apps. Typically events are generated by using the postEvent method of the GamingCommunication library, or by the bot web apps library.
The postEvent function will try sending the event to the Telegram app in a number of different ways.

WebviewProxy

In mobile apps, the event receiver API should be typically exposed as a window.TelegramWebviewProxy object with a postEvent method.

window.TelegramWebviewProxy.postEvent(eventType, eventData)

window.external

Alternatively, a window.external.notify method can be exposed, accepting a string JSON payload with the event type and payload:

window.external.notify(JSON.stringify({eventType: eventType, eventData: eventData}));

postMessage API

Finally, web MTProto clients that need to open a game, open a bot web app or process a payment in an iframe can use the postMessage API to receive events from iframes.
The GamingCommunication and bot web apps libraries by default will use '*' as targetOrigin, sending messages to parent pages regardless of the origin of the embedder.

window.parent.postMessage(JSON.stringify({eventType: eventType, eventData: eventData}), targetOrigin);

Event types

eventType is a simple string indicating the event type, and eventData is a payload with an object that will be parsed by the Telegram app.

web_app_close

No event payload.

Emitted by bot web apps when the web app webview should be closed.

web_app_open_popup

Event data: a JSON object with the following fields (which should be properly validated by the client).

• title - Title for the popup (optional string, max 64 characters)
• message - Message of the popup (string, max 256 characters)
• buttons - An array of the following objects (array of 1-3 objects)
  • type - Button type (string, one of ok, close, cancel, default, destructive (in this case, the button must be red))
  • text - Button text (string, optional for ok, close and cancel types)
  • id - Button ID (unique string)

Emitted by bot web apps when to open a native pop-up over the webview.

By default, buttons should be displayed on one row.
If the web app provides two buttons that can't fit horizontally on one row, display each button on a separate row.
If the web app provides three buttons, always display each button on a separate row.

• If the user presses any of the buttons, call window.Telegram.WebView.receiveEvent("popup_closed", {"button_id": "<button id>"})
• If the user cancels the interaction without pressing any of the specified buttons, call window.Telegram.WebView.receiveEvent("popup_closed", {})

Disable handling of this event if a popup is already being displayed, re-enable handling only after the popup_closed response event is emitted.
While handling is enabled, maximum 3 consecutive valid events of this type can be handled in a timespan of 3 seconds, ignore excess events.

web_app_setup_closing_behavior

Event data: a JSON object with a boolean need_confirmation.

If equal to true, the client should require user confirmation with a "Changes that you made may not be saved." popup with "Cancel"/"Close anyway" buttons 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 web app background and lower overscroll color.

web_app_set_header_color

Event data: a JSON object with a string color_key, with of the following values:

• bg_color - The bg_color from the theme parameters should be used.
• secondary_bg_color - The secondary_bg_color from the theme parameters should be used.

Used to set the web app header and upper overscroll 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 as specified here ». The Web App will be closed.

web_app_trigger_haptic_feedback

Event data: a JSON object with the following fields:

• type - One of the following values (string):
  • impact - An impact occurred.
  • notification - A task or action has succeeded, failed, or produced a warning.
  • selection_change - The user has changed a selection.
• impact_style - Only for impact feedbacks, one of the following values (string):
  • 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
• notification_type - Only for notification feedbacks, one of the folowing values (string):
  • 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

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 (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 (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 », 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.
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.

web_app_request_theme

No event payload.

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, 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:

• is_visible - Whether the main button is visible (boolean, false by default)
• is_active - Whether the main button is active (boolean, true by default)
• text - Button text (string, if trim(text) is empty the button must be hidden)
• color - Button color in hex RGB format (string, defaults to the button_color theme parameter)
• text_color - Button text color in hex RGB format (string, defaults to the button_text_color theme parameter)
• is_progress_visible - Indicates whether the button should display a loading indicator (boolean, false by default)

Configures the main button, located immediately below the webview: when the user presses it a main_button_pressed event should be emitted by the client.

Some clients implement a horizontal media type tab bar located at the bottom of the screen, opened when the user clicks on the attachment menu button: this tab bar contains a horizontal list of buttons used to attach media of a certain type and to open installed attachment menu web apps.
In clients that implements a tab bar, iff the user opens a web app through a tab bar button and the web app emits a web_app_setup_main_button with is_visible=true, the main button should be displayed (replacing the tab bar) only after the first tap inside of the webview, to prevent bots from immediately blocking the tab bar.

Otherwise, the main button can be displayed right away with no user interaction when receiving a web_app_setup_main_button event with is_visible=true.

web_app_setup_back_button

Event data: a JSON object with an is_visible boolean field.

Determines whether to show or hide the back button: when the user presses it a back_button_pressed event should be emitted by the client.
Note that on supported platforms, the OS back button can be used instead of a custom back button: in this case, if is_visible is true pressing the OS back button should emit a back_button_pressed event, otherwise the webview should be closed.

payment_form_submit

Event payload: JSON object with credentials and title fields.

• title is the censored credit card title.
• credentials is a service-specific JSON object with information about the payment credentials provided by the user to the payment system.

Neither Telegram, nor bots will have access to your credit card information.
Credit card details will be handled only by the payment system, see the payment documentation for more info ».

share_score

No event payload.

Will be called by games when the user explicitly clicks on the share score button to share the game, along with their score.
Typically done by using messages.forwardMessages on the game message with the with_my_score flag.

share_game

No event payload.

Will be called by games when the user explicitly clicks on the share game button to share the game, without sharing their score.
Typically done by using messages.forwardMessages on the game message without the with_my_score flag, or by sharing the game's deep link.

game_over

No event payload.

Can be called by games when the user loses a game.

game_loaded

No event payload.

Can be called by games once the game fully loads.

resize_frame

Event payload: JSON object with height field.

Called by supported pages inside of IV iframe embeds, indicates the new size of the embed frame.