Skip to content


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


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;

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

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, '');

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 });

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


Calling Methods

Handling all possible environments for a developer's application can be challenging. To simplify this process, the community developed the @tma.js/sdk package, which greatly eases integration.

Here's how to use it:

import { postEvent } from '@tma.js/sdk';

postEvent('web_app_set_header_color', { color_key: 'bg_color' });

You can learn more about calling methods in the package's documentation.

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.


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.

reload_supportedbooleanOptional. True, if current Mini App supports native reloading.


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


Available since: v7.2

Requests current biometry settings.


Available since: v7.2

Opens the biometric access settings for bots. Useful when you need to request biometrics access to users who haven't granted it yet.


This method can be called only in response to user interaction with the Mini App interface (e.g. a click inside the Mini App or on the main button)


Available since: v7.2

Requests permission to use biometrics.

reasonstringOptional. The text to be displayed to a user in the popup describing why the bot needs access to biometrics, 0-128 characters.


Available since: v7.2

Authenticates the user using biometrics.

reasonstringOptional. The text to be displayed to a user in the popup describing why you are asking them to authenticate and what action you will be taking based on that authentication, 0-128 characters.


Available since: v7.2

Updates the biometric token in secure storage on the device. To remove the token, pass an empty string.

tokenstringToken to store. Has max length of 1024 symbols.


Closes Mini App.


Available since: v6.4

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


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.

datastringData to send to a bot. Should not have size of more than 4096 bytes.


Expands the Mini App.


Available since: v6.9

req_idstringCurrent invocation unique identifier.
methodstringMethod name.
paramsunknownParameters according to method.


Available since: v6.1

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

slugstringInvoice unique identifier.

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

FieldTypeDescriptionAvailable since
urlstringURL to be opened by Telegram application. Should be a full path with https protocol.
try_instant_viewbooleanOptional. Link will be opened in Instant View mode if possible.v6.4


Available since: v6.2

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

titlestringThe text to be displayed in the popup title, 0-64 characters
messagestring The message to be displayed in the body of the popup, 1-256 characters
buttonsPopupButton[]List of buttons to be displayed in the popup, 1-3 buttons


idstringIdentifier of the button, 0-64 characters.
typestring Type of the button. Values:
  • default, a button with the default style
  • destructive, a button with a style that indicates a destructive action (e.g. "Remove", "Delete", etc.)
  • ok, a button with the localized text "OK"
  • close, a button with the localized text "Close"
  • cancel, a button with the localized text "Cancel"
textstring The text to be displayed on the button, 0-64 characters. Ignored when type is ok, close or cancel.


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.

textstringOptional. Text to be displayed in the QR scanner.

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.

path_fullstringShould be a value taken from the link of this format:{path_full}. Can additionally contain query parameters.


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.

req_idstringUnique request identifier. Should be any unique string to handle the generated event appropriately.


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


Available since: v6.9

Requests access to current user's phone.


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


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


Available since: v6.9

Requests write message access to current user.


Available since: v6.1

Updates the Mini App background color.

colorstringThe Mini App background color in #RRGGBB format.


Available since: v6.1

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

FieldTypeDescriptionAvailable since
color_keystringThe Mini App header color key. Could be either bg_color or secondary_bg_color.
colorstringColor in RGB format.v6.9


Available since: v6.1

Updates the Back Button settings.

is_visiblebooleanShould the Back Button be visible.


Updates current closing behavior.

need_confirmationbooleanWill user be prompted in case, an application is going to be closed.


Updates the Main Button settings.

is_visiblebooleanOptional. Should the Main Button be displayed.
is_activebooleanOptional. Should the Main Button be enabled.
is_progress_visiblebooleanOptional. Should loader inside the Main Button be displayed. Use this property in case, some operation takes time. This loader will make user notified about it.
textstringOptional. Text inside the Main Button.
colorstringOptional. The Main Button background color in #RRGGBB format.
text_colorstringOptional. The Main Button text color in #RRGGBB format.


Available since: v6.10

Updates current state of Settings Button.

is_visiblebooleanShould the Settings Button be displayed.


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.

querystring Text which should be inserted in the input after the current bot name. Max length is 256 symbols.
chat_typesstring[] List of chat types which could be chosen to send the message. Could be empty list. Values:
  • users
  • bots
  • groups
  • channels


Available since: v6.1

Generates the haptic feedback event.

typestring Type of haptic event. Values:
  • impact, when there's a collision involving UI components.
  • notification, when some action execution has been completed.
  • selection_change, when the user changes their selection.
impact_stylestring Required when type is impact. Values:
  • 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_typestring Required when type is notification. Values:
  • 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

Released under the MIT License.