Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TelegramOrg/Telegram-web-k/llms.txt

Use this file to discover all available pages before exploring further.

Telegram Web K is configured through a combination of environment variables loaded by Vite at build time and a small set of URL query parameters parsed at runtime. Environment variables live in .env and .env.local files at the project root. The .env file ships with the repository and contains sensible defaults for local development; .env.local is your personal override file and is never committed to version control.

​
Getting Telegram API credentials

Every Telegram client — official or third-party — must register an application to receive an API ID and hash. These values identify your client to Telegram’s servers and are required before the app will connect.
1

Open the Telegram API portal

Go to my.telegram.org and log in with the phone number linked to your Telegram account. Telegram will send a confirmation code to your Telegram app.
2

Create a new application

Navigate to API development tools and fill in the form:
  • App title: any name (e.g., My Web K Dev)
  • Short name: a short identifier (e.g., mywebk)
  • Platform: Web
  • Description: optional
Click Create application.
3

Copy your credentials

After creation, the page shows your App api_id (a number) and App api_hash (a hex string). Copy both values — you will need them in the next section.
Your API ID and hash are tied to your Telegram account. Do not share them publicly or commit them to a public repository. Anyone with your credentials can make API calls on behalf of your registered application.

​
Environment variables

Vite reads .env and .env.local files at startup. Variables prefixed with VITE_ are exposed to client-side code via import.meta.env. Variables without that prefix are only available during the Vite build process itself. On first run in development mode, Vite automatically copies .env.local.example to .env.local if the file does not exist. You can also copy it manually: 
cp .env.local.example .env.local
Then open .env.local and override the variables you need. Values in .env.local take precedence over .env.

​
Core variables

​
VITE_API_ID
number
required
Your Telegram application’s API ID, obtained from my.telegram.org. The .env file ships with a development credential (1025907) that works for local testing, but you should replace it with your own.
VITE_API_ID=1025907
​
VITE_API_HASH
string
required
Your Telegram application’s API hash, obtained from my.telegram.org. Paired with VITE_API_ID to authenticate your client.
VITE_API_HASH=452b0359b988148995f22ff0f4229750
​
VITE_PUSH_SERVER_KEY
string
The VAPID public key for Web Push notifications. Required to receive push notifications when the app is in the background. Leave empty to disable push notifications.
VITE_PUSH_SERVER_KEY=BB3JzmQIBTl8ZdTmLzhkZVnoYxoSvUmCe1CqqF53u2j0WbEFo2m--mOBagroDFdqMeESfz3ue1Z1e5PTIxMYH_g
​
VITE_VERSION
string
The public version string shown in the app’s about screen (e.g., 2.2).
VITE_VERSION=2.2
​
VITE_VERSION_FULL
string
The full version string including build number (e.g., 2.2 (649)).
VITE_VERSION_FULL=2.2 (649)
​
VITE_BUILD
number
The numeric build identifier. Used internally for change detection and cache busting.
VITE_BUILD=649

​
MTProto transport variables

These variables control how the MTProto layer establishes connections to Telegram’s servers. The defaults in .env enable both WebSocket and HTTPS transports with automatic selection.
​
VITE_MTPROTO_WORKER
boolean (0 or 1)
Run MTProto networking in a dedicated Web Worker. Recommended — keeps network I/O off the main thread.
VITE_MTPROTO_WORKER=1
​
VITE_MTPROTO_SW
boolean (0 or 1)
Run MTProto inside the Service Worker instead of a Web Worker. Leave empty for the default Worker-based setup.
VITE_MTPROTO_SW=
​
VITE_MTPROTO_AUTO
boolean (0 or 1)
Enable automatic transport selection. When set alongside VITE_MTPROTO_HAS_HTTP and VITE_MTPROTO_HAS_WS, the client starts with HTTP and upgrades to WebSocket when available.
VITE_MTPROTO_AUTO=1
​
VITE_MTPROTO_HAS_HTTP
boolean (0 or 1)
Allow the HTTPS transport for MTProto connections.
VITE_MTPROTO_HAS_HTTP=1
​
VITE_MTPROTO_HAS_WS
boolean (0 or 1)
Allow the WebSocket transport for MTProto connections.
VITE_MTPROTO_HAS_WS=1

​
Example .env.local

A minimal override file for development with your own credentials: 
# .env.local — personal overrides, never committed
VITE_API_ID=123456
VITE_API_HASH=abcdef1234567890abcdef1234567890

​
App config object

src/config/app.ts defines the App object that the rest of the codebase imports for runtime constants. Most fields are populated from import.meta.env (the Vite environment), but some are computed at startup. 
// src/config/app.ts (abridged)
const threads = Math.min(4, navigator.hardwareConcurrency ?? 4);

const App = {
  id: +import.meta.env.VITE_API_ID,       // Telegram API ID (number)
  hash: import.meta.env.VITE_API_HASH,    // Telegram API hash (string)
  pushServerKey: import.meta.env.VITE_PUSH_SERVER_KEY,
  version: import.meta.env.VITE_VERSION,
  domains: ['web.telegram.org', 'webk.telegram.org'],
  baseDcId: 2,                            // Default data center (DC2)
  suffix: 'K',                            // Client identifier suffix
  threads,                                // Capped at 4 or hardwareConcurrency
  lottieWorkers: threads,                 // Worker threads for rlottie rendering
  cryptoWorkers: threads,                 // Worker threads for crypto operations
  interclientBroadcastChannel: 'tgweb'   // BroadcastChannel name for tab sync
};

​
Main domain override

When the app detects it is running on an official Telegram domain (web.telegram.org or webk.telegram.org), it replaces the API credentials with Telegram’s own production keys: 
if(App.isMainDomain) {
  App.id = 2496;
  App.hash = '8da85b0d5bfe62527e5b244c209159c3';
  App.pushServerKey = 'BHEbKOXt-...';
}
This means self-hosted deployments on custom domains always use the credentials from your environment variables.

​
Thread counts

threads, lottieWorkers, and cryptoWorkers are all set to Math.min(4, navigator.hardwareConcurrency ?? 4). On a machine with 8+ logical cores this is 4; on a dual-core machine it is 2. You cannot override these at runtime — they are computed once at module load.

​
Runtime query parameters

These parameters are parsed by src/config/modes.ts on every page load. Append them to any URL where the app is running.
ParameterTypeDefaultDescription
test=1flagoffConnect to Telegram’s test data centers. Messages and accounts on test DCs are separate from production.
debug=1flagoffEnable verbose logging. In development (IS_BETA), debug logging is always on regardless of this flag.
noSharedWorker=1flagoffDisable the Shared Worker. Each tab opens its own network connection — useful for isolating network traffic in DevTools.
noServiceWorker=1flagoffDisable the Service Worker. Push notifications and file streaming fall back to the main thread.
http=1flagoffForce the HTTPS transport for MTProto connections (requires VITE_MTPROTO_HAS_HTTP=1).
noMultipleTransports=1flagoffDisable automatic transport switching even when VITE_MTPROTO_AUTO is enabled.
Apply parameters like this: 
http://localhost:8080/?test=1&debug=1
Use noSharedWorker=1 together with debug=1 when debugging MTProto message flow — you get one network tab per browser tab and full console output, making it easy to trace a single request end-to-end.

​
Debug mode behavior

src/config/debug.ts exports a DEBUG constant and a MOUNT_CLASS_TO object: 
export const IS_BETA = import.meta.env.DEV;           // true during `pnpm start`
export const DEBUG = IS_BETA || Modes.debug;           // true in dev or with debug=1
export const MOUNT_CLASS_TO: any = DEBUG ? window : {};
When DEBUG is true, internal service classes are attached to window (or self in workers) via MOUNT_CLASS_TO. This lets you inspect live state in the browser console without a debugger breakpoint. For example, after the app loads you can type the class name directly in DevTools to inspect its current state. Source maps are included in production builds, so you can set breakpoints in the original TypeScript source even on a deployed build.

​
SSL configuration

By default the dev server runs over plain HTTP on localhost:8080. To run over HTTPS — for example to test Service Worker behavior or push notifications that require a secure context — edit vite.config.ts: 
// vite.config.ts
const USE_SSL = true;              // set to true
const USE_SIGNED_CERTS = true;     // use your own certs from ./certs/
Then generate a certificate for web.telegram.org, add 127.0.0.1 web.telegram.org to /etc/hosts, and place the cert files in ./certs/. The server will start at https://web.telegram.org/.
The @vitejs/plugin-basic-ssl plugin is available in vite.config.ts for generating self-signed certificates when USE_SELF_SIGNED_CERTS is set to true. Self-signed certificates work for local testing but will show a browser security warning.

Build docs developers (and LLMs) love

Get started for freeTalk to us