💠Init Data

A component responsible for the Telegram Mini Apps init data.

Restoring

The component reads init data from the tgWebAppData launch parameter. To do so, call the restore method after the SDK is initialized. Until then, all computed values of the component return undefined.

import { init, initData } from '@tma.js/sdk';

init();
initData.restore();
initData.user(); // { id: 99281932, first_name: 'Andrew', ... }

If launch parameters have no init data, the method does nothing, and the computed values keep returning undefined.

restore throws NotInitializedError if the SDK is not initialized, and InvalidInitDataError if init data is invalid. safeRestore returns InvalidInitDataError as a result instead of throwing it.

const result = initData.safeRestore();
if (!result.ok) {
  console.error('Init data is invalid:', result.error);
}

TIP

To parse, validate or sign init data, use the @tma.js/init-data package. The SDK re-exports the InitData, User, Chat and ChatType types, and the InvalidInitDataError class from it.

Computed Values

This section provides a complete list of computed values related to init data. Each of them returns undefined if init data was not restored or has no such property.

All values can be subscribed to:

const unsubscribe = initData.user.subscribe((next, prev) => {
  console.log('User changed:', prev, '->', next);
});

authDate

Return type: Date | undefined

A date the init data was created.

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

canSendAfter

Return type: number | undefined

A number of seconds after which a message can be sent via the method answerWebAppQuery.

initData.canSendAfter(); // 3600

canSendAfterDate

Return type: Date | undefined

canSendAfter as a date, calculated from authDate.

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

chat

Return type: undefined or Chat

An object containing data about the chat where the bot was launched via the attachment menu.

NOTE

Returned for supergroups, channels and group chats – only for Mini Apps launched via the attachment menu.

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

chatType

Return type: ChatType | undefined

A type of chat from which the mini app was opened. Values:

• sender
• private
• group
• supergroup
• channel

NOTE

Returned only for applications opened by direct link.

initData.chatType(); // 'group'

chatInstance

Return type: string | undefined

A global identifier indicating the chat from which the mini app was opened.

WARNING

Returned only for applications opened by direct link.

initData.chatInstance(); // '8428209589180549439'

hash

Return type: string | undefined

The init data signature.

initData.hash(); // 'abcedef123'

queryId

Return type: string | undefined

A unique session ID of the mini app. Used in the process of sending a message via the method answerWebAppQuery.

initData.queryId(); // 'hSvhacj28716'

raw

Return type: string | undefined

The init data in the raw format. Pass it to your server to authorize the user.

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

receiver

Return type: undefined or User

An object containing data about the chat partner of the current user in the chat where the bot was launched via the attachment menu.

NOTE

Returned only for private chats and only for Mini Apps launched via the attachment menu.

initData.receiver();
// {
//   added_to_attachment_menu: false,
//   allows_write_to_pm: true,
//   is_premium: true,
//   first_name: 'Pavel',
//   id: 78262681,
//   is_bot: false,
//   last_name: 'Durov',
//   language_code: 'ru',
//   photo_url: 'https://example.com/image.png',
//   username: 'durove',
// }

signature

Return type: string | undefined

The init data signature allowing third parties to validate it without the bot token.

initData.signature(); // 'abc...'

startParam

Return type: string | undefined

A value of the startattach or startapp query parameter specified in the link.

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

state

Return type: undefined or InitData

The whole init data object. Its keys are in snake case, and auth_date is a Date.

initData.state();

user

Return type: undefined or User

An object containing information about the current user.

initData.user();
// {
//   added_to_attachment_menu: false,
//   allows_write_to_pm: true,
//   is_premium: true,
//   first_name: 'Pavel',
//   id: 78262681,
//   is_bot: false,
//   last_name: 'Durov',
//   language_code: 'ru',
//   photo_url: 'https://example.com/image.png',
//   username: 'durove',
// }