@tma.js/bridge

The lowest level communication layer between a Telegram Mini App and the Telegram client.

This package provides typed functions to call Mini Apps methods, listen to Mini Apps events, retrieve launch parameters and imitate the Telegram client during development. It works together with the official SDK (telegram-web-app.js) loaded on the same page: neither of them breaks the other one.

Higher-level package

While a developer can use this package alone, it's recommended to use a higher-level package like @tma.js/sdk.

Installation

pnpm

pnpm i @tma.js/bridge

npm

npm i @tma.js/bridge

yarn

yarn add @tma.js/bridge

CDN

The package also has a self-contained IIFE build, which can be loaded via a <script> tag. It exposes the package as the tmajs.bridge global:

<script src="https://cdn.jsdelivr.net/npm/@tma.js/bridge@4/dist/index.iife.js"></script>
<script>
  tmajs.bridge.postEvent('web_app_ready');
</script>

Prefer installing the package via a package manager when you use a bundler: the IIFE build includes all the dependencies and can't be tree-shaken.

Usage

Here's a basic example of how to use this package. For more details, refer to the next articles in the documentation.

import { onEvent, postEvent } from '@tma.js/bridge';

// Show the back button, wait for it to be clicked once,
// then hide it.
postEvent('web_app_setup_back_button', { is_visible: true });

onEvent('back_button_pressed', () => {
  postEvent('web_app_setup_back_button', { is_visible: false });
}, { once: true });

What's Next

• Methods: calling Mini Apps methods and checking their support.
• Events: listening to Mini Apps events.
• Launch Parameters: retrieving launch parameters, init data and the start parameter.
• Environment: detecting Telegram and mocking it during development.
• Globals: debug mode, logger and target origin.
• Advanced: calling a method and waiting for an event, invoking custom methods.
• Handling Errors: the safe functions and the errors the package produces.

Upgrading from the previous major version? Follow the migration guide.