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.

Retrieving

To extract init data, developer can use the retrieveLaunchParams function from @telegram-apps/sdk.

import { retrieveLaunchParams } from '@telegram-apps/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.

TIP

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 '@telegram-apps/sdk';

const { initDataRaw } = retrieveLaunchParams();

fetch('https://example.com/api', {
  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.

Validating

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.

TIP

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.

TIP

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

• For Node: @telegram-apps/init-data-node
• For GoLang: init-data-golang

Example

Let's imagine, we have this input:

Telegram Bot token:
5768337691:AAGDAe6rjxu1cUgxK4BizYi--Utc3J9v5AU

Init data:
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%22en%22%2C%22is_premium%22%3Atrue%2C%22allows_write_to_pm%22%3Atrue%7D
&chat_instance=-3788475317572404878
&chat_type=private
&auth_date=1709144340
&hash=371697738012ebd26a111ace4aff23ee265596cd64026c8c3677956a85ca1827

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

// Sorted pairs.
[
  'auth_date=1709144340',
  'chat_instance=-3788475317572404878',
  'chat_type=private',
  'user={"id":279058397,"first_name":"Vladislav","last_name":"Kibenko","username":"vdkfrost","language_code":"en","is_premium":true,"allows_write_to_pm":true}'
]

// Hash.
'371697738012ebd26a111ace4aff23ee265596cd64026c8c3677956a85ca1827'

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

HMAC-SHA256(
  "WebAppData", 
  "5768337691:AAGDAe6rjxu1cUgxK4BizYi--Utc3J9v5AU"
) = "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 =
   "auth_date=1709144340
   chat_instance=-3788475317572404878
   chat_type=private
   user={\"id\":279058397,\"first_name\":\"Vladislav\",\"last_name\":\"Kibenko\",\"username\":\"vdkfrost\",\"language_code\":\"en\",\"is_premium\":true,\"allows_write_to_pm\":true}"

HMAC-SHA256(
  "aa492a44bdf019c759defb1698c1d77690189973945491a756051cdc1207a449",
  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.

Parameter	Type	Description
auth_date	number	The date the initialization data was created. Is a number representing a Unix timestamp.
can_send_after	number	Optional. The number of seconds after which a message can be sent via the method answerWebAppQuery.
chat	Chat	Optional. 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_type	string	Optional. 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_instance	string	Optional. A global identifier indicating the chat from which the Mini Apps was opened. Returned only for applications opened by direct link.
hash	string	Initialization data signature.
query_id	string	Optional. The unique session ID of the Mini App. Used in the process of sending a message via the method answerWebAppQuery.
receiver	User	Optional. 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_param	string	Optional. 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.
user	User	Optional. An object containing information about the current user.

Other Types

Chat

Describes the chat information.

Property	Type	Description
id	number	Unique chat ID.
type	string	Chat type. Values: group supergroup channel
title	string	Chat title.
photo_url	string	Optional. Chat photo link. The photo can have .jpeg and .svg formats. It is returned only for Mini Apps opened through the attachments menu.
username	string	Optional. Chat user login.

User

Describes information about a user or bot.

Property	Type	Description
added_to_attachment_menu	boolean	Optional. True, if this user added the bot to the attachment menu.
allows_write_to_pm	boolean	Optional. True, if this user allowed the bot to message them.
is_premium	boolean	Optional. Has the user purchased Telegram Premium.
first_name	string	Bot or user name.
id	number	Bot or user ID.
is_bot	boolean	Optional. Is the user a bot.
last_name	string	Optional. User's last name.
language_code	string	Optional. IETF user's language.
photo_url	string	Optional. 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.
username	string	Optional. Login of the bot or user.