Methods ​

Telegram Mini Apps methods are events, which execute some predefined action. They are always called by a Mini App.

Web ​

As long as the web version of Telegram displays the front-end application in <iframe/> tag, it uses the default way of communication between 2 iframes - sending messages through window.parent.postMessage function.

As the first parameter, you should pass a JSON object converted to a string. The object should have this interface:

interface MessageJSON {
  eventType: string;
  eventData: any;
}

interface MessageJSON {
  eventType: string;
  eventData: any;
}

The second parameter is targetOrigin - allowed parent iframe origin. We recommend avoiding the usage of wildcard * as long as it is not secure - your application could be inserted not by Telegram, but by another iframe that will still be able to communicate with your app and receive some data.

As a default value, you could use https://web.telegram.org.

So, as you see, each method has its own name expressed by eventType and parameters stored in eventData property. Here is the usage example:

const data = JSON.stringify({
  eventType: 'web_app_setup_back_button',
  eventData: {
    is_visible: true,
  },
});

window.parent.postMessage(data, 'https://web.telegram.org');

const data = JSON.stringify({
  eventType: 'web_app_setup_back_button',
  eventData: {
    is_visible: true,
  },
});

window.parent.postMessage(data, 'https://web.telegram.org');

This code will make the Telegram BackButton appear.

Desktop and mobile ​

Unlike the web, desktop and mobile applications use a bit more unusual way of calling methods. Both of these platforms will create a global function window.TelegramWebviewProxy.postEvent.

As the first argument, this function accepts the event name. The second one - the parameters object, converted to a string. Here is how it works:

const data = JSON.stringify({ is_visible: true });

window
  .TelegramWebviewProxy
  .postEvent('web_app_setup_back_button', data);

const data = JSON.stringify({ is_visible: true });

window
  .TelegramWebviewProxy
  .postEvent('web_app_setup_back_button', data);

Windows Phone ​

Telegram Windows Phone app provides such function as window.external.notify. It accepts the same parameter as the web version does:

const data = JSON.stringify({
  eventType: 'web_app_setup_back_button',
  eventData: { is_visible: true },
});

window.external.notify(data);

const data = JSON.stringify({
  eventType: 'web_app_setup_back_button',
  eventData: { is_visible: true },
});

window.external.notify(data);

Available methods ​

This section contains a list of available methods to call with their names, description, and parameters. In case, Mini App does not satisfy the minimal method version requirement, nothing will happen. The native app just doesn't know which method should be called as long as it is not defined internally.

iframe_ready ​

Notifies parent iframe about the current frame is ready. This method is only used in the Web version of Telegram. As a result, Mini App will receive set_custom_style event.

iframe_will_reload ​

Notifies parent iframe about the current iframe is going to reload.

web_app_close ​

Closes Mini App.

web_app_close_scan_qr_popup ​

Available since: v6.4

Closes a QR scanner. The Telegram application creates the scan_qr_popup_closed event.

web_app_data_send ​

Sends data to the bot. When this method is called, a service message is sent to the bot containing the data of the length up to 4096 bytes. Then, Mini App will be closed.

To get more information, take a look at web_app_data field in the class Message.

web_app_expand ​

Expands the Mini App.

web_app_invoke_custom_method ​

Available since: v6.9

web_app_open_invoice ​

Available since: v6.1

Opens an invoice by its specified slug. More information about invoices in this documentation.

web_app_open_link ​

Opens link in the default browser. Mini App will not be closed.

web_app_open_popup ​

Available since: v6.2

Opens a new popup. When user closes the popup, Telegram creates the popup_closed event.

PopupButton ​

web_app_open_scan_qr_popup ​

Available since: v6.4

Opens a QR scanner. When the scanner was closed, the Telegram application creates the scan_qr_popup_closed event. When the scanner reads QR, Telegram creates the qr_text_received event.

web_app_open_tg_link ​

Available since: v6.1

Opens the Telegram link by its pathname and query parameters. The link will be opened in the Telegram app, Mini App will be closed.

web_app_read_text_from_clipboard ​

Available since: v6.4

Reads text from the clipboard. The method accepts a request identifier which is used to appropriately retrieve the method execution result from the clipboard_text_received event.

web_app_ready ​

Notifies Telegram about current application is ready to be shown. This method will make Telegram to remove application loader and display Mini App.

web_app_request_phone ​

Available since: v6.9

Requests access to current user's phone.

web_app_request_theme ​

Requests current theme from Telegram. As a result, Telegram will create theme_changed event.

web_app_request_viewport ​

Requests current viewport information from Telegram. As a result, Telegram will create viewport_changed event.

web_app_request_write_access ​

Available since: v6.9

Requests write message access to current user.

web_app_set_background_color ​

Available since: v6.1

Updates the Mini App background color.

web_app_set_header_color ​

Available since: v6.1

Updates the Mini App header color. This method should accept color_key or color property.

web_app_setup_back_button ​

Available since: v6.1

Updates the Back Button settings.

web_app_setup_closing_behavior ​

Updates current closing behavior.

web_app_setup_main_button ​

Updates the Main Button settings.

web_app_setup_settings_button ​

Available since: v6.10

Updates current state of Settings Button.

web_app_switch_inline_query ​

Available since: v6.7

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. 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.

web_app_trigger_haptic_feedback ​

Available since: v6.1

Generates the haptic feedback event.