Mini Apps Integration

Official Telegram Mini Apps Documentation

Field Mapping

Field	Composable
initData	useWebApp
initDataUnsafe	useWebApp
version	useWebApp
platform	useWebApp
colorScheme	useWebAppTheme
themeParams	useWebAppTheme
isExpanded	useWebAppViewport
viewportHeight	useWebAppViewport
viewportStableHeight	useWebAppViewport
headerColor	useWebAppTheme
backgroundColor	useWebAppTheme
isClosingConfirmationEnabled	useWebAppClosingConfirmation
isVerticalSwipesEnabled	useWebAppViewport
BackButton	useWebAppBackButton
MainButton	useWebAppMainButton
HapticFeedback	useWebAppHapticFeedback
BiometricManager	useWebAppBiometricManager
isVersionAtLeast	useWebApp
setHeaderColor	useWebAppTheme
setBackgroundColor	useWebAppTheme
enableClosingConfirmation	useWebAppClosingConfirmation
disableClosingConfirmation	useWebAppClosingConfirmation
enableVerticalSwipes	useWebAppViewport
disableVerticalSwipes	useWebAppViewport
onEvent	useWebApp
offEvent	Handled automagically 🪄
sendData	useWebApp
switchInlineQuery	useWebAppNavigation
openLink	useWebAppNavigation
openTelegramLink	useWebAppNavigation
openInvoice	useWebAppNavigation
showPopup	useWebAppPopup
showAlert	useWebAppPopup
showConfirm	useWebAppPopup
showScanQrPopup	useWebAppQrScanner
closeScanQrPopup	useWebAppQrScanner
readTextFromClipboard	useWebAppClipboard
requestWriteAccess	useWebAppRequests
requestContact	useWebAppRequests
ready	useWebApp
expand	useWebAppViewport
close	useWebApp

Event Handling

The package provides a set of functions for event handling. By convention, the name of the functions consists of the prefix on + the name of the Telegram event in camelCase. So themeChanged event turns into onThemeChanged and so on. onEvent is also available if you prefer it instead.

import { useWebAppTheme } from 'vue-tg'

const { onThemeChanged } = useWebAppTheme()

onThemeChanged(() => {
  // handle theme update
})

Mapping

Event name	Handler
themeChanged	useWebAppTheme → onThemeChanged
viewportChanged	useWebAppViewport → onViewportChanged
mainButtonClicked	useWebAppMainButton → onMainButtonClicked
backButtonClicked	useWebAppBackButton → onBackButtonClicked
settingsButtonClicked	useWebAppSettingsButton → onSettingsButtonClicked
invoiceClosed	useWebAppNavigation → onInvoiceClosed
popupClosed	useWebAppPopup → onPopupClosed
qrTextReceived	useWebAppQrScanner → onQrTextReceived
clipboardTextReceived	useWebAppClipboard → onClipboardTextReceived
writeAccessRequested	useWebAppRequests → onWriteAccessRequested
contactRequested	useWebAppRequests → onContactRequested
biometricManagerUpdated	useWebAppBiometricManager → onBiometricManagerUpdated
biometricAuthRequested	useWebAppBiometricManager → onBiometricAuthRequested
biometricTokenUpdated	useWebAppBiometricManager → onBiometricTokenUpdated

Managing event subscriptions

By default, event handlers are automatically unsubscribed when the component is unmounted. But you can unsubscribe before that if you need to:

import { useWebAppTheme } from 'vue-tg'

const { onThemeChanged } = useWebAppTheme()

const handler = onThemeChanged(() => {
  // handle theme update
})

// unsubscribe
handler.off()

You can also disable automatic unsubscribing completely:

import { useWebAppTheme } from 'vue-tg'

const { onThemeChanged } = useWebAppTheme()

const handler = onThemeChanged(
  () => {
    // handle theme update
  },
  { manual: true },  
)

// unsubscribe
handler.off()

WARNING

Please note that in manual mode, you are responsible for managing subscription. If subscription is not managed properly, it can lead to memory leaks and other issues.

Components

Alert

A component that shows message in a simple alert with a 'Close' button when is rendered.

<script lang="ts" setup>
import { Alert } from 'vue-tg'

function handleAlertClose() {
  // ...
}
</script>

<template>
  <Alert message="Hello!" @close="handleAlertClose" />
</template>

Props

Name	Type	Required	Description
message	string	true	The message to be displayed in the body of the alert popup.

Events

Name	Type	Description
close	() => void	Emits when the opened popup is closed.

BackButton

A component that enables the back button when is rendered.

<script lang="ts" setup>
import { BackButton } from 'vue-tg'

function handleBackButton() {
  // ...
}
</script>

<template>
  <BackButton @click="handleBackButton" />
</template>

Props

Name	Type	Required	Description
visible	boolean	false	Shows whether the button is visible. Set to true by default.

Events

Name	Type	Description
click	() => void	Emits when the back button is pressed.

BiometricManager

A component that init the biometric manager when is rendered.

<script lang="ts" setup>
import { BiometricManager } from 'vue-tg'
  
const handleInit = () => {
  // ...
}
</script>

<template>
  <BiometricManager @init="handleInit" />
</template>

Events

Name	Type	Description
init	() => void	Emits when the biometric manager is init.

ClosingConfirmation

A component that enables the confirmation dialog while the user is trying to close the Mini App.

<script lang="ts" setup>
import { ClosingConfirmation } from 'vue-tg'
</script>

<template>
  <ClosingConfirmation />
</template>

Confirm

A component that shows message in a simple confirmation window with 'OK' and 'Cancel' buttons when is rendered.

<script lang="ts" setup>
import { Confirm } from 'vue-tg'

function handleConfirmClose(ok: boolean) {
  // ...
}
</script>

<template>
  <Confirm message="Hello?" @close="handleConfirmClose" />
</template>

Props

Name	Type	Required	Description
message	string	true	The message to be displayed in the body of the confirm popup.

Events

Name	Type	Description
close	(ok: boolean) => void	Emits when the opened popup is closed.

ExpandedViewport

A component that expands the Mini App to the maximum available height when is rendered.

<script lang="ts" setup>
import { ExpandedViewport } from 'vue-tg'
</script>

<template>
  <ExpandedViewport />
</template>

Props

Name	Type	Required	Description
force	boolean	false	Expands the viewport despite user interaction. Disables vertical swipes if supported. Set to false by default.

MainButton

A component that enables the main button when is rendered.

<script lang="ts" setup>
import { MainButton } from 'vue-tg'

function handleMainButton() {
  // ...
}
</script>

<template>
  <MainButton @click="handleMainButton" />
</template>

Props

Name	Type	Required	Description
visible	boolean	false	Shows whether the button is visible. Set to true by default.
disabled	boolean	false	Shows whether the button is disable.
progress	boolean	false	Shows whether the button is displaying a loading indicator.
text	string	false	Current button text.
color	string	false	Current button color.
textColor	string	false	Current button text color.

Events

Name	Type	Description
click	() => void	Emits when the main button is pressed.

Popup

A component that shows a native popup when is rendered.

<script lang="ts" setup>
import { Popup } from 'vue-tg'

function handlePopupClose(buttonId: string) {
  // ...
}
</script>

<template>
  <Popup message="Hello" @close="handlePopupClose" />
</template>

Props

Name	Type	Required	Description
message	string	true	The message to be displayed in the body of the popup.
title	string	false	The text to be displayed in the popup title.
buttons	PopupButton[] ↗	false	List of buttons to be displayed in the popup.

Events

Name	Type	Description
close	(buttonId: string) => void	Emits when the opened popup is closed.

ScanQr

A component that shows a native popup for scanning a QR code when is rendered.

<script lang="ts" setup>
import { ScanQr } from 'vue-tg'

function handleScanResult(data: string) {
  // ...
}
</script>

<template>
  <ScanQr @result="handleScanResult" />
</template>

Props

Name	Type	Required	Description
text	string	false	The text to be displayed under the 'Scan QR' heading.

Events

Name	Type	Description
result	(data: string) => void	Emits when the QR code scanner catches a code with text data.

SettingsButton

A component that enables the settings button when is rendered.

<script lang="ts" setup>
import { SettingsButton } from 'vue-tg'

function handleSettingsButton() {
  // ...
}
</script>

<template>
  <SettingsButton @click="handleSettingsButton" />
</template>

Props

Name	Type	Required	Description
visible	boolean	false	Shows whether the button is visible. Set to true by default.

Events

Name	Type	Description
click	() => void	Emits when the settings button is pressed.

Composables

useWebApp

import { useWebApp } from 'vue-tg'

▸ useWebApp(): Object

Returns

Name	Type
close	() => void
initData	string
initDataUnsafe	WebAppInitData ↗
isVersionAtLeast	(version: string) => boolean
onEvent	Available Events ↗
platform	string
ready	() => void
sendData	(data: string) => void
version	string
isReady custom	Readonly<Ref<boolean>>
isPlatform custom	(name: string) => boolean
isPlatformUnknown custom	boolean
canSendData custom	boolean

useWebAppBackButton

import { useWebAppBackButton } from 'vue-tg'

▸ useWebAppBackButton(): Object

Returns

Name	Type
hideBackButton	() => void
isBackButtonVisible	Ref<boolean>
onBackButtonClicked	(eventHandler: () => void) => void
showBackButton	() => void

useWebAppBiometricManager

import { useWebAppBiometricManager } from 'vue-tg'

▸ useWebAppBiometricManager(): Object

Returns

Name	Type
isBiometricInited	Readonly<Ref<boolean>>
isBiometricAvailable	Readonly<Ref<boolean>>
biometricType	Readonly<Ref<"finger" | "face" | "unknown">>
isBiometricAccessRequested	Readonly<Ref<boolean>>
isBiometricAccessGranted	Readonly<Ref<boolean>>
isBiometricTokenSaved	Readonly<Ref<boolean>>
biometricDeviceId	Readonly<Ref<string>>
initBiometric	(callback?: () => void) => void
requestBiometricAccess	(params: BiometricRequestAccessParams, callback?: (isAccessGranted: boolean) => void) => void
authenticateBiometric	(params: BiometricAuthenticateParams, callback?: (isAuthenticated: boolean, biometricToken?: string) => void) => void
updateBiometricToken	(token: string, callback?: (applied: boolean) => void) => void
openBiometricSettings	() => void
onBiometricManagerUpdated	(eventHandler: () => void) => void
onBiometricAuthRequested	(eventHandler: OnBiometricAuthRequested)) => void
onBiometricTokenUpdated	(eventHandler: OnBiometricTokenUpdated)) => void

useWebAppClipboard

import { useWebAppClipboard } from 'vue-tg'

▸ useWebAppClipboard(): Object

Returns

Name	Type
onClipboardTextReceived	(eventHandler: OnClipboardTextReceivedCallback) => void
readTextFromClipboard	(callback?: (data: null | string) => void) => void

useWebAppClosingConfirmation

import { useWebAppClosingConfirmation } from 'vue-tg'

▸ useWebAppClosingConfirmation(): Object

Returns

Name	Type
disableClosingConfirmation	() => void
enableClosingConfirmation	() => void
isClosingConfirmationEnabled	Ref<boolean>

useWebAppCloudStorage

import { useWebAppCloudStorage } from 'vue-tg'

▸ useWebAppCloudStorage(): Object

Returns

Name	Type
getStorageItem	(key: string) => Promise<null | string>
getStorageItems	(keys: string[]) => Promise<Record<string, string>>
getStorageKeys	() => Promise<string[]>
removeStorageItem	(key: string) => Promise<null | true>
removeStorageItems	(keys: string[]) => Promise<null | true>
setStorageItem	(key: string, value: string) => Promise<null | true>

useWebAppHapticFeedback

import { useWebAppHapticFeedback } from 'vue-tg'

▸ useWebAppHapticFeedback(): Object

Returns

Name	Type
impactOccurred	(style: "light" | "medium" | "heavy" | "rigid" | "soft") => () => void
notificationOccurred	(type: "error" | "success" | "warning") => () => void
selectionChanged	() => void

useWebAppMainButton

import { useWebAppMainButton } from 'vue-tg'

▸ useWebAppMainButton(): Object

Returns

Name	Type
disableMainButton	() => void
enableMainButton	() => void
hideMainButton	() => void
hideMainButtonProgress	() => void
isMainButtonActive	Ref<boolean>
isMainButtonProgressVisible	Ref<boolean>
isMainButtonVisible	Ref<boolean>
mainButtonColor	Ref<string>
mainButtonText	Ref<string>
mainButtonTextColor	Ref<string>
onMainButtonClicked	(eventHandler: () => void) => void
setMainButtonParams	(params:MainButtonParams ↗) => void
setMainButtonText	(text: string) => void
showMainButton	() => void
showMainButtonProgress	(leaveActive?: boolean) => void

useWebAppNavigation

import { useWebAppNavigation } from 'vue-tg'

▸ useWebAppNavigation(): Object

Returns

Name	Type
onInvoiceClosed	(eventHandler:OnInvoiceClosedCallback) => void
openInvoice	(url: string, callback: (url: string, status: "paid" | "cancelled" | "failed" | "pending") => void) => void
openLink	(url: string, options?: { try_instant_view?: boolean }) => void
openTelegramLink	(url: string) => void
switchInlineQuery	(query: string, choose_chat_types?: ("users" | "bots" | "groups" | "channels")[]) => void

useWebAppPopup

import { useWebAppPopup } from 'vue-tg'

▸ useWebAppPopup(): Object

Returns

Name	Type
onPopupClosed	(eventHandler:OnPopupClosedCallback) => void
showAlert	(message: string, callback?: () => void) => void
showConfirm	(message: string, callback?: (ok: boolean) => void) => void
showPopup	(params: PopupParams, callback?: (button_id: string) => void) => void

useWebAppQrScanner

import { useWebAppQrScanner } from 'vue-tg'

▸ useWebAppQrScanner(): Object

Returns

Name	Type
showScanQrPopup	(params:ScanQrPopupParams ↗, callback?: (data: string) => void) => void
closeScanQrPopup	() => void
onQrTextReceived	(eventHandler:OnQrTextReceivedCallback) => void
onScanQrPopupClosed	() => void

useWebAppRequests

import { useWebAppRequests } from 'vue-tg'

▸ useWebAppRequests(): Object

Returns

Name	Type
onContactRequested	(eventHandler:OnContactRequestedCallback) => void
onWriteAccessRequested	(eventHandler:OnWriteAccessRequestedCallback) => void
requestContact	(callback?: (success: boolean) => void) => void
requestWriteAccess	(callback?: (success: boolean) => void) => void

useWebAppSendData custom

Useful composable for universal data sending. execute just calls sendData and executeHttp sends an HTTP POST request to the specified URL.
Use canSendData from useWebApp to check that sending data in a service message (using execute) is available.

import { useWebAppSendData } from 'vue-tg'

▸ useWebAppSendData<D>(data, options): Object

Parameters

Name	Type
data	D
options	{ serialize?: (data: D) => string }

Returns

Name	Type
error	Ref<string>
execute	() => void
executeHttp	(callbackUrl: string, { closeAfter?: boolean }) => Promise<Response>

useWebAppSettingsButton

import { useWebAppSettingsButton } from 'vue-tg'

▸ useWebAppSettingsButton(): Object

Returns

Name	Type
hideSettingsButton	() => void
isSettingsButtonVisible	Ref<boolean>
onSettingsButtonClicked	(eventHandler: () => void) => void
showSettingsButton	() => void

useWebAppTheme

import { useWebAppTheme } from 'vue-tg'

▸ useWebAppTheme(): Object

Returns

Name	Type
backgroundColor	Ref<string>
colorScheme	Readonly<Ref<"light" | "dark">>
headerColor	Ref<string>
onThemeChanged	(eventHandler: () => void) => void
setBackgroundColor	(color: string | "bg_color" | "secondary_bg_color") => void
setHeaderColor	(color: string | "bg_color" | "secondary_bg_color") => void
themeParams	Readonly<Ref<ThemeParams ↗>>

useWebAppViewport

import { useWebAppViewport } from 'vue-tg'

▸ useWebAppViewport(): Object

Returns

Name	Type
expand	() => void
isExpanded	Readonly<Ref<boolean>>
onViewportChanged	(eventHandler:OnViewportChangedCallback) => void
viewportHeight	Readonly<Ref<number>>
viewportStableHeight	Readonly<Ref<number>>
isVerticalSwipesEnabled	Ref<boolean>
enableVerticalSwipes	() => void
disableVerticalSwipes	() => void

Type Aliases

OnClipboardTextReceivedCallback

Ƭ OnClipboardTextReceivedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.data	string | null

OnContactRequestedCallback

Ƭ OnContactRequestedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.status	"sent" | "cancelled"

OnInvoiceClosedCallback

Ƭ OnInvoiceClosedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.status	"paid" | "cancelled" | "failed" | "pending"
eventData.url	string

OnPopupClosedCallback

Ƭ OnPopupClosedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.button_id	string | null

OnQrTextReceivedCallback

Ƭ OnQrTextReceivedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.data	string

OnViewportChangedCallback

Ƭ OnViewportChangedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.isStateStable	boolean

OnWriteAccessRequestedCallback

Ƭ OnWriteAccessRequestedCallback: (eventData) => void

Parameters

Name	Type
eventData	Object
eventData.status	"allowed" | "cancelled"

OnBiometricAuthRequested

Ƭ OnBiometricAuthRequested: (eventData) => void

Parameters

Name	Type
isAuthenticated	boolean
biometricToken	string | undefined

OnBiometricTokenUpdated

Ƭ OnBiometricTokenUpdated: (eventData) => void

Parameters

Name	Type
isUpdated	boolean