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: | Continue as signed in. |
400 | The body is invalid: no | A generic error. Check the request. |
401 | The | "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: | For the two account reasons, tell the player why, and when a self-exclusion ends. |
409 |
| Retry the same call without |
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 reads
telegram.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.