Add "Log In With Telegram" to Your Website

To add "Log In With Telegram" to your website, you create a Telegram bot with @BotFather, register your website with that bot, show Telegram's login button, and verify the signed data Telegram sends back on your server before signing the person in. Telegram confirms who the user is inside their Telegram app, so your site never sees their password or login code.

This guide explains the concepts, the two ways to integrate (Telegram's current sign-in flow based on OpenID Connect, and the older login widget many sites still run), how to verify each one in plain words, how to link Telegram identities to your own accounts, and how to fix the errors people hit most often. It describes the steps without code; the official developer pages hold the exact parameter names and should be your reference while building.

How Telegram login works

Every login involves three parties: the person signing in, Telegram, and your website. Your bot is how Telegram knows which website is asking.

1. The visitor clicks the Telegram login button on your site.
2. Telegram shows a confirmation, either in a popup or in the Telegram app, naming your bot and website.
3. The visitor approves.
4. Telegram sends your site a set of data about the user, signed so you can prove it came from Telegram.
5. Your server checks the signature. If it is valid, you sign the user in.

Step 5 is the whole security of the system. Anyone can send your site data that looks like a Telegram user. Only the signature proves Telegram vouched for it.

What you learn about the user

Telegram shares limited profile information:

• a permanent numeric user ID,
• first name and, if set, last name,
• username, if the user has one,
• a profile photo link, if available,
• the time of authentication.

With the current sign-in flow, a phone number can be requested as an optional extra, and the user must agree to share it. Telegram does not give you the user's email address or password.

The numeric ID is the only field you should rely on to identify someone. Names and usernames can change or be absent. Our guide to getting a Telegram chat or user ID explains what these IDs are.

What it is not

• It is not access to the user's Telegram account. You cannot read their chats or act as them.
• It is not the Telegram API ID used to build full Telegram apps. That is a different thing, covered in our guide to the Telegram API ID and hash.
• It is not Mini App authentication. If your site runs inside Telegram as a Mini App, Telegram passes launch data with its own, different verification. See our guide to building a Telegram Mini App.

Before you start

Have these ready:

1. A Telegram bot. Create one with @BotFather if you do not have one. Our guide to creating a bot with BotFather walks through it. The bot's name and photo appear on the login screen, so make them match your brand.
2. A domain served over HTTPS. Telegram ties login to registered addresses and expects a secure site.
3. A server-side component. Verification must happen on your server, where your secrets live. A purely static site cannot do it safely on its own.
4. A plan for accounts. Decide whether Telegram will be the only way to sign in, or one option beside email, and how you will link the two.
5. A privacy notice update. Say that you receive Telegram profile data, what you store and why.

Keep the bot token, and any client secret Telegram issues, out of your front-end code and your public repository. Anyone holding the token controls your bot.

Choosing an integration

Telegram's developer documentation now describes a sign-in flow built on the OpenID Connect standard, and lists the older JavaScript login widget as a legacy option. Both appear on live sites, so it helps to know each.

The current sign-in flow (OpenID Connect). It follows the same pattern as signing in with many other identity providers: your site redirects the user to Telegram, Telegram redirects back with a short-lived code, and your server exchanges that code for a signed token describing the user. If you already use an authentication library that supports OpenID Connect, this is usually the cleaner choice, and it supports extras like requesting a phone number with consent.

The legacy login widget. A small script on your page draws the button. After the user approves, the widget passes the user data and a hash either to a JavaScript function on your page or by redirecting to a URL you choose. Your server checks the hash using your bot token. It is simple and widely documented, but Telegram's documentation marks it as archived, so prefer the current flow for new projects unless you have a reason not to.

Login buttons inside Telegram. A bot can send a message with a special button that signs the user in to your website when tapped, without a separate approval screen. This is useful when users already talk to your bot. It uses the same kind of signed data as the widget.

Mini Apps. If your site runs inside Telegram, use the Mini App launch data instead of either login method.

The rest of this guide covers the first two in detail, because they are what most websites need.

Option A: the current sign-in flow (OpenID Connect)

This section assumes you use an OpenID Connect library for your language or framework, which is strongly recommended. Writing the protocol by hand is possible but easy to get subtly wrong.

Step 1: Register your site with your bot

1. Open @BotFather and select your bot.
2. Find the web login settings for the bot and add your allowed URLs. These include the website origin where the login button appears and the exact redirect address Telegram should send users back to after they approve.
3. Note the client ID and client secret BotFather gives you. Telegram's documentation says the client ID corresponds to your bot.

Telegram only completes logins and redirects to addresses you registered. A redirect address that differs by a single character, such as a missing trailing slash or http instead of https, will be refused.

Step 2: Configure your library

Telegram publishes a discovery document for its sign-in service. Most OpenID Connect libraries can read it automatically and fill in the authorization address, the token address and the public keys used to sign tokens. If your library needs them entered by hand, take them from Telegram's documentation.

Set:

• the client ID and client secret from BotFather,
• your registered redirect address,
• the response type to the authorization code flow,
• the scopes you need. The openid scope is required and gives you the user's identifier. The profile scope adds name, username and photo. The phone scope asks for the phone number and needs the user's consent.

Telegram's documentation notes that it does not currently offer a separate user-info endpoint; the user's details arrive inside the signed ID token. Some libraries try to call a user-info endpoint by default, so turn that off if login fails at that point.

Step 3: Start the login

When the user clicks your button, your server or library builds the authorization request. Alongside the client ID, redirect address and scopes, it includes:

• a state value, a random string you store in the user's session and check on return. It stops another site from tricking a visitor into completing a login they did not start.
• PKCE values, a code verifier you keep and a code challenge derived from it. Telegram recommends the SHA-256 method. PKCE stops an intercepted code from being usable by anyone else.
• a nonce, another random value that will appear inside the token so you can tie the token to this exact request.

The user is sent to Telegram, sees which bot and site are asking, and approves.

Step 4: Handle the redirect back

Telegram returns the user to your redirect address with a code and the state.

1. Check the state matches the one you stored. If it does not, stop.
2. Send the code to Telegram's token address from your server, together with your client ID, client secret, redirect address and the PKCE code verifier.
3. Receive the ID token.

Step 5: Validate the ID token

Do not read anything from the token until it passes these checks. A good library does them for you; confirm it is configured to.

1. Signature. Verify it with Telegram's published public keys. Telegram's documentation says tokens are signed with RS256 by default.
2. Issuer. It must be Telegram's sign-in service.
3. Audience. It must be your client ID.
4. Expiry. The token must not have expired.
5. Nonce. It must match the nonce you sent.

Only then read the user's identifier and profile details from it.

Step 6: Create your own session

Look up the Telegram user ID in your database. If you find a linked account, sign that user in. If not, create an account or start your linking flow, described later. Then issue your own session cookie as you would for any login. Do not keep using the Telegram token as your session.

Option B: the legacy login widget

Many existing sites use this, and some tutorials still describe it. If you maintain such a site, or have a reason to choose it, these are the steps.

Step 1: Link your domain to the bot

In @BotFather, send the set-domain command, choose your bot, and enter your website's domain. The widget only works on the domain linked to the bot. One bot has one linked domain for this purpose, so sites on several domains often use one bot per domain.

Step 2: Generate the button

Telegram's widget page lets you choose your bot, the button size, whether to show the user's photo, and how you want to receive the data:

• Callback. The widget calls a function on your page with the user data. Your page then sends that data to your server for checking.
• Redirect. The widget sends the browser to a URL you choose, with the user data in the query string. Your server checks it on arrival.

You can also ask for permission for your bot to send the user messages. If the user agrees, your bot can write to them later, for example to send login alerts or notifications.

Place the generated script where the button should appear.

Step 3: Verify the data on your server

The data contains the user fields, the authentication time, and a field called hash. Verification works like this, described in words:

1. Take every field you received except hash.
2. Write each as the field name, an equals sign, and the value.
3. Sort these lines alphabetically by field name.
4. Join them into one string, separated by line-feed characters. This is the data-check-string.
5. Compute the SHA-256 digest of your bot token. This digest is the secret key.
6. Compute an HMAC-SHA-256 of the data-check-string, using that secret key.
7. Convert the result to lowercase hexadecimal and compare it with the hash you received. Use a constant-time comparison so the check does not leak timing information.
8. Check that the authentication time is recent. Telegram recommends checking it so old data cannot be replayed. Many sites accept only data from the last day, or much less.

If any step fails, refuse the login.

Step 4: Create your session

As with the current flow, look up the user ID, sign in or create the account, and issue your own session.

Details that break verification

• Use exactly the fields received. Do not add fields that were not sent or remove ones that were. Users without a username or photo simply do not have those fields.
• Decode values first. In the redirect method, values arrive URL-encoded. Build the check string from the decoded values.
• Use the right key. The secret is the SHA-256 digest of the token, not the token itself and not an HMAC of it. Mini Apps use a different key derivation, and mixing the two gives a hash that never matches.
• Use the current token. If you regenerated the bot token in BotFather, old code using the previous one will fail every login.

Linking Telegram to your existing accounts

If your site already has email accounts, plan how Telegram identities join them. Mistakes here cause either duplicate accounts or, worse, one person getting into another's account.

Use the Telegram user ID as the key

Store the numeric Telegram ID against the account. Never identify a user by Telegram username or display name. A username can be released and claimed by someone else, and names are not unique.

Link only from a signed-in session

The safe pattern:

1. The user signs in with their existing method, such as email and password.
2. In account settings, they choose "Connect Telegram".
3. They complete the Telegram login.
4. You attach the verified Telegram ID to the account that is currently signed in.

Do not merge accounts automatically because a Telegram name matches an existing name, or because a phone number looks the same. Matching on unverified details is how accounts get taken over.

New users who arrive through Telegram

Create a new account keyed by the Telegram ID. Remember it has no email address. If your site sends email, ask for one separately and verify it, or design the features that need email to work without it.

Unlinking

Let users disconnect Telegram from their account. If Telegram is their only login method, ask them to add another one first, or they will lock themselves out.

Messaging users after login

A login on its own does not let your bot message the user. A bot can only write to people who have started it or allowed it to.

• With the legacy widget, ask for write access when generating the button. Users who agree can receive messages from your bot.
• Otherwise, invite users to open your bot and press Start, for example with a link on their account page.

Use this for useful things the user expects, such as security alerts or order updates. Unwanted promotional messages lead to blocks and reports. Our guide to sending broadcast messages to bot subscribers covers consent and rate limits.

Designing the login experience

A correct integration can still lose users if the flow confuses them. A few choices make a big difference.

Place the button where people expect it

Put it beside your other sign-in options, with the same size and weight. If Telegram is the main way your audience signs in, for example a site built around a Telegram community, put it first.

Explain what happens next

On a phone, approving a login often means switching to the Telegram app and back to the browser. People who are not expecting that may think something broke. A short line under the button, such as "You will confirm in Telegram, then return here", reduces abandoned logins.

Plan for people without Telegram

Unless your site is only for Telegram users, keep another way to sign in. Someone who does not use Telegram should never reach a dead end.

Handle the return gracefully

After approval, send the user back to the page they were on, not always to the home page. Store the page they started from before the login begins, and return them to it afterwards.

Show which account is connected

On the account page, show the connected Telegram name and photo, and a clear button to disconnect. People who use several Telegram accounts need to see which one they linked.

Worked example: a community forum

This is a hypothetical project to show how the pieces fit together.

A forum for a hobby community already has email accounts. Most members also belong to its Telegram group, and many have asked to sign in with Telegram.

The team decides:

1. Create a bot named after the forum, with the forum's logo.
2. Use the current sign-in flow, because their framework already has an OpenID Connect library.
3. Request only the openid and profile scopes. They have no use for phone numbers, so they do not ask.
4. On the login page, show "Log in with Telegram" beside the email form.
5. For a visitor whose Telegram ID is not yet known, show two choices: "Create a new forum account" or "I already have an account". The second asks them to sign in with email first and then links Telegram from their settings.
6. On each login, refresh the stored display name and photo from the token.
7. Invite members to start the bot from their settings page if they want reply notifications. Only those who press Start receive messages.

The result is a login that existing members can adopt without losing their history, and new members can use without creating a password.

Security checklist

1. Keep the bot token and client secret only on the server, in environment variables or a secret store.
2. Verify every login on the server, never in the browser.
3. Check the authentication time or token expiry, so old data cannot be replayed.
4. Use the state value and PKCE in the current flow.
5. Serve every page involved over HTTPS.
6. Store the Telegram ID, not the username, as the identifier.
7. Log failed verifications without logging the full data, which contains personal details.
8. If the bot token leaks, revoke it in BotFather straight away and deploy the new one.
9. Treat the profile photo link as external content, and consider copying the image to your own storage if you display it widely.

Testing your integration

Domain and address issues during development

Telegram only accepts logins from registered addresses. A local development address usually will not match. Common approaches are a separate test bot registered to a staging domain, or a secure tunnel that gives your local server a public HTTPS address you can register.

Use a separate bot for testing so you never put production secrets on a development machine.

Test cases worth running

1. A user with a username, photo and last name.
2. A user without a username or photo.
3. A user who cancels at the approval screen.
4. Data with one character changed in a field. It must be refused.
5. Data with an old authentication time. It must be refused.
6. For the current flow, a return with a wrong state value. It must be refused.
7. The same user logging in twice. It must reach the same account.
8. Linking Telegram to an account that already has it linked to someone else. It must be refused.

Troubleshooting

"Bot domain invalid" or the button does not appear

The domain linked to the bot does not match the page. Check the domain you registered, including whether you used the bare domain or a subdomain. After changing it, reload the page fully.

The approval popup opens but no data arrives

• Pop-up blockers or strict browser privacy settings can interfere. Try another browser to confirm.
• Some in-app browsers handle popups poorly. The redirect method, or the current sign-in flow, tends to work better there.
• Check your callback function name or redirect URL matches what the widget was generated with.

The hash never matches

Work through the list in "Details that break verification". The most common causes are building the string from URL-encoded values, using the token directly as the key, and using an old token.

The token exchange fails in the current flow

• The redirect address must exactly match the registered one.
• The code is single-use and short-lived; a page refresh can try to use it twice.
• The code verifier must be the one created for this login.
• Check the client secret is the latest one BotFather issued.

The library fails after the token exchange

It may be trying to call a user-info endpoint, which Telegram does not currently provide. Read the user details from the ID token instead.

Users see the wrong name or picture

Telegram sends the profile at the time of login. Update your stored name and photo on each login if you want them to stay current.

Privacy and user control

Tell users plainly what you receive and keep. A short line next to the button helps: for example, that you will receive their Telegram name, username and photo, and never their messages or phone number unless they choose to share it.

Users can review and disconnect websites they logged into with Telegram from inside Telegram's settings. If someone disconnects, your existing session for them is not automatically ended, so offer a normal "log out" and account deletion on your site as well.

Store only what you use. If you do not display photos, do not keep the photo link. If you request a phone number, have a clear reason. Data protection laws differ by country; this is general information, not legal advice.

Common mistakes

• Checking the login in the browser. Front-end checks can be bypassed. Verification belongs on the server.
• Putting the bot token in page code. Anyone can read it and take over your bot.
• Identifying users by username. Usernames change and can be reused by other people.
• Skipping the time check. Without it, captured login data can be replayed later.
• Merging accounts on matching names. Link only from a signed-in session.
• Mixing up widget and Mini App verification. They use different secret keys and different data.
• Forgetting users without usernames. Code that assumes a username will break for them.

FAQ

Is Telegram login free?

Yes. Creating a bot and using Telegram login for your website does not cost anything from Telegram.

Does Telegram give me the user's email or phone number?

Not the email. With the current sign-in flow you can request the phone number, and the user must agree to share it. The legacy widget does not provide a phone number.

Can I use one bot for login on several websites?

With the current flow you can register several allowed addresses for one bot. With the legacy widget, a bot is linked to one domain, so separate domains usually need separate bots.

Should I use the new flow or the old widget?

For a new site, the current sign-in flow is the one Telegram's documentation now describes as standard, and it works with common authentication libraries. Keep the widget if you already have a working, correctly verified setup and no need to change.

How is this different from Telegram Passport?

Telegram login proves which Telegram account a visitor has. Telegram Passport lets users share identity documents they stored with Telegram, for services that need them. Our guide to Telegram Passport explains it.

Can I add a Telegram chat button instead of a login?

Yes, if you just want visitors to message you. That needs no bot or verification. See our guide to adding a Telegram chat button.

Summary

Telegram login lets visitors sign in to your website with the Telegram account they already have. Create a bot, register your site with it, show Telegram's button, and verify every login on your server: with the current flow by validating the signed ID token, or with the legacy widget by recomputing the hash from your bot token and checking the authentication time. Identify users by their numeric Telegram ID, link accounts only from a signed-in session, keep secrets off the front end, and tell users what you store. Use Telegram's developer documentation as the reference for exact parameter names, since they can change.