Telegram Mini Apps@tma.js/bridge
The package provides utilities to simplify communication between web applications and the Telegram native application. It also addresses cross-platform data differences, safeguarding developers' code and saving their time.
Developers can utilize this package to create their software development kit (SDK), as it offers the utmost level of control over cross-application communication.
Installation
pnpm i @tma.js/bridgepnpm i @tma.js/bridgenpm i @tma.js/bridgenpm i @tma.js/bridgeyarn add @tma.js/bridgeyarn add @tma.js/bridgeCalling methods
To call the Telegram Mini Apps methods, you should use postEvent function:
import { postEvent } from '@tma.js/bridge';
postEvent('web_app_setup_back_button', { is_visible: true });import { postEvent } from '@tma.js/bridge';
postEvent('web_app_setup_back_button', { is_visible: true });This function automatically finds the correct way to send this event based on the current environment features. For greater accuracy, it determines the current Telegram application type and selects the appropriate flow.
Listening to events
on and off
To start working with events, we could use on and off functions. Here is how basic on function usage looks like:
import { on } from '@tma.js/bridge';
// Start listening to "viewport_changed" event. Returned value
// is a function, which removes this event listener.
const removeListener = on('viewport_changed', payload => {
console.log('Viewport changed:', payload);
});
// Remove this event listener.
removeListener();import { on } from '@tma.js/bridge';
// Start listening to "viewport_changed" event. Returned value
// is a function, which removes this event listener.
const removeListener = on('viewport_changed', payload => {
console.log('Viewport changed:', payload);
});
// Remove this event listener.
removeListener();To stop listening to events, you could alternatively use off function:
import { on, off, EventListener } from '@tma.js/bridge';
const listener: EventListener<'viewport_changed'> = payload => {
console.log('Viewport changed:', payload);
};
// Start listening to event.
on('viewport_changed', listener);
// Remove event listener.
off('viewport_changed', listener);import { on, off, EventListener } from '@tma.js/bridge';
const listener: EventListener<'viewport_changed'> = payload => {
console.log('Viewport changed:', payload);
};
// Start listening to event.
on('viewport_changed', listener);
// Remove event listener.
off('viewport_changed', listener);subscribe and unsubscribe
To listen to all events sent from the native Telegram application, we utilize such functions as subscribe and unsubscribe:
import { subscribe, unsubscribe, GlobalEventListener } from '@tma.js/bridge';
const listener: GlobalEventListener = (event, data) => {
console.log('Received event', event, 'with data', data);
};
// Listen to all events.
subscribe(listener);
// Remove this listener.
unsubscribe(listener);import { subscribe, unsubscribe, GlobalEventListener } from '@tma.js/bridge';
const listener: GlobalEventListener = (event, data) => {
console.log('Received event', event, 'with data', data);
};
// Listen to all events.
subscribe(listener);
// Remove this listener.
unsubscribe(listener);Checking method support
postEvent function itself is not checking if specified method supported by current native Telegram application. To do this, we could use supports function which accepts Telegram Mini Apps method name and current platform version:
import { supports } from '@tma.js/bridge';
supports('web_app_trigger_haptic_feedback', '6.0'); // false
supports('web_app_trigger_haptic_feedback', '6.1'); // trueimport { supports } from '@tma.js/bridge';
supports('web_app_trigger_haptic_feedback', '6.0'); // false
supports('web_app_trigger_haptic_feedback', '6.1'); // trueThe supports function also allows checking if specified parameter in method parameters is supported:
import { supports } from '@tma.js/bridge';
supports('web_app_open_link', 'try_instant_view', '6.0'); // false
supports('web_app_open_link', 'try_instant_view', '6.7'); // trueimport { supports } from '@tma.js/bridge';
supports('web_app_open_link', 'try_instant_view', '6.0'); // false
supports('web_app_open_link', 'try_instant_view', '6.7'); // trueTIP
It is recommended to use this function before calling Telegram Mini Apps methods to prevent applications from stalling and other unexpected behavior.
Creating safer postEvent
This package includes a function named createPostEvent that takes the current Telegram Mini Apps version as input. It returns the postEvent function, which internally checks if the specified method and parameters are supported. If they are not, the function will throw an error.
import { createPostEvent } from '@tma.js/bridge';
const postEvent = createPostEvent('6.5');
// Will work fine.
postEvent('web_app_read_text_from_clipboard');
// Will throw an error.
postEvent('web_app_request_phone');import { createPostEvent } from '@tma.js/bridge';
const postEvent = createPostEvent('6.5');
// Will work fine.
postEvent('web_app_read_text_from_clipboard');
// Will throw an error.
postEvent('web_app_request_phone');It is highly recommended to use this postEvent generator to ensure that method calls work as expected.
Debugging
Package supports enabling the debug mode, which leads to logging messages related to events handling. To change debug mode, use setDebug function:
import { setDebug } from '@tma.js/bridge';
setDebug(true);import { setDebug } from '@tma.js/bridge';
setDebug(true);Target origin
If the package is being used in a browser environment (iframe), we employ the function window.parent.postMessage. This function requires specifying the target origin to ensure events are only sent to trusted parent iframes. By default, the package utilizes https://web.telegram.org as the origin. To enable event transmission to other origins, you should utilize the setTargetOrigin function:
import { setTargetOrigin } from '@tma.js/bridge';
setTargetOrigin('https://myendpoint.org');import { setTargetOrigin } from '@tma.js/bridge';
setTargetOrigin('https://myendpoint.org');WARNING
It is strongly recommended not to override this value as long as it could lead to security issues. Specify this value only for test purposes.
Higher-level control
As long as the package provides only low-level control, we recommend using SDK which implements package methods. It also provides additional some automatic parameters checks, more intuitive method names, and easier usage.