Telegram Mini Apps

https://docs.telegram-mini-apps.com/
Admin
Telegram Mini Apps enables developers to build simple, flexible, native-like web applications that...
Tokens:231,405
Snippets:1,712
Trust Score:5.4
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install init-data-golang with go get

Source: https://docs.telegram-mini-apps.com/packages/init-data-golang

Install the package using the go get command. Run this in your Go module directory.

```bash
go get github.com/telegram-mini-apps/init-data-golang
```

--------------------------------

### Install @tma.js/init-data with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data

Install the package using yarn.

```bash
yarn add @tma.js/init-data
```

--------------------------------

### Install with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-svelte

Install @tma.js/sdk and @tma.js/sdk-svelte using npm.

```bash
npm i @tma.js/sdk @tma.js/sdk-svelte
```

--------------------------------

### Install @tma.js/init-data with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data

Install the package using npm.

```bash
npm i @tma.js/init-data
```

--------------------------------

### Install @tma.js/init-data with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data

Install the package using pnpm.

```bash
pnpm i @tma.js/init-data
```

--------------------------------

### Install with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-svelte

Install @tma.js/sdk and @tma.js/sdk-svelte using yarn.

```bash
yarn add @tma.js/sdk @tma.js/sdk-svelte
```

--------------------------------

### Install with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-solid

Install the package and its peer dependency @tma.js/sdk using npm.

```bash
npm i @tma.js/sdk @tma.js/sdk-solid
```

--------------------------------

### Install with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-solid

Install the package and its peer dependency @tma.js/sdk using yarn.

```bash
yarn add @tma.js/sdk @tma.js/sdk-solid
```

--------------------------------

### Install with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-solid

Install the package and its peer dependency @tma.js/sdk using pnpm.

```bash
pnpm i @tma.js/sdk @tma.js/sdk-solid
```

--------------------------------

### Install @tma.js/sdk with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk

Install the SDK using the npm package manager.

```bash
npm i @tma.js/sdk
```

--------------------------------

### Install @tma.js/init-data with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data/migrate-from-init-data-node

Removes the deprecated @tma.js/init-data-node package and installs @tma.js/init-data using npm.

```bash
npm rm @tma.js/init-data-node
npm i @tma.js/init-data
```

--------------------------------

### Install @tma.js/init-data with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data/migrate-from-init-data-node

Removes the deprecated @tma.js/init-data-node package and installs @tma.js/init-data using yarn.

```bash
yarn remove @tma.js/init-data-node
yarn add @tma.js/init-data
```

--------------------------------

### Install @tma.js/sdk with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk

Install the SDK using the pnpm package manager.

```bash
pnpm i @tma.js/sdk
```

--------------------------------

### Install @tma.js/init-data with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data/migrate-from-init-data-node

Removes the deprecated @tma.js/init-data-node package and installs @tma.js/init-data using pnpm.

```bash
pnpm rm @tma.js/init-data-node
pnpm i @tma.js/init-data
```

--------------------------------

### Install @tma.js/sdk with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk

Install the SDK using the yarn package manager.

```bash
yarn add @tma.js/sdk
```

--------------------------------

### Install with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-vue

Install @tma.js/sdk and @tma.js/sdk-vue using npm. Requires @tma.js/sdk and vue 3.2+ as peer dependencies.

```bash
npm i @tma.js/sdk @tma.js/sdk-vue
```

--------------------------------

### Example of tgWebAppThemeParams launch parameter value

Source: https://docs.telegram-mini-apps.com/platform/theming

A complete JSON example of the theme parameters provided via the tgWebAppThemeParams launch parameter. It contains optional properties describing palette colors.

```json
{
  "accent_text_color": "#6ab2f2",
  "bg_color": "#17212b",
  "button_color": "#5288c1",
  "button_text_color": "#ffffff",
  "bottom_bar_bg_color": "#ffffff",
  "destructive_text_color": "#ec3942",
  "header_bg_color": "#17212b",
  "hint_color": "#708499",
  "link_color": "#6ab3f3",
  "secondary_bg_color": "#232e3c",
  "section_bg_color": "#17212b",
  "section_header_text_color": "#6ab3f3",
  "subtitle_text_color": "#708499",
  "text_color": "#f5f5f5"
}
```

--------------------------------

### init() with custom launchParams

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/initializing

Example of passing custom launch parameters to the init function.

```APIDOC
## init() with custom launchParams

### Description
Pass `launchParams` to use specific launch parameters instead of the ones retrieved from the current environment.

### Example
```ts
import { init } from '@tma.js/sdk';

init({
  launchParams: {
    tgWebAppPlatform: 'tdesktop',
    tgWebAppVersion: '8.0',
    tgWebAppThemeParams: { bg_color: '#17212b' },
  },
});
```
```

--------------------------------

### Install with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-vue

Install @tma.js/sdk and @tma.js/sdk-vue using pnpm. Requires @tma.js/sdk and vue 3.2+ as peer dependencies.

```bash
pnpm i @tma.js/sdk @tma.js/sdk-vue
```

--------------------------------

### Install @tma.js/sdk and @tma.js/sdk-react with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/usage-tips

Use this command when your main library is React. It installs the React-specific package and its peer dependency @tma.js/sdk.

```bash
pnpm i @tma.js/sdk @tma.js/sdk-react
```

--------------------------------

### ngrok tunnel command example

Source: https://docs.telegram-mini-apps.com/platform/getting-app-link

Concrete example of the ngrok tunnel command using the static domain example.free.ngrok.app and port 5432. After the tunnel is established, users opening the Mini App are forwarded to the development server.

```bash
ngrok http --domain=example.free.ngrok.app 5432
```

--------------------------------

### Install @tma.js/sdk and @tma.js/sdk-react with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/usage-tips

Use this command when your main library is React. It installs the React-specific package and its peer dependency @tma.js/sdk.

```bash
npm i @tma.js/sdk @tma.js/sdk-react
```

--------------------------------

### Install with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-vue

Install @tma.js/sdk and @tma.js/sdk-vue using yarn. Requires @tma.js/sdk and vue 3.2+ as peer dependencies.

```bash
yarn add @tma.js/sdk @tma.js/sdk-vue
```

--------------------------------

### web_app_start_device_orientation

Source: https://docs.telegram-mini-apps.com/platform/methods

Starts tracking device orientation data with optional absolute orientation.

```APIDOC
## web_app_start_device_orientation

### Description
Starts tracking device orientation data.

### Method
web_app_start_device_orientation

### Parameters
#### Request Body
- **refresh_rate** (number) - Required - The refresh rate in milliseconds, with acceptable values ranging from 20 to 1000. Note that refresh_rate may not be supported on all platforms, so the actual tracking frequency may differ from the specified value.
- **need_absolute** (boolean) - Optional - Pass true to receive absolute orientation data, allowing you to determine the device's attitude relative to magnetic north. Use this option if implementing features like a compass in your app. If relative data is sufficient, pass false. Keep in mind that some devices may not support absolute orientation data. In such cases, you will receive relative data even if need_absolute=true is passed.

### Response
No response details provided.
```

--------------------------------

### Complete mockTelegramEnv example with launchParams and onMethod

Source: https://docs.telegram-mini-apps.com/packages/tma-js-bridge/environment

Use this example to mock the Telegram environment in your application. It sets launch parameters including theme params and init data, and intercepts method calls like web_app_request_theme and web_app_request_viewport, emitting corresponding events. The restore function stops intercepting method calls when called.

```TypeScript
import { mockTelegramEnv, emitEvent, type ThemeParams } from '@tma.js/bridge';

const noInsets = { left: 0, top: 0, bottom: 0, right: 0 };
const themeParams: ThemeParams = {
  accent_text_color: '#6ab2f2',
  bg_color: '#17212b',
  button_color: '#5288c1',
  button_text_color: '#ffffff',
  destructive_text_color: '#ec3942',
  header_bg_color: '#17212b',
  hint_color: '#708499',
  link_color: '#6ab3f3',
  secondary_bg_color: '#232e3c',
  section_bg_color: '#17212b',
  section_header_text_color: '#6ab3f3',
  subtitle_text_color: '#708499',
  text_color: '#f5f5f5',
};

const restore = mockTelegramEnv({
  launchParams: {
    tgWebAppThemeParams: themeParams,
    tgWebAppData: new URLSearchParams([
      ['user', JSON.stringify({ id: 1, first_name: 'Pavel' })],
      ['hash', ''],
      ['signature', ''],
      ['auth_date', Math.floor(Date.now() / 1000).toString()],
    ]).toString(),
    tgWebAppStartParam: 'debug',
    tgWebAppVersion: '9.1',
    tgWebAppPlatform: 'tdesktop',
  },
  onMethod({ name }, next) {
    if (name === 'web_app_request_theme') {
      return emitEvent('theme_changed', { theme_params: themeParams });
    }
    if (name === 'web_app_request_viewport') {
      return emitEvent('viewport_changed', {
        height: window.innerHeight,
        width: window.innerWidth,
        is_expanded: true,
        is_state_stable: true,
      });
    }
    if (name === 'web_app_request_content_safe_area') {
      return emitEvent('content_safe_area_changed', noInsets);
    }
    if (name === 'web_app_request_safe_area') {
      return emitEvent('safe_area_changed', noInsets);
    }
    // Pass other calls to the original transport, if any.
    next();
  },
});

// Later, to stop intercepting method calls:
restore();
```

--------------------------------

### Initialize SDK and mount back button

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk

Basic usage example: initialize the SDK, check support for the back button, mount and show it, and handle clicks to navigate back.

```ts
import { init, backButton } from '@tma.js/sdk';

// Initialize the package and configure its global dependencies.
init();

// Mount the back button component and retrieve its actual state.
if (backButton.isSupported()) {
  backButton.mount();
  backButton.show();
}

// When the user clicks the back button, go back in the navigation history.
const off = backButton.onClick(() => {
  off();
  window.history.back();
});
```

--------------------------------

### Read a computed value: backButton.isVisible()

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features

Call a computed value to get its current value. Example shows backButton.isVisible() returning false.

```ts
import { backButton } from '@tma.js/sdk';

backButton.isVisible(); // false
```

--------------------------------

### Get complete component state: mainButton.state()

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features

Stateful components have a state computed value containing the complete component state. Example shows mainButton.state() returning an object with text and visibility.

```ts
import { mainButton } from '@tma.js/sdk';

mainButton.state(); // { text: 'Continue', isVisible: false, ... }
```

--------------------------------

### After: init with launchParams

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/migrate-from-v3

Shows the new way of initializing the SDK by passing complete launch parameters in the launchParams option.

```ts
import { init } from '@tma.js/sdk';

init({
  launchParams: {
    tgWebAppPlatform: 'tdesktop',
    tgWebAppVersion: '8.0',
    tgWebAppBotInline: false,
    tgWebAppThemeParams: { bg_color: '#17212b' },
  },
});
```

--------------------------------

### Access Safe Area Insets

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features/viewport

Use `viewport.safeAreaInsets()` and `viewport.contentSafeAreaInsets()` to get objects with numeric properties `top`, `bottom`, `left`, and `right`. The example shows typical values for a device with a bottom inset and a fullscreen header.

```TypeScript
// Objects with numeric properties "top", "bottom", "left" and "right".
viewport.safeAreaInsets(); // { top: 0, bottom: 34, left: 0, right: 0 }
viewport.contentSafeAreaInsets(); // { top: 46, bottom: 0, left: 0, right: 0 }

viewport.safeAreaInsets().top; // 0
```

--------------------------------

### Before: init with removed options

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/migrate-from-v3

Shows the old way of initializing the SDK with version, isInlineMode, and themeParams options, which are now removed.

```ts
import { init } from '@tma.js/sdk';

init({
  version: '8.0',
  isInlineMode: false,
  themeParams: { bg_color: '#17212b' },
});
```

--------------------------------

### init()

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/initializing

Initializes the SDK by retrieving launch parameters, creating a postEvent function, and handling Telegram Web events. Returns a cleanup function.

```APIDOC
## init()

### Description
Initializes the @tma.js/sdk package. Must be called before using any SDK functions or components. It retrieves launch parameters, creates a postEvent function, and starts handling Telegram Web events. Returns a cleanup function that removes added event listeners and styles.

### Method
init

### Signature
```ts
init(options?: InitOptions): () => void
```

### Parameters
#### Options (optional)
- **acceptCustomStyles** (boolean) - Optional - Apply styles sent by Telegram Web clients. Default: `true`.
- **launchParams** (LaunchParams) - Optional - Launch parameters to use. Default: Launch parameters retrieved with the `retrieveLaunchParams` function.
- **postEvent** (PostEventFn) - Optional - Function calling Mini Apps methods. Default: A function created with `createPostEvent` for the current Mini Apps version. It throws `MethodUnsupportedError` and `MethodParameterUnsupportedError` on unsupported calls.

### Return Value
Returns a cleanup function that removes added event listeners and styles. Calling `init` again performs this cleanup for the previous call first.

### Example
```ts
import { init } from '@tma.js/sdk';

const cleanup = init();
// ...
cleanup();
```

### Notes
- The `postEvent` function passed to `init` is used only by the SDK components and functions. The `postEvent`, `request` and `invokeCustomMethod` functions re-exported from the bridge don't use it. If you need them to use a specific `postEvent` function, pass it in their options.

### Errors
- Throws `NotInitializedError` if SDK functions or component methods are used before calling `init`.
```

--------------------------------

### useRawLaunchParams example

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-react

Shows how to retrieve launch parameters in raw format using useRawLaunchParams. The value is computed once on first render.

```tsx
import { useRawLaunchParams } from '@tma.js/sdk-react';

function Component() {
  console.log(useRawLaunchParams());
  // 'tgWebAppBotInline=0&tgWebAppData=user%3D...&tgWebAppPlatform=tdesktop&...'
}
```

--------------------------------

### useLaunchParams example

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-react

Shows how to retrieve launch parameters using useLaunchParams. It throws LaunchParamsRetrieveError if parameters are not found, and the value is computed once on first render.

```tsx
import { useLaunchParams } from '@tma.js/sdk-react';

function Component() {
  console.log(useLaunchParams());
  // {
  //   tgWebAppBotInline: false,
  //   tgWebAppData: 'user=%7B%22id%22%3A...&auth_date=...&hash=...',
  //   tgWebAppPlatform: 'tdesktop',
  //   tgWebAppThemeParams: { bg_color: '#17212b', ... },
  //   tgWebAppVersion: '8.0',
  //   ...
  // }
}
```

--------------------------------

### Install @tma.js/bridge with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-bridge

Install the package using yarn.

```bash
yarn add @tma.js/bridge
```

--------------------------------

### Initialize SDK and mount BackButton

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-solid

Initialize the SDK, mount the Back Button, and render the application. This is the entry point for using the package.

```tsx
import { render } from 'solid-js/web';
import { init, backButton } from '@tma.js/sdk-solid';

import { BackButton } from './BackButton.js';

// Initialize the SDK.
init();

// Mount the Back Button, so it works with its actual state.
backButton.mount();

render(() => <BackButton/>, document.getElementById('root')!);
```

--------------------------------

### Install @tma.js/bridge with npm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-bridge

Install the package using npm.

```bash
npm i @tma.js/bridge
```

--------------------------------

### Install @tma.js/bridge with pnpm

Source: https://docs.telegram-mini-apps.com/packages/tma-js-bridge

Install the package using pnpm.

```bash
pnpm i @tma.js/bridge
```

--------------------------------

### Sign init data with initdata.SignQueryString and initdata.Sign

Source: https://docs.telegram-mini-apps.com/packages/init-data-golang

Signs init data using a bot token and auth date. SignQueryString parses the query string, while Sign takes a map. Both remove hash and auth_date parameters. The console should show the same results for both.

```go
package main

import (
	"fmt"
	"time"

	initdata "github.com/telegram-mini-apps/init-data-golang"
)

func main() {
	// Init data in raw format.
	initData := "user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%20%2B%20-%20%3F%20%5C%2F%22%2C%22last_name%22%3A%22Kibenko%22%2C%22username%22%3A%22vdkfrost%22%2C%22language_code%22%3A%22ru%22%2C%22is_premium%22%3Atrue%2C%22allows_write_to_pm%22%3Atrue%2C%22photo_url%22%3A%22https%3A%5C%2F%5C%2Ft.me%5C%2Fi%5C%2Fuserpic%5C%2F320%5C%2F4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg%22%7D&chat_instance=8134722200314281151&chat_type=private&auth_date=1733509682&signature=TYJxVcisqbWjtodPepiJ6ghziUL94-KNpG8Pau-X7oNNLNBM72APCpi_RKiUlBvcqo5L-LAxIc3dnTzcZX_PDg&hash=a433d8f9847bd6addcc563bff7cc82c89e97ea0d90c11fe5729cae6796a36d73"

	// Telegram Bot secret key.
	token := "7342037359:AAHI25ES9xCOMPokpYoz-p8XVrZUdygo2J4"

	// Signing timestamp.
	// Here we took the value from the initData variable
	// above (auth_date query parameter).
	authDate := time.Unix(1733509682, 0)

	// Signing query parameters.
	// Returned values:
	// 1. Parameters sign result ("hash" init data property).
	// 2. Error occurring while parsing query string as query parameters.
	fmt.Println(initdata.SignQueryString(initData, token, authDate))

	// Signing the same query parameters presented as a map.
	fmt.Println(initdata.Sign(map[string]string{
		"user":          "{\"id\":279058397,\"first_name\":\"Vladislav + - ? \\\/\",\"last_name\":\"Kibenko\",\"username\":\"vdkfrost\",\"language_code\":\"ru\",\"is_premium\":true,\"allows_write_to_pm\":true,\"photo_url\":\"https:\\\/\\\/t.me\\\/i\\\/userpic\\\/320\\\/4FPEE4tmP3ATHa57u6MqTDih13LTOiMoKoLDRG4PnSA.svg\"}",
		"chat_instance": "8134722200314281151",
		"chat_type":     "private",
		"signature":     "TYJxVcisqbWjtodPepiJ6ghziUL94-KNpG8Pau-X7oNNLNBM72APCpi_RKiUlBvcqo5L-LAxIc3dnTzcZX_PDg",
	}, token, authDate))

	// In the console, you should see the same results.
}

```

--------------------------------

### web_app_setup_main_button

Source: https://docs.telegram-mini-apps.com/platform/methods

Updates the Main Button settings.

```APIDOC
## web_app_setup_main_button

### Description
Updates the Main Button settings.

### Method
web_app_setup_main_button

### Parameters
#### Request Body
- **is_visible** (boolean) - Optional - Should the button be displayed.
- **is_active** (boolean) - Optional - Should the button be enabled.
- **is_progress_visible** (boolean) - Optional - Should loader inside the button be displayed. Use this property in case, some operation takes time. This loader will make user notified about it.
- **text** (string) - Optional - Text inside the button.
- **color** (string) - Optional - The button background color in `#RRGGBB` format.
- **text_color** (string) - Optional - The button text color in `#RRGGBB` format.
- **has_shine_effect** (boolean) - Optional - Should the button have a shining effect. Available since v7.8.
- **icon_custom_emoji_id** (string) - Optional - The ID of custom emoji icon displayed alongside button text. Available since v9.5.
```

--------------------------------

### Vite dev server startup output

Source: https://docs.telegram-mini-apps.com/platform/getting-app-link

Example console output after launching the Vite development server with host enabled. It shows the Local and Network URLs, where the Network link is used for devices on the same network.

```bash
  VITE v5.2.12  ready in 15 ms

  ➜  Local:   http://localhost:5173
  ➜  Network: http://172.20.10.8:5173
  ➜  press h + enter to show help
```

--------------------------------

### Initialize SDK and mount Back Button (main.ts)

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-svelte

Initialize the SDK and mount the Back Button before mounting the application. Uses Svelte 5's mount API; for Svelte 3/4 use new App({ target }).

```ts
import { mount } from 'svelte';
import { init, backButton } from '@tma.js/sdk-svelte';

import App from './App.svelte';

// Initialize the SDK.
init();

// Mount the Back Button, so it works with its actual state.
backButton.mount();

mount(App, { target: document.getElementById('app')! });
```

--------------------------------

### Before: initFp with fp-ts

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/migrate-from-v3

Shows the old way of handling initialization errors using initFp and fp-ts.

```ts
import { initFp } from '@tma.js/sdk';
import { either as E, function as fn } from 'fp-ts';

fn.pipe(initFp(), E.match(
  error => console.error(error),
  cleanup => {},
));
```

--------------------------------

### Before: popup.showFp with fp-ts TaskEither

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/migrate-from-v3

Shows the old v3 approach using popup.showFp and fp-ts taskEither to handle the result. This is the 'Before' example in the BeforeAfter tab.

```ts
import { popup } from '@tma.js/sdk';
import { taskEither as TE, function as fn } from 'fp-ts';

await fn.pipe(
  popup.showFp({ message: 'Hello!' }),
  TE.match(
    error => console.error(error),
    buttonId => console.log(buttonId),
  ),
)();
```

--------------------------------

### Check and Use close.supports('returnBack')

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features/mini-app

Checks if the `close` method supports the `returnBack` argument and calls it with `true` if supported. Also shows how to check if the SDK is initialized.

```ts
miniApp.close.isSupported(); // true if the SDK is initialized

if (miniApp.close.supports('returnBack')) {
  miniApp.close(true);
}
```

--------------------------------

### Install localtunnel globally

Source: https://docs.telegram-mini-apps.com/platform/getting-app-link

Install the localtunnel package globally using npm. This is required before creating a tunnel with the lt command.

```bash
npm install -g localtunnel
```

--------------------------------

### Install @tma.js/sdk and @tma.js/sdk-react with yarn

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/usage-tips

Use this command when your main library is React. It installs the React-specific package and its peer dependency @tma.js/sdk.

```bash
yarn add @tma.js/sdk @tma.js/sdk-react
```

--------------------------------

### Install @tma.js/sdk as peer dependency

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk-svelte/migrate-from-v1

Install @tma.js/sdk alongside @tma.js/sdk-svelte because it is now a peer dependency. This ensures a single copy of the SDK, as its components are singletons with their own state.

```bash
pnpm i @tma.js/sdk @tma.js/sdk-svelte
```

--------------------------------

### Get release version with getReleaseVersion()

Source: https://docs.telegram-mini-apps.com/packages/tma-js-bridge/methods

Use `getReleaseVersion` to get the Mini Apps version a method or method parameter was released in. Returns `undefined` if the method is unknown.

```ts
import { getReleaseVersion } from '@tma.js/bridge';

getReleaseVersion('web_app_open_popup'); // '6.2'
getReleaseVersion('web_app_open_link', 'try_browser'); // '7.6'
```

--------------------------------

### tgWebAppThemeParams JSON example

Source: https://docs.telegram-mini-apps.com/platform/launch-parameters

Example of the theme parameters object that is passed as a JSON string in the tgWebAppThemeParams launch parameter. Use JSON.parse to convert it to a JavaScript object.

```typescript
const theme = {
  bg_color: '#212121',
  text_color: '#ffffff',
  hint_color: '#aaaaaa',
  link_color: '#8774e1',
  button_color: '#8774e1',
  button_text_color: '#ffffff',
  secondary_bg_color: '#0f0f0f',
};
```

--------------------------------

### web_app_setup_closing_behavior

Source: https://docs.telegram-mini-apps.com/platform/methods

Updates current closing behavior.

```APIDOC
## web_app_setup_closing_behavior

### Description
Updates current closing behavior.

### Method
web_app_setup_closing_behavior

### Parameters
#### Request Body
- **need_confirmation** (boolean) - Required - Will user be prompted in case, an application is going to be closed.
```

--------------------------------

### safeValidate3rd and isValid3rd: Error handling and boolean check

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data/validating

Use safeValidate3rd to get a result object instead of throwing, and isValid3rd to get a boolean. Note that isValid3rd does not check the init data structure, similar to isValid.

```TypeScript
import { isValid3rd, safeValidate3rd } from '@tma.js/init-data';

const result = await safeValidate3rd(rawInitData, 7342037359);
if (!result.ok) {
  console.error(result.error.name);
}

if (await isValid3rd(rawInitData, 7342037359)) {
  console.log('Init data signature is fine');
}
```

--------------------------------

### init with custom launchParams

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/initializing

Passes specific launch parameters instead of retrieving them from the environment. Useful for testing or custom environments.

```ts
import { init } from '@tma.js/sdk';

init({
  launchParams: {
    tgWebAppPlatform: 'tdesktop',
    tgWebAppVersion: '8.0',
    tgWebAppThemeParams: { bg_color: '#17212b' },
  },
});
```

--------------------------------

### openSettings()

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features/location-manager

Opens the location settings. Use it when the user denied access but the mini app needs it. Call it only in response to user interaction. The method doesn't require the component to be mounted.

```APIDOC
## openSettings()

### Description
Opens the location settings. Use it when the user denied access but the mini app needs it. Call it only in response to user interaction. The method doesn't require the component to be mounted.

### Method
openSettings

### Parameters
None

### Request Example
```ts
locationManager.openSettings();
```

### Response
No return value.
```

--------------------------------

### Get hash

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features/init-data

Returns the init data signature.

```TypeScript
initData.hash(); // 'abcedef123'
```

--------------------------------

### Decode start parameter with decodeStartParam

Source: https://docs.telegram-mini-apps.com/packages/tma-js-bridge/launch-parameters

Decodes a start parameter retrieved from launch parameters. Pass 'json' as the second argument to parse the decoded value as JSON, or provide a custom parser. Throws if the value is not a valid base64url string or if the parser throws.

```TypeScript
import { decodeStartParam, retrieveLaunchParams } from '@tma.js/bridge';

const { tgWebAppStartParam } = retrieveLaunchParams();
if (tgWebAppStartParam) {
  decodeStartParam(tgWebAppStartParam); // '{"page":"product","id":42}'
  decodeStartParam(tgWebAppStartParam, 'json'); // { page: 'product', id: 42 }
  decodeStartParam(tgWebAppStartParam, value => value.length); // 26
}
```

--------------------------------

### Get canSendAfterDate

Source: https://docs.telegram-mini-apps.com/packages/tma-js-sdk/features/init-data

Returns canSendAfter as a Date, calculated from authDate.

```TypeScript
initData.canSendAfterDate(); // Date(1727372494000)
```

--------------------------------

### Fetch API server with safeValidate()

Source: https://docs.telegram-mini-apps.com/packages/tma-js-init-data

Complete HTTP server example for Bun, Deno, or Cloudflare Workers. Expects init data in the Authorization header in the 'tma <init data>' format. Uses safeValidate with a 1-hour expiration and returns 401 on failure.

```TypeScript
import { safeValidate } from '@tma.js/init-data';

// Your secret bot token.
const botToken = '1234567890:ABC';

export default {
  async fetch(request: Request): Promise<Response> {
    const [authType, authData = ''] = (request.headers.get('authorization') || '').split(' ');
    if (authType !== 'tma') {
      return new Response('Unauthorized', { status: 401 });
    }

    // We consider init data valid for 1 hour since its creation.
    const result = await safeValidate(authData, botToken, { expiresIn: 3600 });
    if (!result.ok) {
      return new Response(result.error.message, { status: 401 });
    }
    return Response.json(result.data);
  },
};
```
Tokens:
Raw