WebApp Methods

The window.Telegram.WebApp object provides the following methods to control Mini App behavior and interactions.

Lifecycle

ready

Telegram.WebApp.ready()

Notifies the client that the Mini App is ready to be displayed. Should be called as early as possible after the page has loaded.

close

Telegram.WebApp.close()

Closes the Mini App.

isVersionAtLeast

Telegram.WebApp.isVersionAtLeast(version)

Checks if the current client version meets the requirement.

Parameter	Type	Required	Description
version	String	Yes	Minimum required version, e.g., "7.10"

Returns: Boolean

UI Control

setHeaderColor

Telegram.WebApp.setHeaderColor(color)

Sets the Mini App header bar color.

Parameter	Type	Required	Description
color	String	Yes	Color keyword (bg_color, secondary_bg_color) or hex color value

setBackgroundColor

Telegram.WebApp.setBackgroundColor(color)

Sets the Mini App background color.

Parameter	Type	Required	Description
color	String	Yes	Color keyword or hex color value

setBottomBarColor

Telegram.WebApp.setBottomBarColor(color)

Sets the bottom bar color. Bot API 7.10+

Parameter	Type	Required	Description
color	String	Yes	Color keyword or hex color value

enableClosingConfirmation

Telegram.WebApp.enableClosingConfirmation()

Enables closing confirmation. When enabled, a confirmation dialog will appear when the user tries to close the Mini App.

disableClosingConfirmation

Telegram.WebApp.disableClosingConfirmation()

Disables closing confirmation.

enableVerticalSwipes

Telegram.WebApp.enableVerticalSwipes()

Enables vertical swipe gestures, allowing the user to close or minimize the Mini App by swiping down. Bot API 7.7+

disableVerticalSwipes

Telegram.WebApp.disableVerticalSwipes()

Disables vertical swipe gestures. Bot API 7.7+

requestFullscreen

Telegram.WebApp.requestFullscreen()

Requests fullscreen mode. Bot API 8.0+

exitFullscreen

Telegram.WebApp.exitFullscreen()

Exits fullscreen mode. Bot API 8.0+

lockOrientation

Telegram.WebApp.lockOrientation()

Locks the current screen orientation. Bot API 8.0+

unlockOrientation

Telegram.WebApp.unlockOrientation()

Unlocks screen orientation. Bot API 8.0+

Expand & Scroll

expand

Telegram.WebApp.expand()

Expands the Mini App to its maximum available height.

requestViewport

Telegram.WebApp.requestViewport()

Requests a viewport information refresh.

Data & Communication

sendData

Telegram.WebApp.sendData(data)

Sends data to the Bot. After calling, the Mini App will close and the data will be sent to the Bot via a web_app_data service message.

Parameter	Type	Required	Description
data	String	Yes	Data to send, 1-4096 bytes

Note

This method is only available when the Mini App is launched via a Keyboard Button.

switchInlineQuery

Telegram.WebApp.switchInlineQuery(query, chat_types)

Switches to inline mode and inserts the inline query in the specified chat types. Bot API 6.7+

Parameter	Type	Required	Description
query	String	Yes	Inline query text to insert
chat_types	Array of String	No	Allowed chat types: "users", "bots", "groups", "channels"

Links & Navigation

openLink

Telegram.WebApp.openLink(url, options)

Opens a link in an external browser.

Parameter	Type	Required	Description
url	String	Yes	URL to open
options	Object	No	Options
options.try_instant_view	Boolean	No	Whether to try opening with Instant View

openTelegramLink

Telegram.WebApp.openTelegramLink(url)

Opens a Telegram link within the app.

Parameter	Type	Required	Description
url	String	Yes	Telegram link (https://t.me/...)

Sharing & Social

shareToStory

Telegram.WebApp.shareToStory(media_url, params)

Shares content to a story. Bot API 7.8+

Parameter	Type	Required	Description
media_url	String	Yes	Media file URL (image or video)
params	Object	No	Share parameters
params.text	String	No	Additional text description
params.widget_link	Object	No	Widget link
params.widget_link.url	String	No	Link URL
params.widget_link.name	String	No	Link display name

shareMessage

Telegram.WebApp.shareMessage(msg_id, callback)

Shares a message prepared by the Bot to a chat. Bot API 8.0+

Parameter	Type	Required	Description
msg_id	String	Yes	Message ID prepared by the Bot
callback	Function	No	Callback function with sent (Boolean) parameter indicating success

setEmojiStatus

Telegram.WebApp.setEmojiStatus(custom_emoji_id, params, callback)

Sets a custom emoji status for the user. Bot API 8.0+

Parameter	Type	Required	Description
custom_emoji_id	String	Yes	Custom emoji ID
params	Object	No	Parameters
params.duration	Integer	No	Status duration in seconds
callback	Function	No	Callback function with set (Boolean) parameter indicating success

downloadFile

Telegram.WebApp.downloadFile(params, callback)

Requests a file download. Bot API 8.0+

Parameter	Type	Required	Description
params	Object	Yes	Download parameters
params.url	String	Yes	File download URL
params.file_name	String	Yes	Suggested file name
callback	Function	No	Callback function with accepted (Boolean) parameter indicating user consent

Events

onEvent

Telegram.WebApp.onEvent(eventType, eventHandler)

Subscribes to an event. See Events for details.

Parameter	Type	Required	Description
eventType	String	Yes	Event name
eventHandler	Function	Yes	Event handler function

offEvent

Telegram.WebApp.offEvent(eventType, eventHandler)

Unsubscribes from an event.

Parameter	Type	Required	Description
eventType	String	Yes	Event name
eventHandler	Function	Yes	Previously registered event handler function

Usage Example

const tg = window.Telegram.WebApp;

// Initialize
tg.ready();
tg.expand();

// Set UI
tg.setHeaderColor('#1a1a2e');
tg.setBackgroundColor('#16213e');
tg.enableClosingConfirmation();

// Listen for theme changes
tg.onEvent('themeChanged', () => {
  console.log('Theme updated:', tg.colorScheme);
});

// Send data to Bot
tg.MainButton.setText('Submit');
tg.MainButton.onClick(() => {
  tg.sendData(JSON.stringify({ action: 'submit' }));
});
tg.MainButton.show();