Telegram Login Widget: Sign In With Telegram on a Website
· 4 min read · 18+ readers

The Telegram Login Widget lets people sign in to your website with their Telegram account, without a new password. Telegram gives your page a signed bundle of the user's basic data, and your server checks the signature with your bot token. This guide covers setup, the data you get and how to verify it. Read the official page at core.telegram.org/widgets/login for the current options.
What you need
- A bot. The widget is tied to it.
- A website with a real domain name that you control, served over HTTPS.
- A server that can verify the signature. Verification must not run in the browser.
Step 1: Tell BotFather your domain
Send /setdomain to BotFather, choose the bot, and give the domain, for example example.com. Without this, the widget will not work on your pages. Use the exact domain you serve the page from. You can set one domain per bot, so use a separate bot for each site if needed.
Step 2: Add the widget
The simplest way is the script tag. Put it where the button should appear:
<script async src="https://telegram.org/js/telegram-widget.js?22"
data-telegram-login="YourBotUsername"
data-size="large"
data-auth-url="https://example.com/auth/telegram"
data-request-access="write"></script>
data-telegram-loginis the bot username without the at sign.data-auth-urlis where Telegram sends the user's browser with the data in the query string. Alternatively usedata-onauth="onTelegramAuth(user)"to receive the data in JavaScript and send it to your server yourself.data-request-access="write"asks permission to let the bot message the user. Omit it if you do not need that.- Other options include
data-size,data-radiusanddata-userpic.
The script version number in the URL can change, so copy the current snippet from the official page.
Step 3: What you receive
Telegram returns these fields:
id: the user's permanent Telegram id.first_name,last_name,username,photo_url: optional profile fields.auth_date: a Unix timestamp.hash: the signature.
It does not give an email address or a phone number.
Step 4: Verify on the server
The algorithm:
- Take all fields except
hash. - Sort them by key and join as
key=valuelines separated by\n. - Compute
secret_key = SHA256(bot_token)as raw bytes. - Compute
HMAC_SHA256(secret_key, data_check_string)as hex. - Compare to
hashwith a constant time comparison. - Check that
auth_dateis recent.
import crypto from "node:crypto";
export function verifyLogin(query, botToken, maxAge = 86400) {
const { hash, ...data } = query;
if (!hash) return null;
const check = Object.keys(data).sort().map((k) => `${k}=${data[k]}`).join("\n");
const secret = crypto.createHash("sha256").update(botToken).digest();
const calc = crypto.createHmac("sha256", secret).update(check).digest("hex");
const a = Buffer.from(calc, "hex"), b = Buffer.from(String(hash), "hex");
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return null;
if (Date.now() / 1000 - Number(data.auth_date) > maxAge) return null;
return data;
}
Notice the difference from Mini Apps: the secret here is the SHA-256 of the token, not an HMAC with the WebAppData key. See which signature to verify and Mini App initData.
Step 5: Start your session
If verification passes, find or create the user by id, then set your own session cookie with sensible flags: HttpOnly, Secure and SameSite. Do not keep using the raw Telegram parameters as a session. Expire sessions and allow logout.
Linking with the bot
If you also run a bot, the same id is the chat id for private messages, so you can message users who allowed it. See connecting your backend.
Common mistakes
- Doing the check in the browser, or not checking at all.
- Forgetting
/setdomainor using the wrong domain. - Serving over plain HTTP.
- Sorting or joining fields incorrectly, or including
hashin the string. - Accepting old
auth_datevalues. - Trusting
photo_urlas a safe image without handling errors. - Using the Mini App formula for the widget, or the reverse.
Privacy
Collect only what you need and explain it in your privacy note. Telegram usernames can change, so key by id. Offer a way to delete the account.
Quick checklist
- /setdomain set to your exact domain.
- Widget script copied from the official page.
- Verification code runs on the server.
- auth_date checked for freshness.
- Your own session cookie is HttpOnly, Secure and SameSite.
- Users keyed by id, not username.
- A privacy note explains what is stored.
- Account deletion is possible.
Fallbacks
Some people cannot or will not use Telegram login. Offer another way in if your service needs to be open to everyone, and consider letting people link Telegram to an existing account after they sign in.
Frequently asked questions
Does the widget work on localhost?
Telegram requires a real domain. Use a tunnel with a test domain and set it in BotFather.
Can I get the user's phone number?
Not through this widget. Bots can request a contact separately, with the user's consent.
Is there a widget for mobile apps?
Mobile apps usually link to the bot or a Mini App. See Telegram's documentation for other login options.
How long is the signature valid?
As long as you accept it. Reject old auth_date values.
Related guides

Which Telegram Signature to Verify: initData, Login Widget or Webhook
Telegram uses three different ways to prove data came from it. Compare initData, the Login Widget hash and the webhook secret token, with a decision table.

Validate Telegram Mini App initData on Your Server
Why initData must be verified, how the HMAC check works step by step, a Node.js example, auth_date freshness and common mistakes.

BotFather Commands: What Each One Does
A reference to BotFather, Telegram's tool for creating and managing bots: the main commands, settings menus, what they change and what to watch out for.

Connect Your Backend to a Telegram Bot: A Practical Architecture
How to wire a bot to your own backend: receiving updates, mapping Telegram users to accounts, queues, database design, idempotency and safe deploys.

Keep Your Telegram Bot Token Safe (and What to Do if It Leaks)
A bot token is a password. Learn where tokens leak, how to store them, how to rotate with /revoke, how to detect misuse and a leak response checklist.

A Telegram Webhook on AWS Lambda or a Small Server
Two ways to receive Telegram updates: an AWS Lambda function URL and a tiny Node server behind HTTPS, with secret token checks, fast replies and queues.
More in Build on Telegram
- Add a Bot as Channel Admin and Post to Your Channel
- Bot Privacy Mode and Group Admin Rights Explained
- Common Telegram Bot Errors and How to Fix Them
- Connect a Bot to Your Telegram Business Account (Chatbot Mode)
All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial