Telegram Login Widget Integration: Site Auth Turnkey

How the Telegram Login Widget Works on Your Site

Many sites lose conversion at the registration step — users don't want to fill forms or remember passwords. We offer a solution: integrate login via Telegram. This cuts authorization time to one click and improves conversion rates. Our experience with 100+ successful projects over 10+ years guarantees reliability and security.

The Telegram Login Widget lets users log into your site via their Telegram account without OAuth2 redirects. The user clicks a button, Telegram opens a confirmation dialog, and your site receives signed data. No password, no email — just a Telegram ID.

Why Telegram Login Widget Is More Secure Than Classic Auth

Unlike OAuth2, Telegram does not redirect the user to a third-party site — data is transferred directly through the client widget. HMAC-SHA256 signature prevents forgery. It's twice as fast as traditional redirects and reduces phishing risk. Telegram's documentation confirms server-side verification is mandatory.

Additional protection: rate limiting — no more than 10 auth attempts per minute from a single IP. We also configure auth_date freshness checks: data older than 5 minutes is automatically rejected. This blocks replay attacks where an attacker intercepts old auth data and tries to reuse it. The combination of HMAC verification and time window makes this auth more robust than most classic password schemes.

How to Create a Bot for Authorization

Telegram auth requires a bot. The bot doesn't need to be active — it's only needed for the Bot Token.

1. Open @BotFather in Telegram
2. /newbot → specify name and username
3. Save Bot Token (format 123456:ABCdef...)
4. Set domain: /setdomain → select bot → specify domain (e.g., example.com)

How to Install the Widget on Your Site

<script async src="https://telegram.org/js/telegram-widget.js?22" data-telegram-login="YourBotName" data-size="large" data-auth-url="https://example.com/auth/telegram/callback" data-request-access="write"> </script> 

The data-auth-url parameter is the URL where Telegram will make a GET redirect with auth parameters. The data-request-access="write" parameter requests permission to send messages to the user via the bot.

Alternative mode — callback via JavaScript:

<script src="https://telegram.org/js/telegram-widget.js?22" data-telegram-login="YourBotName" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"> </script> <script> function onTelegramAuth(user) { fetch('/auth/telegram/token', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrfToken }, body: JSON.stringify(user), }).then(r => r.json()).then(data => { if (data.redirect) window.location.href = data.redirect; }); } </script> 

How to Verify the Signature on the Server

This is critical. Data from Telegram is signed with HMAC-SHA256. Without verification, an attacker can send arbitrary data:

class TelegramAuthController extends Controller { public function callback(Request $request): RedirectResponse { $data = $request->only(['id','first_name','last_name','username','photo_url','auth_date','hash']); if (!$this->verifyTelegramHash($data)) { abort(422, 'Invalid Telegram signature'); } // Check freshness: auth_date no older than 5 minutes if (abs(time() - $data['auth_date']) > 300) { abort(422, 'Stale authorization data'); } $user = $this->findOrCreateUser($data); Auth::login($user, remember: true); return redirect()->intended('/dashboard'); } private function verifyTelegramHash(array $data): bool { $receivedHash = $data['hash']; unset($data['hash']); // Sort parameters by key, each in key=value format ksort($data); $dataCheckString = implode("\n", array_map( fn($k, $v) => "{$k}={$v}", array_keys($data), array_values($data) )); // Key is SHA256 of Bot Token $secretKey = hash('sha256', config('services.telegram.bot_token'), true); $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey); return hash_equals($calculatedHash, $receivedHash); } private function findOrCreateUser(array $data): User { return User::updateOrCreate( ['telegram_id' => $data['id']], [ 'name' => trim(($data['first_name'] ?? '') . ' ' . ($data['last_name'] ?? '')), 'avatar' => $data['photo_url'] ?? null, ] ); } } 

Telegram Login via Mini App (TWA)

For embedded Telegram Mini Apps, a different mechanism is used — initData with verification via window.Telegram.WebApp.initData. This is a separate integration for apps inside Telegram.

Data Storage

Telegram does not provide email. The database needs a telegram_id field (bigint, unique). The username may change — update it on each login.

// Migration Schema::table('users', function (Blueprint $table) { $table->bigInteger('telegram_id')->nullable()->unique(); $table->string('telegram_username')->nullable(); }); 

If the users table already has millions of records, add a unique index with CONCURRENTLY to avoid blocking reads. In high-load projects, cache user data in Redis with a 15-minute TTL to reduce database queries on repeated logins. We recommend proxying the photo_url through your own S3 storage: Telegram avatars change periodically, and the original URL may become unavailable after a few months.

Comparison of Authorization Methods

What Our Work Includes

• Bot creation and domain setup
• Widget development and embedding on the frontend
• Server-side verification and API endpoint implementation
• Database migrations and tests
• Integration documentation
• Support for 1 month after delivery

Timeline Estimates

Total: 2.5–3.5 working days.

Assess Your Project

Contact us — we will assess the integration complexity for free and propose the optimal solution. Order a turnkey deployment: a ready Telegram auth in 3 days. The cost is determined after analysis based on your specific requirements.