Miku-web-app NPM

miku-web-app

A npm module for Telegram Web App to prevent the pollution of the global scope.

General Information

You can find docs on Telegram official website

This website features several demos of the WebApp, as well as update records and API documentation.

Setup

$ npm i miku-web-app

Usage

// destructured import
import { WebView, Utils, Game, WebApp } from 'miku-web-app'
// import all exported members
import * as Telegram from 'miku-web-app'
// import default export
import Telegram from 'miku-web-app'

For the WebApp to initialize correctly, it is important to import miku-web-app before vue-router. This is because vue-router's hash mode will change the location.hash value, which can cause the WebApp to fail to initialize. If you are not using hash mode, you do not need to worry about this import order.

// main.js
import 'miku-web-app' // add this line
import router from '@/router'
import App from './App.vue'

To ensure the WebApp is initialized correctly, include a call to ready() once the page has finished loading. For example, in a Vue project you can do this in the onMounted() hook, like this:

// App.vue
<script setup lang="ts">
import { onMounted } from 'vue'
import { WebApp } from 'miku-web-app'

onMounted(() => WebApp.ready())
</script>

There are some functions (e.g. WebApp.MainButton.onClick()) that may not be triggered on some platforms. In this case, you can try adding the following code to your application:

// For Windows Phone app
window.TelegramGameProxy_receiveEvent = Telegram.Game.Proxy_receiveEvent
// App backward compatibility
window.TelegramGameProxy = Telegram.Game.Proxy

If you want to use all of the objects in the global scope, you can add the following code:

window.Telegram = {
  Utils: Telegram.Utils,
  WebView: Telegram.WebView,
  WebApp: Telegram.WebApp
}
window.TelegramWebviewProxy = Telegram.WebView.Proxy

FAQ

1. Why does Telegram Desktop WebApp not work on some website (e.g. Vite)?

The browser used by Telegram WebView depends on your computer's OS:

Windows 8.1-10: EdgeHtml
Windows 11: EdgeChromium
macOS: Cocoa WebKit
Linux: WebKitGTK

By default, Telegram uses Edge Legacy in Windows 8.1-10. This older version of the browser is unable to support newer versions ECMAScript.

There are two ways to fix this problem:

Install Microsoft Edge WebView2
Use legacy ECMAScript

If you choose to install Microsoft Edge WebView2, it is important to also let your users know to update their browsers. Telegram will attempt to use Chromium Edge on all Windows versions, and if it can't find a Chromium version, it will fall back to Edge Legacy.

If you don't have Microsoft Edge WebView2 installed, you may not be able to launch DevTools with right-click in Edge Legacy's WebView. As a consequence, debugging becomes extremely difficult.

This information via tdesktop/issues

2. Telegram.WebApp.sendData not working?

This method is only available for Web Apps launched via a Keyboard button (below the input box) not an inline keyboard button (under bot messages).

The solution can also be found on Stack Overflow.