TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Telegram Login Widget: Sign In With Telegram on a Website

· 4 min read · 18+ readers

Telegram Login Widget: Sign In With Telegram on a Website: TSocial guide cover card

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 icon 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 code icon 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-login is the bot username without the at sign.
  • data-auth-url is where Telegram sends the user's browser with the data in the query string. Alternatively use data-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-radius and data-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:

  1. Take all fields except hash.
  2. Sort them by key and join as key=value lines separated by \n.
  3. Compute secret_key = SHA256(bot_token) as raw bytes.
  4. Compute HMAC_SHA256(secret_key, data_check_string) as hex.
  5. Compare to hash with a constant time comparison.
  6. Check that auth_date is 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 App icon (grid) 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 /setdomain or using the wrong domain.
  • Serving over plain HTTP.
  • Sorting or joining fields incorrectly, or including hash in the string.
  • Accepting old auth_date values.
  • Trusting photo_url as a safety icon 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 icon 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

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Telegram Login Widget: Sign In With Telegram on a Website | TSocial