WebApp Methods

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

Lifecycle

ready

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

Safew.WebApp.close()

Closes the Mini App.

isVersionAtLeast

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

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

Safew.WebApp.setBackgroundColor(color)

Sets the Mini App background color.

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

setBottomBarColor

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

Safew.WebApp.enableClosingConfirmation()

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

disableClosingConfirmation

Safew.WebApp.disableClosingConfirmation()

Disables closing confirmation.

enableVerticalSwipes

Safew.WebApp.enableVerticalSwipes()

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

disableVerticalSwipes

Safew.WebApp.disableVerticalSwipes()

Disables vertical swipe gestures. Bot API 7.7+

requestFullscreen

Safew.WebApp.requestFullscreen()

Requests fullscreen mode. Bot API 8.0+

exitFullscreen

Safew.WebApp.exitFullscreen()

Exits fullscreen mode. Bot API 8.0+

lockOrientation

Safew.WebApp.lockOrientation()

Locks the current screen orientation. Bot API 8.0+

unlockOrientation

Safew.WebApp.unlockOrientation()

Unlocks screen orientation. Bot API 8.0+

Expand & Scroll

expand

Safew.WebApp.expand()

Expands the Mini App to its maximum available height.

requestViewport

Safew.WebApp.requestViewport()

Requests a viewport information refresh.

Data & Communication

sendData

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

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

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

openSafewLink

Safew.WebApp.openSafewLink(url)

Opens a SafeW link within the app.

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

Sharing & Social

shareToStory

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

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

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

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

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

Safew.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 sw = window.Safew.WebApp;

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

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

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

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