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, it is required to firstly get the launch parameters, then extract parameter with name tgWebAppData and pass it to the URLSearchParams constructor:

// Get launch parameters.
const params = new URLSearchParams(window.location.hash.slice(1));
const initDataRaw = params.get('tgWebAppData'); // user=...&query_id=...&...

const initData = new URLSearchParams(initDataRaw);
// ['user', '{"id":279058397,"first_name":"Vladislav", ... }']
// ['chat_instance', '8428209589180549439']
// ['chat_type', 'sender']
// ['auth_date', '1698272211']
// ['hash', 'ddc15fc7419ae9cb9a597b98efee42ea0']

// Get launch parameters.
const params = new URLSearchParams(window.location.hash.slice(1));
const initDataRaw = params.get('tgWebAppData'); // user=...&query_id=...&...

const initData = new URLSearchParams(initDataRaw);
// ['user', '{"id":279058397,"first_name":"Vladislav", ... }']
// ['chat_instance', '8428209589180549439']
// ['chat_type', 'sender']
// ['auth_date', '1698272211']
// ['hash', 'ddc15fc7419ae9cb9a597b98efee42ea0']

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. More information about the data signature and verification algorithm can be found in this documentation.

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 comes the example with the usage of such package as axios:

import axios from 'axios';

const initData = new URLSearchParams(window.location.hash.slice(1))
  .get('tgWebAppData');

if (initData === null) {
  throw new Error('Ooof! Something is wrong. Init data is missing');
}

// Create axios instance.  
const http = axios.create({
  headers: {
    // Append authorization header. 
    Authorization: `tma ${initData}`,
  }
});

import axios from 'axios';

const initData = new URLSearchParams(window.location.hash.slice(1))
  .get('tgWebAppData');

if (initData === null) {
  throw new Error('Ooof! Something is wrong. Init data is missing');
}

// Create axios instance.  
const http = axios.create({
  headers: {
    // Append authorization header. 
    Authorization: `tma ${initData}`,
  }
});

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 initialization data and verify its signature.

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

Parameters list ​

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

Other types ​

Chat ​

Describes the chat information.

User ​

Describes information about a user or bot.