Telegram Mini Apps SDK

https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/
Admin
A Software Development Kit (SDK) designed to help developers build and integrate mini-applications...
Tokens:23,831
Snippets:136
Trust Score:5.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install @telegram-apps/sdk using PNPM

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/index

Installs the @telegram-apps/sdk package using the PNPM package manager. Ensure PNPM is installed and configured in your project.

```bash
pnpm i @telegram-apps/sdk
```

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

### Install @telegram-apps/sdk-react with npm

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/usage-tips

Installs the Telegram Mini Apps SDK for React projects using the npm package manager. Use this if npm is your preferred package manager.

```bash
npm i @telegram-apps/sdk-react
```

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

### Install @telegram-apps/sdk-react with pnpm

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/usage-tips

Installs the Telegram Mini Apps SDK for React projects using the pnpm package manager. This is recommended if React is your core library.

```bash
pnpm i @telegram-apps/sdk-react
```

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

### Install @telegram-apps/sdk-react with yarn

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/usage-tips

Installs the Telegram Mini Apps SDK for React projects using the yarn package manager. This command is for users who prefer yarn.

```bash
yarn add @telegram-apps/sdk-react
```

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

### Install @telegram-apps/sdk using NPM

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/index

Installs the @telegram-apps/sdk package using the NPM package manager. This is a common way to add dependencies to Node.js projects.

```bash
npm i @telegram-apps/sdk
```

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

### Get Telegram Start Parameter (SDK)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves the value of the `startattach` or `startapp` query parameter from the link used to launch the Mini App. Returns a string or undefined if no parameter is present.

```typescript
import { initDataStartParam } from '@telegram-apps/sdk';

initDataStartParam(); // 'my-value'
```

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

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

### Install @telegram-apps/sdk using Yarn

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/index

Installs the @telegram-apps/sdk package using the Yarn package manager. Yarn is an alternative package manager for JavaScript.

```bash
yarn add @telegram-apps/sdk
```

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

### Get Cloud Storage Keys in Telegram Mini Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/cloud-storage

Provides examples for retrieving a list of all existing keys in cloud storage using the `getKeys` method. It also demonstrates fetching specific item values or multiple values using the `getItem` method. Availability checks are included.

```typescript
if (cloudStorage.getKeys.isAvailable()) {
  const keys = await cloudStorage.getKeys(); // ['a', 'b', 'c']
}
```

```typescript
import { getCloudStorageKeys } from '@telegram-apps/sdk';

if (getCloudStorageKeys.isAvailable()) {
  const keys = await getCloudStorageKeys(); // ['a', 'b', 'c']
}
```

```typescript
if (cloudStorage.getItem.isAvailable()) {
  const nonExistent = await cloudStorage.getItem('non-existent');
  // The result is an empty string: ''

  const existent = await cloudStorage.getItem('a');
  // The result is the value of the 'a' key. Example: 'a-value'

  const values = await cloudStorage.getItem(['a', 'b', 'non-existent']);
  // The result is a record of the keys 'a', 'b', and 'non-existent'. 
  // Example:
  // { 
  //   a: 'a-value', 
  //   b: 'b-value', 
  //   'non-existent': '', 
  // }
}
```

```typescript
import { getCloudStorageItem } from '@telegram-apps/sdk';

if (getCloudStorageItem.isAvailable()) {
  const nonExistent = await getCloudStorageItem('non-existent');
  // The result is an empty string: ''

  const existent = await getCloudStorageItem('a');
  // The result is the value of the 'a' key. Example: 'a-value'

  const values = await getCloudStorageItem(['a', 'b', 'non-existent']);
  // The result is a record of the keys 'a', 'b', and 'non-existent'. 
  // Example:
  // { 
  //   a: 'a-value', 
  //   b: 'b-value', 
  //   'non-existent': '', 
  // }
}
```

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

### Bundler Configuration for SDK Source Code Usage (Vite Example)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/scopes

Illustrates how to configure a bundler, specifically Vite, to use the SDK's source code instead of its built version. This allows the bundler to perform more granular tree-shaking, as shown in the example where `backButton.show()` is recognized as `showBackButton` and only its source is bundled.

```typescript
import { backButton } from '@telegram-apps/sdk';

backButton.show();
// Only backButton.show's source code will be bundled 
// because the bundler is smart enough to understand 
// that backButton.show is just the showBackButton 
// function, so only its source code is bundled.
```

```typescript
import { defineConfig } from 'vite';
import { resolve } from 'node:path';

export default defineConfig({
  resolve: {
    alias: {
      '@telegram-apps/sdk': resolve('node_modules/@telegram-apps/sdk/src'),
    },
  },
});
```

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

### Get Telegram Initialization State (SDK)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves an object containing the initialization data of the Mini App. This data is deeply camel-cased and provides comprehensive initialization information.

```typescript
import { initDataState } from '@telegram-apps/sdk';

initDataState();
// { ... init data object ... }
```

```typescript
initData.state();
// { ... init data object ... }
```

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

### Get Raw Init Data String

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Returns the raw, unparsed string representation of the initialization data. This signal is useful for debugging or when specific parsing logic is required. It returns a `string` or `undefined`.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.raw(); // 'user=...&chat=...&...'
```

```typescript
import { initDataRaw } from '@telegram-apps/sdk';

initDataRaw(); // 'user=...&chat=...&...'
```

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

### Open QR Scanner (Promise Style) - TypeScript

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/qr-scanner

Illustrates using the `qrScanner.open` method with a promise-based approach. This allows capturing the first scanned QR code or a specific QR code by providing a `capture` function. The example includes checking the scanner's open state and handling the promise resolution.

```typescript
import { qrScanner } from '@telegram-apps/sdk';

if (qrScanner.open.isAvailable()) {
  // Getting the first captured QR.
  qrScanner.isOpened(); // false
  let promise = qrScanner.open({ text: 'Scan any QR' });
  qrScanner.isOpened(); // true
  await promise;
  qrScanner.isOpened(); // false

  // Getting some specific QR.
  qrScanner.isOpened(); // false
  promise = qrScanner.open({
    text: 'Scan some specific QR',
    capture(qr) {
      return qr === 'some-specific-qr';
    },
  });
  qrScanner.isOpened(); // true
  await promise;
  qrScanner.isOpened(); // false
}
```

```typescript
import {
  openQrScanner,
  closeQrScanner,
  isQrScannerOpened,
} from '@telegram-apps/sdk';

if (openQrScanner.isAvailable()) {
  // Getting the first captured QR.
  // isQrScannerOpened() -> false
  let promise = openQrScanner({ text: 'Scan any QR' });
  // isQrScannerOpened() -> true
  await promise;
  // isQrScannerOpened() -> false

  // Getting some specific QR.
  // isQrScannerOpened() -> false
  promise = openQrScanner({
    text: 'Scan some specific QR',
    capture(qr) {
      return qr === 'some-specific-qr';
    },
  });
  // isQrScannerOpened() -> true
  await promise;
  // isQrScannerOpened() -> false
}
```

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

### Get Init Data Chat Information

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Provides an object containing details about the chat where the Mini App was launched via the attachment menu. This includes chat ID, type, title, photo URL, and username. Returned for supergroups, channels, and group chats.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.chat();
// { 
//   id: 7728725378876215,
//   type: 'group',
//   title: '@BotFather',
//   photoUrl: 'https://example.com/image.png',
//   username: 'botfather'
// }
```

```typescript
import { initDataChat } from '@telegram-apps/sdk';

initDataChat();
// { 
//   id: 7728725378876215,
//   type: 'group',
//   title: '@BotFather',
//   photoUrl: 'https://example.com/image.png',
//   username: 'botfather'
// }
```

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

### Get Init Data Signature Hash

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves the initialization data signature, which is used to verify the integrity and authenticity of the data. This signal returns a `string` representing the hash, or `undefined` if it's not available.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.hash(); // 'group'
```

```typescript
import { initDataHash } from '@telegram-apps/sdk';

initDataHash(); // 'sgbbc62g3bvdhg3djsaasd'
```

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

### Show and Hide Settings Button (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/settings-button

Provides examples of how to show and hide the settings button using the 'show' and 'hide' methods. These actions affect the 'isVisible' signal property. It's recommended to check availability before calling these methods.

```typescript
import { settingsButton } from '@telegram-apps/sdk';

if (settingsButton.show.isAvailable()) {
  settingsButton.show();
  settingsButton.isVisible(); // true
}

if (settingsButton.hide.isAvailable()) {
  settingsButton.hide();
  settingsButton.isVisible(); // false
}
```

```typescript
import {
  showSettingsButton,
  hideSettingsButton,
  isSettingsButtonVisible,
} from '@telegram-apps/sdk';

if (showSettingsButton.isAvailable()) {
  showSettingsButton();
  isSettingsButtonVisible(); // true
}

if (hideSettingsButton.isAvailable()) {
  hideSettingsButton();
  isSettingsButtonVisible(); // false
}
```

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

### Cloud Storage API

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/cloud-storage

The Cloud Storage component allows mini apps to store and retrieve user data in the cloud. It provides methods for checking support, setting, getting, and deleting items.

```APIDOC
## Cloud Storage API

### Description
Provides methods for interacting with the cloud storage in Telegram Mini Apps. This allows for persistent storage of user data.

### Methods

#### Check Support

Checks if cloud storage is supported by the current Telegram Mini Apps version.

**Method:** `isSupported`

**Endpoint:** N/A (Client-side SDK method)

**Parameters:** None

**Request Example:**
```typescript
import { cloudStorage } from '@telegram-apps/sdk';

const supported = cloudStorage.isSupported(); // boolean
```

```typescript
import { isCloudStorageSupported } from '@telegram-apps/sdk';

const supported = isCloudStorageSupported(); // boolean
```

**Response:**
- `boolean`: `true` if supported, `false` otherwise.

#### Set Item

Sets a key-value pair in the cloud storage.

**Method:** `setItem`

**Endpoint:** N/A (Client-side SDK method)

**Parameters:**
- `key` (string) - Required - The key to set.
- `value` (string) - Required - The value to associate with the key.

**Request Example:**
```typescript
import { cloudStorage } from '@telegram-apps/sdk';

if (cloudStorage.setItem.isAvailable()) {
  await cloudStorage.setItem('myKey', 'myValue');
}
```

```typescript
import { setCloudStorageItem } from '@telegram-apps/sdk';

if (setCloudStorageItem.isAvailable()) {
  await setCloudStorageItem('myKey', 'myValue');
}
```

**Response:** None (asynchronous operation).

#### Get Keys

Retrieves a list of all existing keys in the cloud storage.

**Method:** `getKeys`

**Endpoint:** N/A (Client-side SDK method)

**Parameters:** None

**Request Example:**
```typescript
import { cloudStorage } from '@telegram-apps/sdk';

if (cloudStorage.getKeys.isAvailable()) {
  const keys = await cloudStorage.getKeys(); // ['key1', 'key2']
}
```

```typescript
import { getCloudStorageKeys } from '@telegram-apps/sdk';

if (getCloudStorageKeys.isAvailable()) {
  const keys = await getCloudStorageKeys(); // ['key1', 'key2']
}
```

**Response:**
- `string[]`: An array of keys stored in the cloud storage.

#### Get Item

Retrieves the value of a specific key or multiple keys from the cloud storage.

**Method:** `getItem`

**Endpoint:** N/A (Client-side SDK method)

**Parameters:**
- `key` (string | string[]) - Required - The key or an array of keys to retrieve values for.

**Request Example:**
```typescript
import { cloudStorage } from '@telegram-apps/sdk';

if (cloudStorage.getItem.isAvailable()) {
  // Get a single item
  const value = await cloudStorage.getItem('myKey'); // 'myValue' or '' if not found

  // Get multiple items
  const values = await cloudStorage.getItem(['key1', 'key2', 'nonExistentKey']); 
  // Example: { key1: 'value1', key2: 'value2', nonExistentKey: '' }
}
```

```typescript
import { getCloudStorageItem } from '@telegram-apps/sdk';

if (getCloudStorageItem.isAvailable()) {
  // Get a single item
  const value = await getCloudStorageItem('myKey'); // 'myValue' or '' if not found

  // Get multiple items
  const values = await getCloudStorageItem(['key1', 'key2', 'nonExistentKey']); 
  // Example: { key1: 'value1', key2: 'value2', nonExistentKey: '' }
}
```

**Response:**
- `string` | `Record<string, string>`: The value for a single key, or a record of key-value pairs for multiple keys. Returns an empty string for non-existent keys.

#### Delete Item

Deletes a key or a list of keys from the cloud storage.

**Method:** `deleteItem`

**Endpoint:** N/A (Client-side SDK method)

**Parameters:**
- `key` (string | string[]) - Required - The key or an array of keys to delete.

**Request Example:**
```typescript
import { cloudStorage } from '@telegram-apps/sdk';

if (cloudStorage.deleteItem.isAvailable()) {
  // Delete a single item
  await cloudStorage.deleteItem('myKey');

  // Delete multiple items
  await cloudStorage.deleteItem(['key1', 'key2']);
}
```

```typescript
import { deleteCloudStorageItem } from '@telegram-apps/sdk';

if (deleteCloudStorageItem.isAvailable()) {
  // Delete a single item
  await deleteCloudStorageItem('myKey');

  // Delete multiple items
  await deleteCloudStorageItem(['key1', 'key2']);
}
```

**Response:** None (asynchronous operation).
```

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

### Get Telegram User Data (SDK)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves an object containing information about the current Telegram user. This includes details like user ID, first name, username, and premium status. The returned object has camel-cased properties.

```typescript
import { initDataUser } from '@telegram-apps/sdk';

initDataUser();
// { ... user object ... }
```

```typescript
initData.user();
// { ... user object ... }
```

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

### Get Init Data Auth Date

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves the creation date of the initialization data. This signal returns a `Date` object representing when the init data was generated. It can also be `undefined` if the data is not available.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.authDate(); // Date(1727368894000)
```

```typescript
import { initDataAuthDate } from '@telegram-apps/sdk';

initDataAuthDate(); // Date(1727368894000)
```

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

### Open and Close QR Scanner (Callback Style) - TypeScript

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/qr-scanner

Demonstrates opening the QR scanner using the `qrScanner.open` method with a callback for `onCaptured`. The scanner can be closed programmatically if specific QR content is detected. This example also shows checking the scanner's open state before and after operations.

```typescript
import { qrScanner } from '@telegram-apps/sdk';

if (qrScanner.open.isAvailable()) {
  qrScanner.isOpened(); // false
  const promise = qrScanner.open({
    text: 'Scan the QR',
    onCaptured(qr) {
      if (qr === 'qr-content-we-expect') {
        qrScanner.close();
      }
    },
  });
  qrScanner.isOpened(); // true
  await promise;
  qrScanner.isOpened(); // false
}
```

```typescript
import {
  openQrScanner,
  closeQrScanner,
  isQrScannerOpened,
} from '@telegram-apps/sdk';

if (openQrScanner.isAvailable()) {
  isQrScannerOpened(); // false
  const promise = openQrScanner({
    text: 'Scan the QR',
    onCaptured(qr) {
      if (qr === 'qr-content-we-expect') {
        closeQrScanner();
      }
    },
  });
  isQrScannerOpened(); // true
  await promise;
  isQrScannerOpened(); // true
}
```

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

### Get Init Data Chat Instance Identifier

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Returns a global identifier for the chat from which the Mini App was opened. This signal is crucial for distinguishing between different instances of the same chat. It is returned only for applications opened via a direct link.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.chatInstance(); // 'group'
```

```typescript
import { initDataChatInstance } from '@telegram-apps/sdk';

initDataChatInstance(); // '899667289674387257'
```

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

### Get Init Data Query ID

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Fetches the unique session ID of the Mini App, referred to as the query ID. This ID is essential for processes like sending messages via the `answerWebAppQuery` method. It returns a `string` or `undefined`.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.queryId(); // 'group'
```

```typescript
import { initDataQueryId } from '@telegram-apps/sdk';

initDataQueryId(); // 'ssVXZ231ger'
```

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

### Mount and Show Back Button

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/usage-tips

Demonstrates how to mount the `backButton` component and then safely show it. Mounting is required before calling methods like `show()` to prevent errors.

```typescript
import { init, backButton } from '@telegram-apps/sdk';

// Initialize the SDK.
init();

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

// Show the Back Button.
backButton.show();
```

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

### Signal Mini App Ready - Telegram Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/mini-app

Signals that the Mini App is ready to be displayed, hiding the loading placeholder and showing the application. It should be called as early as possible after essential UI elements are loaded.

```typescript
if (miniApp.ready.isAvailable()) {
  miniApp.ready();
}
```

```typescript
import { miniAppReady } from '@telegram-apps/sdk';

if (miniAppReady.isAvailable()) {
  miniAppReady();
}
```

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

### Telegram Mini Apps SDK Initialization and Back Button Usage

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/index

Demonstrates how to initialize the Telegram Mini Apps SDK and manage the back button functionality in TypeScript. It imports necessary functions, initializes the SDK, mounts the back button, and sets up an event listener for clicks to navigate back in the browser history.

```typescript
import { init, backButton } from '@telegram-apps/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();
});
```

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

### Synchronous Mounting of ThemeParams and MiniApp (v3)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/migrate-v2-v3

For v3, `mountSync` offers a safe, synchronous alternative to `mount` for both `ThemeParams` and `MiniApp`, allowing them to be mounted in any order without issues.

```typescript
import { themeParams, miniApp } from '@telegram-apps/bridge';

// Safe to call in any order.
themeParams.mountSync();
miniApp.mountSync();
```

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

### Asynchronous Mounting of ThemeParams and MiniApp (v2 vs v3)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/migrate-v2-v3

In v3, mounting `ThemeParams` and `MiniApp` became asynchronous, returning promises. Avoid mounting both simultaneously. The v2 code shows the older synchronous approach.

```typescript
import { themeParams, miniApp } from '@telegram-apps/bridge';

themeParams.mount();
miniApp.mount();
```

```typescript
import { themeParams, miniApp } from '@telegram-apps/bridge';

// If ThemeParams is required.
await themeParams.mount();

// Or if MiniApp is required.
await miniApp.mount();

// Avoid this — it may cause issues.
await Promise.all([themeParams.mount(), miniApp.mount()]);
```

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

### Get Init Data Can Send After Timestamp

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Returns the number of seconds after which a message can be sent using the `answerWebAppQuery` method. This signal provides a `number` representing the delay in seconds, or `undefined` if not applicable.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.canSendAfter(); // 3600
```

```typescript
import { initDataCanSendAfter } from '@telegram-apps/sdk';

initDataAuthDate(); // 3600
```

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

### Initialize Telegram Mini Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/initializing

Initializes the Telegram Mini Apps SDK, configuring its internal global dependencies. This function must be called before using other SDK functions. It accepts an optional `Options` object to customize initialization behavior. If no options are provided, default settings are used.

```typescript
import { init } from '@telegram-apps/sdk';

init();
```

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

### Get Init Data Can Send After Date

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves the timestamp for when a message can be sent, similar to `canSendAfter` but returned as a `Date` object. This is useful for calculations involving specific dates and times. It can also be `undefined`.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.canSendAfterDate(); // Date(1727368897600)
```

```typescript
import { initDataCanSendAfterDate } from '@telegram-apps/sdk';

initDataCanSendAfterDate(); // Date(1727368897600)
```

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

### Mount Back Button Component in Telegram SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/scopes

Shows how to initialize the SDK and mount the Back Button component. Mounting ensures that the component is properly configured and ready for use within the Telegram Mini Apps environment.

```typescript
import { init, backButton } from '@telegram-apps/sdk';

// Initialize the SDK.
init();

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

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

### Share Story on Telegram with Media

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/utils/uncategorized

The `shareStory` method opens the native Telegram story editor, pre-populating it with a provided media URL. You can optionally add text captions (with length limits varying for regular and premium users) and include a widget link for premium subscribers. Check availability using `isAvailable()` or `ifAvailable()`.

```typescript
import { shareStory } from '@telegram-apps/sdk';

if (shareStory.isAvailable()) {
  shareStory('https://my.media/background.png');
}
```

```typescript
import { shareStory } from '@telegram-apps/sdk';

shareStory.ifAvailable('https://my.media/background.png');
```

```typescript
shareStory('https://my.media/background.png', {
  text: 'Today was a good day. Love it! Thanks to this public!',
  widgetLink: {
    url: 'https://t.me/heyqbnk',
    name: 'heyqbnk public group',
  },
});
```

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

### Mount Mini App Asynchronously (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/mini-app

Asynchronously mounts the Telegram Mini App component, fetching theme parameters. It updates `isMounting`, `isMounted`, and `mountError` signals. This method handles potential errors during the mounting process.

```typescript
if (miniApp.mount.isAvailable()) {
  try {
    const promise = miniApp.mount();
    miniApp.isMounting(); // true
    await promise;
    miniApp.isMounting(); // false
    miniApp.isMounted(); // true
  } catch (err) {
    miniApp.mountError(); // equals "err"
    miniApp.isMounting(); // false
    miniApp.isMounted(); // false
  }
}
```

```typescript
import {
  mountminiApp,
  isMiniAppMounting,
  isMiniAppMounted,
  miniAppMountError,
} from '@telegram-apps/sdk';

if (mountminiApp.isAvailable()) {
  try {
    const promise = mountminiApp();
    isMiniAppMounting(); // true
    await promise;
    isMiniAppMounting(); // false
    isMiniAppMounted(); // true
  } catch (err) {
    miniAppMountError(); // equals "err"
    isMiniAppMounting(); // false
    isMiniAppMounted(); // false
  }
}
```

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

### Control Vertical Swipes (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/swipe-behavior

These code examples show how to enable and disable vertical swipes using the SDK. The `enableVertical` and `disableVertical` methods update the `isVerticalEnabled` property. Availability of these methods is checked before execution.

```typescript
import { swipeBehavior } from '@telegram-apps/sdk';

if (swipeBehavior.enableVertical.isAvailable()) {
  swipeBehavior.enableVertical();
  swipeBehavior.isVerticalEnabled(); // true
}

if (swipeBehavior.disableVertical.isAvailable()) {
  swipeBehavior.disableVertical();
  swipeBehavior.isVerticalEnabled(); // false
}
```

```typescript
import {
  enableVerticalSwipes,
  disableVerticalSwipes,
  isVerticalSwipesEnabled,
} from '@telegram-apps/sdk';

if (enableVerticalSwipes.isAvailable()) {
  enableVerticalSwipes();
  isVerticalSwipesEnabled(); // true
}

if (disableVerticalSwipes.isAvailable()) {
  disableVerticalSwipes();
  isVerticalSwipesEnabled(); // false
}
```

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

### Mount Theme Params Synchronously - TypeScript

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/theme-params

Demonstrates the synchronous mounting of theme parameters using `themeParams.mountSync()`. This method updates the `isMounted` signal. It requires the `@telegram-apps/sdk` package.

```typescript
import { themeParams } from '@telegram-apps/sdk';

if (themeParams.mountSync.isAvailable()) {
  themeParams.mountSync();
  themeParams.isMounted(); // true
}
```

```typescript
import { mountThemeParamsSync, isThemeParamsMounted } from '@telegram-apps/sdk';

if (mountThemeParamsSync.isAvailable()) {
  mountThemeParamsSync();
  isThemeParamsMounted(); // true
}
```

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

### Get Telegram Receiver Data (SDK)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves an object with data about the chat partner when the Mini App is launched via the attachment menu in a private chat. Returns undefined otherwise. The object contains camel-cased properties.

```typescript
import { initDataReceiver } from '@telegram-apps/sdk';

initDataReceiver();
// { ... receiver object ... }
```

```typescript
initData.receiver();
// { ... receiver object ... }
```

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

### Mount Mini App Synchronously (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/mini-app

Mounts the Telegram Mini App component synchronously. It updates the `isMounted` signal to true if successful. This method requires the SDK to be available.

```typescript
import { miniApp } from '@telegram-apps/sdk';

if (miniApp.mountSync.isAvailable()) {
  miniApp.mountSync();
  miniApp.isMounted(); // true
}
```

```typescript
import { mountMiniAppSync, isMiniAppMounted } from '@telegram-apps/sdk';

if (mountMiniAppSync.isAvailable()) {
  mountMiniAppSync();
  isMiniAppMounted(); // true
}
```

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

### Mount Theme Params Asynchronously - TypeScript

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/theme-params

Illustrates asynchronous mounting of theme parameters using `themeParams.mount()`. This method involves a promise and updates signals like `isMounting`, `isMounted`, and `mountError` to reflect the process status. It requires the `@telegram-apps/sdk` package.

```typescript
if (themeParams.mount.isAvailable()) {
  try {
    const promise = themeParams.mount();
    themeParams.isMounting(); // true
    await promise;
    themeParams.isMounting(); // false
    themeParams.isMounted(); // true
  } catch (err) {
    themeParams.mountError(); // equals "err"
    themeParams.isMounting(); // false
    themeParams.isMounted(); // false
  }
}
```

```typescript
import {
  mountThemeParams,
  isThemeParamsMounting,
  isThemeParamsMounted,
  themeParamsMountError,
} from '@telegram-apps/sdk';

if (mountThemeParams.isAvailable()) {
  try {
    const promise = mountThemeParams();
    isThemeParamsMounting(); // true
    await promise;
    isThemeParamsMounting(); // false
    isThemeParamsMounted(); // true
  } catch (err) {
    themeParamsMountError(); // equals "err"
    isThemeParamsMounting(); // false
    isThemeParamsMounted(); // false
  }
}
```

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

### Request Emoji Status Access - TypeScript

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/utils/emoji-status

Requests access to the user's emoji status update functionality. It utilizes `requestEmojiStatusAccess.isAvailable()` to check for availability and then calls `requestEmojiStatusAccess()` to get the status. The function returns a promise that resolves with the status.

```typescript
import { requestEmojiStatusAccess } from '@telegram-apps/sdk';

if (requestEmojiStatusAccess.isAvailable()) {
  const status = await requestEmojiStatusAccess();
}
```

```typescript
import { requestEmojiStatusAccess } from '@telegram-apps/sdk';

const result = requestEmojiStatusAccess.ifAvailable();
if (result[0]) {
  const status = await result[1];
}
```

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

### Prompt to Add Telegram Mini App to Home Screen (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/utils/home-screen

Prompts the user to add the current Mini App to their device's home screen. It utilizes the `addToHomeScreen` function from the Telegram Apps SDK. The `isAvailable()` method checks if the feature is supported on the current platform before calling the prompt. This function has no direct input parameters and its output is a user interaction prompt.

```typescript
import { addToHomeScreen } from '@telegram-apps/sdk';

if (addToHomeScreen.isAvailable()) {
  addToHomeScreen();
}
```

```typescript
import { addToHomeScreen } from '@telegram-apps/sdk';

addToHomeScreen.ifAvailable();
```

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

### Check Back Button Method Availability

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/usage-tips

Shows how to check if the `backButton.show()` method is available before calling it. This prevents errors if the method is not supported in the current Telegram version or environment.

```typescript
import { backButton } from '@telegram-apps/sdk';

// ... the SDK is already initialized, and the Back Button is mounted.
if (backButton.show.isAvailable()) {
  backButton.show();
}
```

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

### Get Init Data Chat Type

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/init-data

Retrieves the type of chat from which the Mini App was opened. Possible values include 'sender', 'private', 'group', 'supergroup', and 'channel'. This signal is returned only for applications opened via a direct link.

```typescript
import { initData } from '@telegram-apps/sdk';

initData.chatType(); // 'group'
```

```typescript
import { initDataChatType } from '@telegram-apps/sdk';

initDataChatType(); // 'group'
```

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

### Open Invoice - TypeScript

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/invoice

Shows how to open an invoice using the Telegram Mini Apps SDK. The `open` method can accept an invoice slug or a URL. It also demonstrates checking availability and the invoice's opened state, which updates asynchronously.

```typescript
import { invoice } from '@telegram-apps/sdk';

if (invoice.open.isAvailable()) {
  invoice.isOpened(); // false
  const promise = invoice.open('abIIks213');
  invoice.isOpened(); // true
  const status = await promise;
  invoice.isOpened(); // false

  // Or in URL mode:
  await invoice.open('https://t.me/invoice/abIIks213', 'url');
}
```

```typescript
import { openInvoice, isInvoiceOpened } from '@telegram-apps/sdk';

if (openInvoice.isAvailable()) {
  isInvoiceOpened(); // false
  const promise = openInvoice('abIIks213');
  isInvoiceOpened(); // true
  const status = await promise;
  isInvoiceOpened(); // false

  // Or in URL mode:
  await openInvoice('https://t.me/invoice/abIIks213', 'url');
}
```

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

### Request Biometry Access in Telegram Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/biometry

Provides code examples for requesting user permission to access biometry features within a Telegram Mini App. The `requestAccess` method returns a promise that resolves to a boolean indicating whether the user granted access.

```typescript
if (biometry.requestAccess.isAvailable()) {
  const granted = await biometry.requestAccess(); // boolean
}
```

```typescript
import { requestBiometryAccess } from '@telegram-apps/sdk';

if (requestBiometryAccess.isAvailable()) {
  const granted = await requestBiometryAccess(); // boolean
}
```

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

### Conditionally Call Back Button Show Method

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/usage-tips

Uses the `ifAvailable` utility to call `backButton.show()` only if the method is available. This simplifies code by avoiding explicit `isAvailable()` checks when the result is not critical.

```typescript
import { backButton } from '@telegram-apps/sdk';

// ... the SDK is already initialized, and the Back Button is mounted.
backButton.show.ifAvailable();
```

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

### Configure Main Button Properties using telegram-apps-sdk

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/main-button

Shows how to set various properties of the main button, such as text, color, and visibility, using the `setParams` method. This updates several state signals including `backgroundColor`, `text`, and `isVisible`.

```typescript
import { mainButton } from '@telegram-apps/sdk';

if (mainButton.setParams.isAvailable()) {
  mainButton.setParams({
    backgroundColor: '#000000',
    hasShineEffect: true,
    isEnabled: true,
    isLoaderVisible: true,
    isVisible: true,
    text: 'My text',
    textColor: '#ffffff'
  });
  mainButton.backgroundColor(); // '#000000'
  mainButton.hasShineEffect(); // true
  mainButton.isEnabled(); // true
  mainButton.isLoaderVisible(); // true
  mainButton.isVisible(); // true
  mainButton.text(); // 'My text'
  mainButton.textColor(); // '#ffffff'

  mainButton.state();
  // {
  //   backgroundColor: '#000000',
  //   hasShineEffect: true,
  //   isActive: true,
  //   isLoaderVisible: true,
  //   isVisible: true,
  //   text: 'My text',
  //   textColor: '#ffffff'
  // }
}
```

```typescript
import {
  setMainButtonParams,
  mainButtonBackgroundColor,
  mainButtonHasShineEffect,
  isMainButtonVisible,
  isMainButtonEnabled,
  isMainButtonLoaderVisible,
  mainButtonState,
  mainButtonTextColor,
  mainButtonText,
} from '@telegram-apps/sdk';

if (setMainButtonParams.isAvailable()) {
  setMainButtonParams({
    backgroundColor: '#000000',
    hasShineEffect: true,
    isEnabled: true,
    isLoaderVisible: true,
    isVisible: true,
    text: 'My text',
    textColor: '#ffffff'
  });
  mainButtonBackgroundColor(); // '#000000'
  mainButtonHasShineEffect(); // true
  isMainButtonEnabled(); // true
  isMainButtonLoaderVisible(); // true
  isMainButtonVisible(); // true
  mainButtonText(); // 'My text'
  mainButtonTextColor(); // '#ffffff'

  mainButtonState();
  // {
  //   backgroundColor: '#000000',
  //   hasShineEffect: true,
  //   isActive: true,
  //   isLoaderVisible: true,
  //   isVisible: true,
  //   text: 'My text',
  //   textColor: '#ffffff'
  // }
}
```

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

### Manage Back Button Component with Telegram SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/scopes

Demonstrates how to use the Back Button scope in the Telegram SDK. This includes showing, hiding, and checking the visibility of the back button, along with its mounting process. It highlights the equivalence between component variables and their associated functions.

```typescript
import {
  backButton,
  hideBackButton,
  isBackButtonVisible,
} from '@telegram-apps/sdk';

isBackButtonVisible(); // false

backButton.show();
// backButton.isVisible and isBackButtonVisible are the same 
// entity (signal). We can say the same about backButton.show 
// and showBackButton.
//
// backButton.isVisible() -> true
// isBackButtonVisible() -> true

hideBackButton();
// backButton.isVisible() -> false
// isBackButtonVisible() -> false
```

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

### Get Safe Area Insets (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/viewport

Retrieves the safe area insets (top, bottom, left, right) and content safe area insets as objects or individual numeric values using the viewport component. This is useful for adjusting UI elements to avoid being obscured by system UI.

```typescript
import {
  viewportSafeAreaInsets,
  viewportSafeAreaInsetTop,
  viewportSafeAreaInsetBottom,
  viewportSafeAreaInsetLeft,
  viewportSafeAreaInsetRight,
  viewportContentSafeAreaInsets,
  viewportContentSafeAreaInsetTop,
  viewportContentSafeAreaInsetBottom,
  viewportContentSafeAreaInsetLeft,
  viewportContentSafeAreaInsetRight,
} from '@telegram-apps/sdk';

// Objects with numeric properties "top", "bottom", "left" and "right".
vpSafeAreaInsets();
vpContentSafeAreaInsets();

// Numeric values.
vpSafeAreaInsetTop();
vpSafeAreaInsetBottom();
vpSafeAreaInsetLeft();
vpSafeAreaInsetRight();
vpContentSafeAreaInsetTop();
vpContentSafeAreaInsetBottom();
vpContentSafeAreaInsetLeft();
vpContentSafeAreaInsetRight();
```

```typescript
// Objects with numeric properties "top", "bottom", "left" and "right".
vpSafeAr<ctrl63>
```

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

### Update Background Color - Telegram Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/mini-app

Updates the mini application's background color and header color. It checks for method availability before execution. Returns the current background color after setting it.

```typescript
if (miniApp.setBackgroundColor.isAvailable()) {
  miniApp.setBackgroundColor('#ffffff');
  miniApp.backgroundColor(); // '#ffffff'
}
```

```typescript
import {
  setMiniAppBackgroundColor,
  miniAppBackgroundColor,
} from '@telegram-apps/sdk';

if (setMiniAppBackgroundColor.isAvailable()) {
  setMiniAppBackgroundColor('#ffffff');
  miniAppBackgroundColor(); // '#ffffff'
}
```

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

### Get Current Telegram Server Time

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/utils/uncategorized

The `getCurrentTime` function retrieves the current time from Telegram's servers, returning it as a JavaScript `Date` object. This ensures accurate timekeeping within your Mini App, independent of the user's device clock. Use `isAvailable()` or `ifAvailable()` to check compatibility.

```typescript
import { getCurrentTime } from '@telegram-apps/sdk';

if (getCurrentTime.isAvailable()) {
  const time = await getCurrentTime(); // Date
}
```

```typescript
import { getCurrentTime } from '@telegram-apps/sdk';

const result = getCurrentTime.ifAvailable();
if (result[0]) {
  const date = await result[1];
}
```

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

### Download File with Telegram SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/utils/uncategorized

The `downloadFile` function facilitates requesting the download of a file from a given URL. It accepts the file URL and an optional proposed name for the saved file. The `isAvailable()` and `ifAvailable()` methods can be used to check for support before attempting the download.

```typescript
import { downloadFile } from '@telegram-apps/sdk';

if (downloadFile.isAvailable()) {
  await downloadFile(
    'https://telegram.org/js/telegram-web-app.js',
    'telegram-sdk.js',
  );
}
```

```typescript
import { downloadFile } from '@telegram-apps/sdk';

const foo = downloadFile.ifAvailable(
  'https://telegram.org/js/telegram-web-app.js',
  'telegram-sdk.js',
);
foo[0] && await foo[1];
```

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

### Mount and Unmount Main Button using telegram-apps-sdk

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/main-button

Demonstrates how to mount and unmount the main button for Telegram Mini Apps. Ensure Theme Params are mounted first. The `isMounted` signal indicates the button's current state.

```typescript
import { mainButton } from '@telegram-apps/sdk';

if (mainButton.mount.isAvailable()) {
  mainButton.mount();
  mainButton.isMounted(); // true
}

mainButton.unmount(); 
mainButton.isMounted(); // false
```

```typescript
import { mountMainButton, isMainButtonMounted, unmountMainButton } from '@telegram-apps/sdk';

if (mountMainButton.isAvailable()) {
  mountMainButton();
  isMainButtonMounted(); // true
}

unmountMainButton();
isMainButtonMounted(); // false
```

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

### Mount Telegram Mini Apps Viewport

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/viewport

Demonstrates how to mount the Telegram Mini Apps viewport. This is an asynchronous operation that requests viewport information from the Telegram application. It uses signals like `isMounting`, `isMounted`, and `mountError` to track the mounting process and its outcome. Ensure the `mount` method is available before calling.

```typescript
if (viewport.mount.isAvailable()) {
  try {
    const promise = viewport.mount();
    viewport.isMounting(); // true
    await promise;
    viewport.isMounting(); // false
    viewport.isMounted(); // true
  } catch (err) {
    viewport.mountError(); // equals "err"
    viewport.isMounting(); // false
    viewport.isMounted(); // false
  }
}
```

```typescript
import {
  mountViewport,
  isViewportMounting,
  isViewportMounted,
  viewportMountError,
} from '@telegram-apps/sdk';

if (mountViewport.isAvailable()) {
  try {
    const promise = mountViewport();
    isViewportMounting(); // true
    await promise;
    isViewportMounting(); // false
    isViewportMounted(); // true
  } catch (err) {
    viewportMountError(); // equals "err"
    isViewportMounting(); // false
    isViewportMounted(); // false
  }
}
```

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

### Tree-shaking with Exclusive Function Usage in Telegram Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/scopes

Demonstrates how using functions exclusively from the SDK can improve tree-shaking by bundlers. Importing and calling specific functions like `showBackButton` ensures only their relevant code is bundled, unlike importing the entire `backButton` object which may include unused methods.

```typescript
import { showBackButton, backButton } from '@telegram-apps/sdk';

showBackButton();
// Only showBackButton's source code will be bundled.

backButton.show();
// All backButton dependencies will be bundled, even 
// if not used in the code: backButton.show(), 
// backButton.hide(), backButton.isVisible(), etc.
```

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

### Open Popup with Telegram Apps SDK

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/popup

Shows how to open a popup window using the Telegram Mini Apps SDK. It requires calling the `open` method (or `openPopup` function) with a title, message, and a list of up to three buttons. The method returns a promise that resolves with the clicked button's identifier or null if no button was clicked. Calling this method also updates the popup's open state.

```typescript
import { popup } from '@telegram-apps/sdk';

if (popup.open.isAvailable()) {
  // popup.isOpened() -> false
  const promise = popup.open({
    title: 'Hello!',
    message: 'Here is a test message.',
    buttons: [{ id: 'my-id', type: 'default', text: 'Default text' }],
  });
  // popup.isOpened() -> true
  const buttonId = await promise;
  // popup.isOpened() -> false
}
```

```typescript
import { openPopup, isPopupOpened } from '@telegram-apps/sdk';

if (openPopup.isAvailable()) {
  // isPopupOpened() -> false
  const promise = openPopup({
    title: 'Hello!',
    message: 'Here is a test message.',
    buttons: [{ id: 'my-id', type: 'default', text: 'Default text' }],
  });
  // isPopupOpened() -> true
  const buttonId = await promise;
  // isPopupOpened() -> false
}
```

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

### Mounting Closing Behavior Component

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/components/closing-behavior

Demonstrates how to mount the closing behavior component using the `mount` method. This action updates the `isMounted` signal property. It's crucial to check availability before mounting.

```typescript
import { closingBehavior } from '@telegram-apps/sdk';

if (closingBehavior.mount.isAvailable()) {
  closingBehavior.mount();
  closingBehavior.isMounted(); // true
}
```

```typescript
import {
  mountClosingBehavior,
  isClosingBehaviorMounted,
} from '@telegram-apps/sdk';

if (mountClosingBehavior.isAvailable()) {
  mountClosingBehavior();
  isClosingBehaviorMounted(); // true
}
```

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

### Track Telegram Mini App Added to Home Screen Events (TypeScript)

Source: https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk/3-x/utils/home-screen

Sets up and removes event listeners for when a Telegram Mini App is successfully added to the home screen or if the request fails. It uses `onAddedToHomeScreen`, `offAddedToHomeScreen`, `onAddToHomeScreenFailed`, and `offAddToHomeScreenFailed` from the Telegram Apps SDK. These functions take a callback as an argument to handle the respective events.

```typescript
import {
  onAddedToHomeScreen,
  onAddToHomeScreenFailed,
  offAddedToHomeScreen,
  offAddToHomeScreenFailed,
} from '@telegram-apps/sdk';

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

onAddedToHomeScreen(onAdded);
offAddedToHomeScreen(onAdded);

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

onAddToHomeScreenFailed(onFailed);
offAddToHomeScreenFailed(onFailed);
```
Tokens:
Raw