### Example Direct Link with startapp

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/start-parameter.md

Shows the structure of a Direct Link to a Mini App including the 'startapp' query parameter for the start parameter.

```url
https://t.me/botusername/appname?startapp=ABC
```

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

### Example Bot Link with startattach

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/start-parameter.md

Illustrates how the start parameter is appended to a bot link using the 'startattach' query parameter.

```url
https://t.me/botusername?startattach=ABC
```

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node.md

Install the package using yarn.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node.md

Install the package using npm.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node.md

Install the package using pnpm.

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

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

### Install SDK with yarn

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

Use this command to install the SDK package with yarn.

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

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

### Install SDK with pnpm

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

Use this command to install the SDK package with pnpm.

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

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

### Install SDK with npm

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

Use this command to install the SDK package with npm.

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

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

### Installation

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

Instructions for installing the @tma.js/sdk-react package using different package managers.

```APIDOC
## Installation

Before proceeding, it is assumed that you have already installed the `react` package, as it is a peer dependency of this package.

::: code-group

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

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

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

> [!INFO]
> This package fully re-exports the [@tma.js/sdk](./tma-js-sdk.md) package, so you don't need to install it separately.
```

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

### Install @tma.js/sdk

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/packages/sdk/README.md

Install the SDK using your preferred package manager.

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

# yarn
yarn add @tma.js/sdk

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

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

### Basic Usage Example

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

A simple example demonstrating how to initialize the package and mount the Back Button component.

```APIDOC
## Usage

Here is a simple usage example of the package:

:::code-group

```tsx [index.tsx]
import ReactDOM from 'react-dom/client';
import { init, backButton } from '@tma.js/sdk-react';

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

// Initialize the package.
init();

// Mount the Back Button, so we will work with 
// the actual component properties.
backButton.mount();

ReactDOM
  .createRoot(document.getElementById('root')!)
  .render(<BackButton />);
```

```ts [BackButton.ts]
import { useEffect } from 'react';
import { backButton, useSignal } from '@tma.js/sdk-react';

/**
 * Component which controls the Back Button visibility.
 */
export function BackButton() {
  const isVisible = useSignal(backButton.isVisible);

  useEffect(() => {
    console.log('The button is', isVisible ? 'visible' : 'invisible');
  }, [isVisible]);

  useEffect(() => {
    backButton.show();
    return () => {
      backButton.hide();
    };
  }, []);

  return null;
}
```

:::
```

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

### Get Start Param

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

Retrieve the value of the `startattach` or `startapp` query parameter from the launch link. This can be used to pass custom data when launching the Mini App.

```typescript
initData.startParam(); // 'my-value'
```

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

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

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

Use this command to install the package using npm.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-sdk.md

Use this command to install the SDK using npm.

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

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

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

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

Install the package using npm. Ensure you have Vue installed as a peer dependency.

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

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

### Complete Node.js Signing Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node/signing.md

A comprehensive example demonstrating how to sign init data in a Node.js environment using the `sign` method. Ensure all required fields for the init data object are provided.

```ts
import { sign } from '@tma.js/init-data-node';

sign(
  {
    can_send_after: 10000,
    chat: {
      id: 1,
      type: 'group',
      username: 'my-chat',
      title: 'chat-title',
      photo_url: 'chat-photo',
    },
    chat_instance: '888',
    chat_type: 'sender',
    query_id: 'QUERY',
    receiver: {
      added_to_attachment_menu: false,
      allows_write_to_pm: true,
      first_name: 'receiver-first-name',
      id: 991,
      is_bot: false,
      is_premium: true,
      language_code: 'ru',
      last_name: 'receiver-last-name',
      photo_url: 'receiver-photo',
      username: 'receiver-username',
    },
    start_param: 'debug',
    user: {
      added_to_attachment_menu: false,
      allows_write_to_pm: false,
      first_name: 'user-first-name',
      id: 222,
      is_bot: true,
      is_premium: false,
      language_code: 'en',
      last_name: 'user-last-name',
      photo_url: 'user-photo',
      username: 'user-username',
    },
  },
  '5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8',
  new Date(1000),
);
```

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

### Example Init Data for Third-Party Validation

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/init-data.md

This is an example of init data that should be passed directly from the mini application to the server as-is for third-party validation.

```text
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=1733584787&hash=2174df5b000556d044f3f020384e879c8efcab55ddea2ced4eb752e93e7080d6&signature=zL-ucjNyREiHDE8aihFwpfR9aggP2xiAo3NSpfe-p7IbCisNlDKlo7Kb6G4D0Ao2mBrSgEk4maLSdv6MLIlADQ
```

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

### Install @tma.js/sdk

Source: https://context7.com/telegram-mini-apps/tma.js/llms.txt

Install the main SDK package for client-side development using pnpm, npm, or yarn.

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

# Using npm
npm i @tma.js/sdk

# Using yarn
yarn add @tma.js/sdk
```

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

### Install init-data-golang Package

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/init-data-golang.md

Use this command to add the init-data-golang package to your Go project.

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

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

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

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

Use this command to install the package using yarn.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-sdk.md

Use this command to install the SDK using yarn.

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

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

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

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

Install the package using yarn. Ensure you have Vue installed as a peer dependency.

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

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

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

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

Install the package using pnpm. Ensure you have Vue installed as a peer dependency.

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

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

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

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

Use this command to install the package using pnpm.

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

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

### Desktop and Mobile Communication Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Example of calling a method using `window.TelegramWebviewProxy.postEvent` for desktop and mobile environments.

```APIDOC
## Desktop and Mobile Communication Example

### Description
This example shows how to call a method on desktop and mobile platforms using the global `window.TelegramWebviewProxy.postEvent` function.

### Method
`window.TelegramWebviewProxy.postEvent`

### Endpoint
N/A (In-app communication)

### Request Body Example
```json
{
  "is_visible": true
}
```

### Code Example
```javascript
const data = JSON.stringify({ is_visible: true });

window
  .TelegramWebviewProxy
  .postEvent('web_app_setup_back_button', data);
```
```

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-sdk.md

Use this command to install the SDK using pnpm.

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

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

### Example Parsed Init Data

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/init-data.md

This is an example of how init data should be parsed into key-value pairs, joined by '=', and sorted alphabetically, with the final array joined by linebreaks.

```text
auth_date=1662771648
query_id=AAHdF6IQAAAAAN0XohDhrOrc
user={"id":279058397,"first_name":"Vladislav","last_name":"Kibenko","username":"vdkfrost","language_code":"ru","is_premium":true}
```

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

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

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

Use this command to install the package using npm.

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

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

### Complete Web Crypto API Signing Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node/signing.md

This example demonstrates signing init data in a browser environment using the Web Crypto API via the `sign` function. Remember that this operation is asynchronous.

```typescript
import { sign } from '@tma.js/init-data-node/web';

await sign(
  {
    can_send_after: 10000,
    chat: {
      id: 1,
      type: 'group',
      username: 'my-chat',
      title: 'chat-title',
      photo_url: 'chat-photo',
    },
    chat_instance: '888',
    chat_type: 'sender',
    query_id: 'QUERY',
    receiver: {
      added_to_attachment_menu: false,
      allows_write_to_pm: true,
      first_name: 'receiver-first-name',
      id: 991,
      is_bot: false,
      is_premium: true,
      language_code: 'ru',
      last_name: 'receiver-last-name',
      photo_url: 'receiver-photo',
      username: 'receiver-username',
    },
    start_param: 'debug',
    user: {
      added_to_attachment_menu: false,
      allows_write_to_pm: false,
      first_name: 'user-first-name',
      id: 222,
      is_bot: true,
      is_premium: false,
      language_code: 'en',
      last_name: 'user-last-name',
      photo_url: 'user-photo',
      username: 'user-username',
    },
  },
  '5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8',
  new Date(1000),
);
```

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

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

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

Use this command to install the package using pnpm.

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

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

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

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

Use this command to install the package using yarn.

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

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

### Parsed Initialization Data Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/init-data.md

This is an example of parsed initialization data, showing key-value pairs joined by '=' and sorted alphabetically, with values separated by newline characters.

```text
auth_date=1733584787
chat_instance=8134722200314281151
chat_type=private
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"}
```

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

### web_app_start_device_orientation

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Starts tracking device orientation data.

```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.

### Request Example
```json
{
  "refresh_rate": 50,
  "need_absolute": true
}
```

### Response
This method does not return a value upon success.
```

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

### Example Init Data Input

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/init-data.md

These are example values for Telegram Bot Token and init data, used for understanding the validation process.

```text
5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8
```

```text
query_id=AAHdF6IQAAAAAN0XohDhrOrc&user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%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%7D&auth_date=1662771648&hash=c501b71e775f74ce10e377dea85a7ea24ecd640b223ea86dfe453e0eaed2e2b2
```

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

### Ngrok Tunnel Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/getting-app-link.md

Example command to create an ngrok tunnel for a development server running on port 5432, using a static domain 'example.free.ngrok.app'.

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

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

### Install Project Dependencies

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/CONTRIBUTING.md

Install project dependencies using pnpm. This is the only package manager supported.

```bash
pnpm i
```

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-signals.md

Use this command to install the signals package using npm.

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

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

### Track Home Screen Installation Status

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-sdk/features/home-screen.md

Listen for events related to the home screen installation status. Use `on` to subscribe and `off` to unsubscribe. Note that events may not be received if the device cannot determine the installation status.

```typescript
import { on, off } from '@tma.js/sdk';

function onAdded() {
  console.log('Added');
}

on('home_screen_added', onAdded);
off('home_screen_added', onAdded);

function onFailed() {
  console.log('User declined the request');
}

on('home_screen_failed', onFailed);
off('home_screen_failed', onFailed);
```

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

### Web Communication Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Example of sending a message to the parent iframe using `window.parent.postMessage` for web environments.

```APIDOC
## Web Communication Example

### Description
This example demonstrates how to send a message to the parent iframe in a web environment using `window.parent.postMessage`.

### Method
`window.parent.postMessage`

### Endpoint
N/A (In-page communication)

### Request Body Example
```json
{
  "eventType": "web_app_setup_back_button",
  "eventData": {
    "is_visible": true
  }
}
```

### Code Example
```javascript
const data = JSON.stringify({
  eventType: 'web_app_setup_back_button',
  eventData: {
    is_visible: true,
  },
});

window.parent.postMessage(data, 'https://web.telegram.org');
```
```

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

### web_app_start_accelerometer

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Starts tracking accelerometer data from the device.

```APIDOC
## web_app_start_accelerometer

### Description
Starts tracking accelerometer data.

### Method
`web_app_start_accelerometer`

### 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.

### Request Example
```json
{
  "refresh_rate": 100
}
```

### Response
This method does not return a value upon success.
```

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

### Initialize SDK and Handle Back Button

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-sdk.md

This example shows how to initialize the SDK, mount the back button, and add a click listener to navigate back in history. Ensure the SDK is initialized before using its components.

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

// Init the package and actualize all global dependencies.
init();

// Mount the back button component and retrieve its actual
// state.
backButton.mount();

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

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

### Data-Check String Construction

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/init-data.md

This example demonstrates the construction of a data-check string by concatenating the bot token, 'WebAppData', a newline, and the sorted initialization data.

```text
7342037359:WebAppData
auth_date=1733584787
chat_instance=8134722200314281151
chat_type=private
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"}
```

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

### Install @tma.js/bridge

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/packages/bridge/README.md

Install the package using pnpm, npm, or yarn.

```bash
pnpm i @tma.js/bridge
# or
npm i @tma.js/bridge
# or
yarn add @tma.js/bridge
```

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

### web_app_setup_main_button

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Updates the Main Button settings. All parameters are optional.

```APIDOC
## web_app_setup_main_button

### Description
Updates the Main Button settings.

### Method
Not specified (assumed to be a JavaScript function call)

### Endpoint
Not applicable (client-side JavaScript API)

### 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.

### Request Example
```javascript
Telegram.WebApp.MainButton.setParams({
  text: "Send",
  color: "#3AB6F6",
  is_active: true
});
```

### Response
#### Success Response (200)
No specific response body defined, operation is typically synchronous.

#### Response Example
```json
// No explicit response body
```
```

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

### Initialize SDK and Mount Back Button in Solid.js

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

Initializes the SDK, mounts the back button component, and renders it. Ensure 'solid-js' is installed as a peer dependency.

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

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

// Initialize the package.
init();

// Mount the Back Button, so we will work with 
// the actual component properties.
backButton.mount();

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

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

### SDK Initialization Examples

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

Provides two common ways to initialize the tma.js SDK: a basic initialization that throws an error if configuration fails, and a functional initialization.

```APIDOC
## Initialization Examples

### Throwing Initialization
This method initializes the SDK and will throw an error if the initialization process fails.

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

init();
```

### Functional Initialization
This method provides a functional approach to initializing the SDK.

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

initFp();
```
```

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-signals.md

Use this command to install the signals package using yarn.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-signals.md

Use this command to install the signals package using pnpm.

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

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

### Mounting and Unmounting the Mini App SDK

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

Demonstrates how to mount and unmount the Mini App component, including the prerequisite of mounting theme parameters.

```APIDOC
## Mounting and Unmounting

### Description
Mounts and unmounts the Mini App component. It's required to mount `themeParams` before mounting `miniApp` for proper property values.

### Method
`mount()` / `unmount()`

### Endpoint
N/A (SDK method)

### Request Example
```ts
import { miniApp, themeParams } from '@tma.js/sdk';

// Mount
themeParams.mount();
miniApp.mount();
console.log(miniApp.isMounted()); // true

// Unmount
miniApp.unmount();
console.log(miniApp.isMounted()); // false
```

### Response
#### Success Response (Mount)
- `isMounted` (boolean) - Signal indicating if the Mini App is mounted.

#### Success Response (Unmount)
- `isMounted` (boolean) - Signal indicating if the Mini App is unmounted.

#### Response Example (Mount)
```json
{
  "isMounted": true
}
```

#### Response Example (Unmount)
```json
{
  "isMounted": false
}
```
```

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-bridge.md

Use this command to install the @tma.js/bridge package using yarn.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-bridge.md

Use this command to install the @tma.js/bridge package using npm.

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

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

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

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-bridge.md

Use this command to install the @tma.js/bridge package using pnpm.

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

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

### Run Create Mini App with npm

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-create-mini-app.md

Use this command to initiate the creation of a new Telegram Mini App project using npm.

```bash
npx @tma.js/create-mini-app@latest
```

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

### web_app_setup_closing_behavior

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Updates the current closing behavior of the Mini App. User will be prompted if confirmation is needed.

```APIDOC
## web_app_setup_closing_behavior

### Description
Updates current closing behavior.

### Method
Not specified (assumed to be a JavaScript function call)

### Endpoint
Not applicable (client-side JavaScript API)

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

### Request Example
```javascript
Telegram.WebApp.enableClosingConfirmation();
```

### Response
#### Success Response (200)
No specific response body defined, operation is typically synchronous.

#### Response Example
```json
// No explicit response body
```
```

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

### Initialize SDK with Options

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-sdk/migrate-from-telegram-apps.md

The `init` function options in @tma.js/sdk have been updated. You no longer need to pass all launch parameters; only specific options like acceptCustomStyles, isInlineMode, postEvent, themeParams, and version are required.

```typescript
interface InitOptions {
  /**
   * True if SDK should accept styles sent from the Telegram
   * application.
   * @default true
   */
  acceptCustomStyles?: boolean;
  /**
   * True if the application is launched in inline mode.
   * @default Will be calculated based on the launch parameters'
   * tgWebAppBotInline field.
   */
  isInlineMode?: boolean;
  /**
   * A custom `postEvent` function to use across the package.
   * @default tma.js/bridge's postEventFp function will be used.
   */
  postEvent?: PostEventFpFn;
  /**
   * Mini application theme parameters.
   * @default Will be calculated based on the launch parameters'
   * tgWebAppThemeParams field.
   */
  themeParams?: ThemeParams;
  /**
   * Telegram Mini Apps version supported by the Telegram
   * client.
   * @default Will be calculated based on the launch parameters'
   * tgWebAppVersion field.
   */
  version?: Version;
}
```

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

### Run Vite Dev Server for Local Playground

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/CONTRIBUTING.md

Navigate to the local playground directory and run the Vite development server.

```bash
# Go to the application folder.
cd apps/local-playground

# Run Vite dev server.
pnpm run dev
```

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

### Windows Phone Communication Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Example of sending a notification using `window.external.notify` for Windows Phone environments.

```APIDOC
## Windows Phone Communication Example

### Description
This example demonstrates how to send a notification on Windows Phone using the `window.external.notify` function.

### Method
`window.external.notify`

### Endpoint
N/A (In-app communication)

### Request Body Example
```json
{
  "eventType": "web_app_setup_back_button",
  "eventData": {
    "is_visible": true
  }
}
```

### Code Example
```javascript
const data = JSON.stringify({
  eventType: 'web_app_setup_back_button',
  eventData: { is_visible: true },
});

window.external.notify(data);
```
```

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

### Initialize SDK and use BackButton component in Svelte

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

This example shows how to initialize the package and use the BackButton component. Ensure the BackButton.svelte component is correctly imported and defined.

```svelte
<script lang="ts">
  import { init, backButton } from '@tma.js/sdk-svelte';

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

  // Initialize the package.
  init();
</script>

<BackButton />
```

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

### Initialize SDK and Mount Back Button

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

Initializes the SDK and mounts the Back Button component. Mounting is required for component-related methods to work.

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

// Initialize the SDK.
init();

// Mount the Back Button component.
backButton.mount();
```

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

### Initializing the SDK

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

The `init` function configures the SDK's global dependencies. It accepts an optional `InitOptions` object to customize behavior. If not initialized, most SDK functions will not work.

```APIDOC
## POST /telegram-mini-apps/tma.js/init

### Description
Initializes the tma.js SDK by configuring its internal global dependencies. This step is crucial for the proper functioning of most SDK features.

### Method
POST

### Endpoint
/telegram-mini-apps/tma.js/init

### Parameters
#### Request Body
- **acceptCustomStyles** (boolean) - Optional - True if SDK should accept styles sent from the Telegram client. Defaults to `true`.
- **isInlineMode** (boolean) - Optional - True if the application is launched in inline mode. Defaults to calculation based on launch parameters.
- **postEvent** (PostEventFpFn) - Optional - A custom `postEvent` function to use across the package. Defaults to `tma.js/bridge`'s `postEventFp` function.
- **themeParams** (ThemeParams) - Optional - Mini application theme parameters. Defaults to calculation based on launch parameters.
- **version** (Version) - Optional - Telegram Mini Apps version supported by the Telegram client. Defaults to calculation based on launch parameters.

### Request Example
```json
{
  "acceptCustomStyles": true,
  "isInlineMode": false,
  "themeParams": {
    "bg_color": "#232629",
    "text_color": "#ffffff",
    "hint_color": "#707579",
    "link_color": "#5488ef"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the initialization status. Typically "success" upon successful initialization.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### Install Localtunnel

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/getting-app-link.md

Install the localtunnel package globally using npm. This tool provides a free alternative to ngrok for creating tunnels.

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

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

### Run Create Mini App CLI

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/packages/create-mini-app/README.md

Use these commands to initialize a new Telegram Mini App project with the CLI tool. Choose the command that corresponds to your package manager.

```bash
# npm
npx @tma.js/create-mini-app
```

```bash
# yarn
yarn create @tma.js/mini-app
```

```bash
# pnpm
pnpm dlx @tma.js/create-mini-app
```

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

### Padded Signature Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/init-data.md

This example shows the signature with necessary padding added to make it a valid base64 encoded string, as required by some programming languages.

```text
zL-ucjNyREiHDE8aihFwpfR9aggP2xiAo3NSpfe-p7IbCisNlDKlo7Kb6G4D0Ao2mBrSgEk4maLSdv6MLIlADQ==
```

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

### Initialize SDK and Mount Back Button

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

Initializes the SDK and mounts the Back Button component. Ensure this is done before rendering components that interact with the back button.

```tsx
import ReactDOM from 'react-dom/client';
import { init, backButton } from '@tma.js/sdk-react';

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

// Initialize the package.
init();

// Mount the Back Button, so we will work with 
// the actual component properties.
backButton.mount();

ReactDOM
  .createRoot(document.getElementById('root')!)
  .render(<BackButton />);

```

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

### Initialize SDK with Custom Options

Source: https://context7.com/telegram-mini-apps/tma.js/llms.txt

Initialize the SDK with custom options, such as accepting custom styles from the Telegram client or specifying the Mini Apps version.

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

// Or with custom options
init({
  acceptCustomStyles: true,  // Accept styles from Telegram client
  // version: '7.0',         // Optional: specify Mini Apps version
  // themeParams: {...},     // Optional: custom theme parameters
});

// Now you can use SDK features
backButton.mount();
backButton.show();
```

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

### Use useRawLaunchParams Hook

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

Returns launch parameters in a raw, URL-encoded format from any known source.

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

function Component() {
  console.log(useRawLaunchParams());
  // tgWebAppBotInline=0&tgWebAppData=%7B%22user%22%3A%7B%7D...
}

```

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

### Start Parameter Validation RegExp

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/start-parameter.md

Regular expression for validating the characters and length of the start parameter. It allows alphanumeric characters, underscore, and hyphen, with a maximum length of 512.

```regex
/^[\w-]{0,512}$/
```

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

### Signaling Mini App Readiness

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

Call the ready method as early as possible after loading essential interface elements to signal that the Mini App is ready to be displayed. This action hides the loading placeholder and shows the Mini App, ensuring a smooth user experience.

```typescript
miniApp.ready();
```

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

### Retrieve Launch Parameters

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

Use the `retrieveLaunchParams` function to extract launch parameters from the current environment. This function attempts to get them from all possible sources and throws an error if it fails.

```APIDOC
## Retrieve Launch Parameters

### Description
Retrieves launch parameters from the current environment.

### Method
`retrieveLaunchParams()`

### Parameters
None

### Request Example
```typescript
import { retrieveLaunchParams } from '@tma.js/bridge';

retrieveLaunchParams();
```

### Response
#### Success Response (Object)
- **tgWebAppBotInline** (boolean) - Indicates if the bot is inline.
- **tgWebAppData** (object) - Contains user, auth_date, query_id, hash, etc.
- ... (other launch parameters)

#### Response Example
```json
{
  "tgWebAppBotInline": false,
  "tgWebAppData": {
    "user": { ... },
    "auth_date": Date(...),
    "query_id": ...,
    "hash": ...
  },
  "...": "..."
}
```
```

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

### Functional Web Crypto API Signing Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node/signing.md

This example illustrates using the functional `signFp` method with the Web Crypto API for signing data. It leverages `fp-ts/TaskEither` to handle the asynchronous nature and potential errors.

```typescript
import { signFp } from '@tma.js/init-data-node/web';
import * as TE from 'fp-ts/TaskEither';
import { pipe } from 'fp-ts/function';

pipe(
  signFp(
    {
      can_send_after: 10000,
      chat: {
        id: 1,
        type: 'group',
        username: 'my-chat',
        title: 'chat-title',
        photo_url: 'chat-photo',
      },
      chat_instance: '888',
      chat_type: 'sender',
      query_id: 'QUERY',
      receiver: {
        added_to_attachment_menu: false,
        allows_write_to_pm: true,
        first_name: 'receiver-first-name',
        id: 991,
        is_bot: false,
        is_premium: true,
        language_code: 'ru',
        last_name: 'receiver-last-name',
        photo_url: 'receiver-photo',
        username: 'receiver-username',
      },
      start_param: 'debug',
      user: {
        added_to_attachment_menu: false,
        allows_write_to_pm: false,
        first_name: 'user-first-name',
        id: 222,
        is_bot: true,
        is_premium: false,
        language_code: 'en',
        last_name: 'user-last-name',
        photo_url: 'user-photo',
        username: 'user-username',
      },
    },
    '5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8',
    new Date(1000),
  ),
  // The rest of the pipe function would follow here, handling the TaskEither result.
);
```

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

### Functional Node.js Signing Example

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-init-data-node/signing.md

This example shows how to use the functional `signFp` method for signing data in Node.js, utilizing `fp-ts` for handling the `Either` result. It's useful for managing potential signing errors.

```ts
import { signFp } from '@tma.js/init-data-node';
import * as E from 'fp-ts/Either';
import { pipe } from 'fp-ts/function';

pipe(
  signFp(
    {
      can_send_after: 10000,
      chat: {
        id: 1,
        type: 'group',
        username: 'my-chat',
        title: 'chat-title',
        photo_url: 'chat-photo',
      },
      chat_instance: '888',
      chat_type: 'sender',
      query_id: 'QUERY',
      receiver: {
        added_to_attachment_menu: false,
        allows_write_to_pm: true,
        first_name: 'receiver-first-name',
        id: 991,
        is_bot: false,
        is_premium: true,
        language_code: 'ru',
        last_name: 'receiver-last-name',
        photo_url: 'receiver-photo',
        username: 'receiver-username',
      },
      start_param: 'debug',
      user: {
        added_to_attachment_menu: false,
        allows_write_to_pm: false,
        first_name: 'user-first-name',
        id: 222,
        is_bot: true,
        is_premium: false,
        language_code: 'en',
        last_name: 'user-last-name',
        photo_url: 'user-photo',
        username: 'user-username',
      },
    },
    '5768337691:AAH5YkoiEuPk8-FZa32hStHTqXiLPtAEhx8',
    new Date(1000),
  ),
  E.match(
    error => {
      // Something went wrong.
    },
    signedData => {
      // Signing is successful.
    },
  ),
);
```

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

### useRawLaunchParams Hook

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

Returns launch parameters in a raw format from any known source.

```APIDOC
### `useRawLaunchParams`

Returns launch parameters in a raw format from any known source.

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

function Component() {
  console.log(useRawLaunchParams());
  // tgWebAppBotInline=0&tgWebAppData=%7B%22user%22%3A%7B%7D...
}
```
```

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

### web_app_setup_swipe_behavior

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Sets new swipe behavior for the Mini App. Available since v7.7.

```APIDOC
## web_app_setup_swipe_behavior

### Description
Sets new swipe behavior.

### Method
Not specified (assumed to be a JavaScript function call)

### Endpoint
Not applicable (client-side JavaScript API)

### Parameters
#### Request Body
- **allow_vertical_swipe** (boolean) - Required - Allows closing the application using vertical swipe.

### Request Example
```javascript
Telegram.WebApp.enableVerticalSwipe();
```

### Response
#### Success Response (200)
No specific response body defined, operation is typically synchronous.

#### Response Example
```json
// No explicit response body
```
```

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

### Gyroscope Tracking API

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/platform/methods.md

Methods for starting and stopping gyroscope data tracking.

```APIDOC
## `web_app_start_gyroscope`

### Description
Starts tracking gyroscope data.

### Method
POST

### Endpoint
/web_app_start_gyroscope

### Parameters
#### Request Body
- **refresh_rate** (number) - Optional - 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.

### Response
#### Success Response (200)
No specific fields mentioned.

## `web_app_stop_gyroscope`

### Description
Stops tracking gyroscope data.

### Method
POST

### Endpoint
/web_app_stop_gyroscope

### Parameters
No parameters.

### Response
#### Success Response (200)
No specific fields mentioned.
```

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

### Signaling Mini App Ready

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

Explains how to signal that the Mini App is ready to be displayed, which hides the loading placeholder.

```APIDOC
## `ready` Method

### Description
Signals that the Mini App is ready to be displayed. This action hides the loading placeholder and shows the Mini App interface.

### Method
`ready()`

### Endpoint
N/A (SDK method)

### Request Example
```ts
// Call this as early as possible after loading essential interface elements.
miniApp.ready();
```

### Response
This method does not return a value upon successful execution.

### Tip
Call this function as early as possible after loading essential interface elements to ensure a smooth user experience.
```

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

### Get signal value

Source: https://github.com/telegram-mini-apps/tma.js/blob/master/apps/docs/packages/tma-js-signals.md

Call the signal function to retrieve its current value.

```typescript
console.log('The element is', isVisible() ? 'visible' : 'invisible');
```