Skip to main content

Moving your frontend to the new Telegram Login

For operators who build their own casino frontend on the DeGaming public API. It takes your site from the legacy Telegram Login Widget to Telegram Login (OpenID Connect). The change is in the browser only: the API endpoint stays the same and accepts both

Why switch

Legacy widget · telegram-widget.js

The browser receives the player's Telegram data with a hash signed using your bot token. Anyone who gets hold of the token can sign data for any Telegram user and sign in as them.

Telegram Login · telegram-login.js

The browser receives an id_token signed by Telegram's own keys, which we verify against Telegram's published key set. A leaked bot token can't be used to forge a sign-in.

Steps

1

Allow your site's origins in @BotFather

Telegram Login only opens for the origins you allow on the bot. In @BotFather, open your bot's settings and add every origin your casino runs on to its Allowed URLs, for example https://yourcasino.com and https://www.yourcasino.com. Subdomains and www. count as separate origins.

2

Ask us to turn on Telegram Login for your site

Tell us in your support channel when step 1 is done, and we switch your site to OpenID Connect. Your sign-in methods call then reports it:

Copy

GET {API_BASE}/signin  {   "telegram": {     "username": "your_casino_bot",     "botId": 123456789,     "openIdConnect": true   },   ... }

Read openIdConnect at runtime. Show the new login when it is true and the legacy widget when it is false, so you can ship the frontend before we switch the site over. Use botId as the client_id in step 4.

3

Load telegram-login.js

Load Telegram's script instead of telegram-widget.js. It defines window.Telegram.Login.

Copy

<script async src="https://oauth.telegram.org/js/telegram-login.js?6"></script>

Don't load it inside the Telegram Mini App

When your site runs as a Mini App, telegram-login.js replaces window.Telegram.WebView, and the Mini App's back button, viewport and theme events stop reaching telegram-web-app.js. Inside the Mini App, keep signing in with initData (see "Mini App" below).

4

Open Telegram Login when the player clicks

Call Telegram.Login.auth from your "Sign in with Telegram" button with the bot id as client_id and the profile scope. Call it from the click handler itself, so the browser allows the popup.

Copy

button.addEventListener("click", () => {   window.Telegram.Login.auth(     { client_id: botId, scope: ["profile"] },     (result) => {       if (result.id_token === undefined) {         return; // the player closed the window or declined       }       signInWithTelegram(result.id_token);     },   ); });

5

Send the id_token to the platform

Post it to the same endpoint the widget used. Send it from the browser the same way as your other sign-in calls, so the session cookie is set. Referral and affiliate fields work as they did with the widget.

Copy

const signInWithTelegram = async (idToken) => {   const response = await fetch(`${API_BASE}/signin/telegram/verify`, {     method: "POST",     credentials: "include",     headers: { "Content-Type": "application/json" },     body: JSON.stringify({       id_token: idToken,       // optional, as before:       // referral_code: "...",       // source: "scaleo",       // affiliate_id: 123,     }),   });   // 200: { "data": { "id": "<account id>", "nickname": "..." } } };

A new Telegram user gets an account; a returning one is signed in to theirs. A player who signed up with the legacy widget is signed in to the same account with the new login, because both carry the same Telegram id.

6

Linking Telegram to a signed-in account

If your account page lets a player link Telegram, send the id_token from the same Telegram.Login.auth call to the linking endpoint instead:

Copy

POST {API_BASE}/profile/authenticators/telegram { "id_token": "<id_token>" }

The response is the linked Telegram authenticator. It answers 409 when that Telegram account is already linked to another player.

Responses from POST /signin/telegram/verify

Status

When

What to show

200

Signed in or signed up. Body: { data: { id, nickname } }.

Continue as signed in.

400

The body is invalid: no id_token, or an invalid field.

A generic error. Check the request.

401

The id_token is invalid, expired or not issued for your bot.

"Couldn't sign you in with Telegram, please try again."

403

Telegram isn't set up for the site, the region is blocked, or the account is unavailable: details.reason is ACCOUNT_CLOSED, or ACCOUNT_SELF_EXCLUDED with details.endsAt.

For the two account reasons, tell the player why, and when a self-exclusion ends.

409

details.code is REFERRAL_CODE_CONFLICT: the referral code is already claimed.

Retry the same call without referral_code.

500

Something failed on our side.

"Something went wrong, please try again."

Mini App

Nothing changes for the Telegram Mini App. It keeps signing in with the initData Telegram gives the Mini App, posted to POST {API_BASE}/signin/telegram/mini-app as { "init_data": "..." }. Only the button on your website moves to Telegram Login.

Checklist

  • Every origin of your casino is in the bot's Allowed URLs in @BotFather.

  • Your frontend readstelegram.openIdConnectfromGET /signinand shows the matching login.

  • telegram-login.jsloads on the website, and not inside the Mini App.

  • Sign-in posts{ id_token }to/signin/telegram/verify, and linking posts it to/profile/authenticators/telegram.

  • 401, 403 (with its reasons) and 409 are handled as above.

  • Tested on staging with a new Telegram user, a returning user and a player who signed up with the old widget.

  • We've switched your site to OpenID Connect.

  • After switching: rotate your bot tokenin @BotFather andsend the new token to DeGaming right awaythrough a private channel (a password manager share, not Slack or email). We still use the token to verify Mini App sign-ins, and until we replace the old one, sign-ins signed with it are still accepted. Store it only in your secret store, and never post it in Slack or commit it to a repository.

Building on the Northstar template?

Telegram Login is already implemented in the Northstar template, including the switch on openIdConnect and the Mini App exception. Update to the latest version of the template and do steps 1 and 2.

Questions or want us to check your setup? Ask in your DeGaming support channel. {API_BASE} is your site's DeGaming public API base URL, the one ending in /v1 that your frontend already calls.

Did this answer your question?