Appearance
Telegram sign-in
"Continue with Telegram" uses Telegram's official login with a bot you create. It's free and takes about 10 minutes. Telegram never shares an email address, so new users add an email or phone number once.
You need
A Telegram account (on your phone or desktop), the site live on its final domain, and access to .env.
Create the bot
- In Telegram, open @BotFather (check for the blue verified tick) and send
/newbot. - Name: what users see on the login screen, for example
YourExchange. - Username: must end in
bot, for exampleYourExchangeBot. - BotFather replies with the token, which looks like
7123456789:AAH.... Keep it secret: anyone with it controls the bot and can fake sign-in data.
Optional: send /setuserpic to give the bot your logo and /setdescription to describe it. Users see these on the login screen.
Link the bot to your domain
Telegram only allows sign-in on the domain you set:
- Send
/setdomainto @BotFather and choose your bot. - Send your domain exactly as in
APP_URL, withouthttps://, for exampleyourdomain.com(orwww.yourdomain.comif that is yourAPP_URL).
You can use one domain per bot. A test or demo site on another domain needs its own bot.
Fill in .env
ini
TELEGRAM_BOT_TOKEN=7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_BOT_USERNAME=YourExchangeBot
TELEGRAM_AUTH_ENABLED=trueTELEGRAM_BOT_USERNAMEis without the@.- The button appears as soon as the token is set.
TELEGRAM_AUTH_ENABLED=falsehides it while keeping the token. APP_URLmust be the domain you gave/setdomain. Telegram checks it.
bash
php artisan config:clearHow sign-in works
- The visitor clicks Telegram and goes to Telegram's own login page (
oauth.telegram.org). They enter their phone number there and confirm in the Telegram app. The site never sees the number. - Telegram may ask them to let your bot send messages ("request access to write"). The site asks for this so the bot can message users later if you build that. It does not send anything today.
- Telegram returns to
https://yourdomain.com/auth/telegram/return, the site checks Telegram's signature with your bot token, and:- an account that connected this Telegram account is signed in (2FA still applies);
- otherwise the visitor lands on Complete sign-up: they enter an email or phone number, get a 6-digit code, and the account is created with Telegram connected. If that email or phone already has an account, Telegram is connected to it instead.
Existing users can connect Telegram under Connected accounts, then sign in with it from then on.
Sign-in results are accepted for up to one day after Telegram creates them, and every result is checked against the bot token. Forged or edited data is refused.
Test it
- Open
https://yourdomain.com/loginin a private window → the Telegram button. - Enter your phone number on Telegram's page and confirm in Telegram.
- A new Telegram user sees Complete sign-up. A connected one is signed in.
- In the app: Sign in → Telegram works the same way.
Common errors
| What you see | Cause and fix |
|---|---|
| Telegram page: Bot domain invalid | /setdomain wasn't run, or it differs from the APP_URL domain (www counts). Run /setdomain again. |
| Our page: Telegram authentication failed. | The signature didn't match: the TELEGRAM_BOT_TOKEN in .env is wrong or old (did you /revoke it?), or config:clear wasn't run. Also shown for results older than a day. |
| No Telegram button | TELEGRAM_BOT_TOKEN is empty or TELEGRAM_AUTH_ENABLED=false. Run config:clear. |
| The page after Telegram stays blank | That page needs JavaScript to pass Telegram's answer on. Ask the user to allow JavaScript, or try another browser. |
If the token leaks
Send /revoke to @BotFather, choose the bot, put the new token in TELEGRAM_BOT_TOKEN and run config:clear. Users who connected Telegram keep working: accounts are linked by their Telegram user ID, not by the bot.
