Skip to content

Init Data

In the list of launch parameters, initialization data is located in the tgWebAppData parameter. It is a set of data mostly related to a specific user who launched the Mini App.

A striking feature of init data is the fact that it can be used as an authentication or authorization factor. For this reason, do not forget about the security of the application and init data specifically.


To extract init data, developer can use the retrieveLaunchParams function from @tma.js/sdk.

import { retrieveLaunchParams } from '@tma.js/sdk';

const { initDataRaw, initData } = retrieveLaunchParams();

Authorization and Authentication

A special feature of initialization data is the ability to be used as a factor for authorization or authentication. The fact is that the data generated by the native Telegram application is signed with the secret key of the Telegram bot, after which the generated signature is placed next to the parameters themselves.

Thus, knowing the secret key of the Telegram bot, the developer has the opportunity to verify the signature of the parameters and make sure that they were indeed issued to the specified user.

Also, the signature verification operation is fast enough and does not require large server resources.


You can find examples using different programming languages in this article.

Sending to Server

In order to authorize the user on the server, the developer needs to transmit the initialization data that was specified when launching the Mini App. To make life easier for yourself, the developer can transmit them at each request to the server, after which the signature verification is carried out on the server side.

Here is how a developer could send init data to server:

import { retrieveLaunchParams } from '@tma.js/sdk';

const { initDataRaw } = retrieveLaunchParams();

fetch('', {
  method: 'POST',
  headers: {
    Authorization: `tma ${initDataRaw}`

In turn, the following actions must be performed on the server side:

  1. Get the value of the Authorization header;
  2. Check that the first part of it is equal to tma;
  3. Get init data and validate its signature.

If this algorithm is successful, the server part of the application can trust the transmitted init data.


Init data validation is one of the most important parts in communication between client and server. It's validity guarantees, that init data can be trusted and used in the future code execution.

Knowing, that init data is presented as query parameters list, to validate them, developer should follow the steps:

  1. Iterate over all key-value pairs and create an array of string values in format {key}={value}. Key hash should be excluded, but memoized. It represents the init data sign and will be used in the final step of the validation process.
  2. Sort the computed array in the alphabetical order.
  3. Create HMAC-SHA256 using key WebAppData and apply it to the Telegram Bot token, that is bound to your Mini App.
  4. Create HMAC-SHA256 using the result of the 3-rd step as a key. Apply it to the pairs array joined with linebreak (\n) received in the 2-nd step and present the result as hex symbols sequence.
  5. Compare the hash value received in the 1-st step with the result of the 4-th step.
  6. If these values are equal, passed init data can be trusted.


In real-world applications, it is recommended to use additional mechanisms for verifying initialization data. For example, add their expiration date. This check can be implemented using the auth_date parameter, which is responsible for the date when the parameters were created. This solution will allow in case of theft of initialization data to prevent their constant use by an attacker.


To avoid possible problems related to the init data validation process, we recommend utilizing well-established and tested packages:


Let's imagine, we have this input:

Telegram Bot token:

Init data:

After the 1-st and 2-nd steps we should receive the following data:

// Sorted pairs.

// Hash.

Then, create HMAC-SHA256 required in the 3-rd step. It should be based on the WebAppData string literal value and Telegram Bot token.

) = "aa492a44bdf019c759defb1698c1d77690189973945491a756051cdc1207a449"

Finally, let's compute the init data sign using the sorted pairs received in the 2-nd step and the value from the 3-rd step:

joined_pairs =

) = "371697738012ebd26a111ace4aff23ee265596cd64026c8c3677956a85ca1827"

Now, comparing the last received result with the hash value from the 1-st step, we can see, that they are equal. It means, we can trust the passed init data.

Parameters List

This section provides a complete list of parameters used in initialization data.

auth_datenumber The date the initialization data was created. Is a number representing a Unix timestamp.
can_send_afternumberOptional. The number of seconds after which a message can be sent via the method answerWebAppQuery.
chatChatOptional. An object containing information about the chat with the bot in which the Mini Apps was launched. It is returned only for Mini Apps opened through the attachments menu.
chat_typestringOptional. The type of chat from which the Mini Apps was opened. Values:
  • sender
  • private
  • group
  • supergroup
  • channel
Returned only for applications opened by direct link.
chat_instancestringOptional. A global identifier indicating the chat from which the Mini Apps was opened. Returned only for applications opened by direct link.
hashstringInitialization data signature.
query_idstringOptional. The unique session ID of the Mini App. Used in the process of sending a message via the method answerWebAppQuery.
receiverUserOptional. An object containing data about the chat partner of the current user in the chat where the bot was launched via the attachment menu. Returned only for private chats and only for Mini Apps launched via the attachment menu.
start_paramstringOptional. The value of the startattach or startapp query parameter specified in the link. It is returned only for Mini Apps opened through the attachment menu.
userUserOptional. An object containing information about the current user.

Other Types


Describes the chat information.

idnumberUnique chat ID.
typestring Chat type. Values:
  • group
  • supergroup
  • channel
titlestringChat title.
photo_urlstringOptional. Chat photo link. The photo can have .jpeg and .svg formats. It is returned only for Mini Apps opened through the attachments menu.
usernamestringOptional. Chat user login.


Describes information about a user or bot.

added_to_attachment_menubooleanOptional. True, if this user added the bot to the attachment menu.
allows_write_to_pmbooleanOptional. True, if this user allowed the bot to message them.
is_premiumbooleanOptional. Has the user purchased Telegram Premium.
first_namestringBot or user name.
idnumberBot or user ID.
is_botbooleanOptional. Is the user a bot.
last_namestringOptional. User's last name.
language_codestringOptional. IETF user's language.
photo_urlstringOptional. Link to the user's or bot's photo. Photos can have formats .jpeg and .svg. It is returned only for Mini Apps opened through the attachment menu.
usernamestringOptional. Login of the bot or user.

Released under the MIT License.