Skip to main content
Telegram is an end-to-end encrypted messaging platform with in-application experiences. Privy supports two Telegram authentication flows:
  • Standard login: Users authenticate via Telegram’s login widget from a regular web environment.
  • Seamless login: Users authenticate automatically (zero-click) when accessing your app from within a Telegram bot or Mini App.
Enable Telegram authentication in the Privy Dashboard before implementing this feature.

​
Configure Telegram

​
Create a Telegram bot

Follow this guide to create a Telegram bot. After creating the bot, set your domain using the /setdomain command in the @BotFather chat. Provide the following to Privy via the Dashboard:
  • Bot token (e.g., 1234567890:AzByCxDwEvFuGtHsIr1k2M4o5Q6s7U8w9Y0)
  • Bot handle (e.g., @MyBot_bot)

​
Domain requirements

  • Your domain must be configured as the bot’s allowed domain.
  • Telegram does not support .xyz domains. If your application uses a .xyz domain, use a different top-level domain for Telegram authentication.
Since the bot’s allowed domain must match your app’s domain, use a tunneling tool for local development such as Cloudflare tunnels or ngrok.

​
Content Security Policy

If your app enforces CSP, add these directives:
  • script-src: allow https://telegram.org (Telegram’s widget script)
  • frame-src: allow https://oauth.telegram.org (Telegram’s widget iframe)
To use your app as a Telegram Mini App in the Telegram web client, add http://web.telegram.org and https://web.telegram.org to your allowed domains in the Dashboard under Configuration > App settings > Domains.

​
Secure your bot secret

The bot secret controls the Telegram bot and is used as a symmetric key for authentication. Compromise of this key enables signing over authentication data, putting your users and their accounts at risk.Securing this key is essential for the security of all Telegram logins in your app.

​
Per-client configuration

Privy supports overriding Telegram bot credentials on a per-app-client basis. This is useful when different clients (e.g., a web app and a Mini App) need to authenticate through different Telegram bots.

​
How it works

Each app client can have its own Telegram configuration that takes precedence over the app-level default. If no client-specific override is set, the app-level configuration is used as a fallback.

​
Configure in the Dashboard

Navigate to App clients > select your client > Telegram credentials override and configure:
FieldDescription
Bot tokenThe full bot token for this client’s Telegram bot
Bot nameThe bot’s handle (e.g., @MyMiniApp_bot)
Enable seamless authToggle to allow zero-click login from within Telegram for this client
To remove the override and revert to the app-level default, select Remove override.

​
Standard login

​
Seamless login

Seamless login enables zero-click authentication for users who access your app from within a Telegram bot or Mini App. Privy automatically logs the user in without requiring them to interact with a login widget.

​
How it works

When a user opens your app via a Telegram bot command or Mini App link, Privy detects the Telegram context and authenticates the user automatically. Your app does not need to call login from the usePrivy hook.

​
Enable seamless login

  1. Enable seamless authentication in the Privy Dashboard under Telegram settings (or per-client via the app client Telegram override).
  2. Send your website URL via one of these Telegram bot methods:
bot.send_message(chat_id, 'Log in to demo!', {
  reply_markup: {
    inline_keyboard: [
      [
        {
          text: 'Login',
          login_url: {url: 'https://your-website-url'}
        },
        {
          text: 'Mini App',
          web_app: {url: 'https://your-website-url'}
        }
      ]
    ]
  }
});
You can also use a direct link (e.g., t.me/your_bot/your_app). For reference:

​
Configure login methods (optional)

If loginMethods is configured client-side in the PrivyProvider, add "telegram" to the list. Client-side login method configuration is only necessary to restrict logins to a subset of those configured in the Dashboard. 
<PrivyProvider
  appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID || ""}
  config={{
    loginMethods: ["email", "google", "telegram"],
  }}
>

​
Linking Telegram accounts

Use the linkTelegram method from the usePrivy hook to add Telegram accounts to a user, and the useUnlinkTelegram hook to remove them. 
import {usePrivy, useUnlinkTelegram} from '@privy-io/react-auth';

const {linkTelegram} = usePrivy();
const {unlink: unlinkTelegram} = useUnlinkTelegram();

​
Seamless linking within a Mini App

Within a Telegram Mini App, link a Telegram account seamlessly by passing launchParams: 
import {retrieveLaunchParams} from '@telegram-apps/bridge';

const {linkTelegram} = usePrivy();
const launchParams = retrieveLaunchParams();
linkTelegram({launchParams});
Telegram launchParams are treated as expired after five minutes for security.

​
TelegramAccount type

The user object contains information about all accounts a user has linked with Privy.
  • Use user.linkedAccounts to get all linked accounts
  • Use user.telegram to get the Telegram account
TelegramAccount extends LinkedAccount
FieldTypeDescription
type'telegram'Account type identifier
telegram_user_idstringID of the user’s Telegram account
first_namestringFirst name displayed on the Telegram account
last_namestring(Optional) Last name displayed on the Telegram account
usernamestring(Optional) Username displayed on the Telegram account
photo_urlstring(Optional) URL of the Telegram account profile picture