Telegram

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:

Field	Description
Bot token	The full bot token for this client’s Telegram bot
Bot name	The bot’s handle (e.g., `@MyMiniApp_bot`)
Enable seamless auth	Toggle 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.

To authenticate users with Privy’s out-of-the-box UIs, check out UI components.

Use the useLoginWithTelegram hook to authenticate users with Telegram.

login: () => Promise<void>;

Usage

import {useLoginWithTelegram} from '@privy-io/react-auth';

export default function LoginWithTelegram() {
  const {login, state} = useLoginWithTelegram();

  const handleLogin = async () => {
    try {
      const authenticationInfo = await login();
    } catch (err) {
      // Handle errors due to network availability, captcha failure, or input validation
    }
  };

  return <button onClick={handleLogin}>Log in with Telegram</button>;
}

Tracking flow state

Track the state of the Telegram authentication flow via the state variable returned by the useLoginWithTelegram hook.

type TelegramAuthFlowState =
  | {status: 'initial'}
  | {status: 'loading'}
  | {status: 'done'}
  | {status: 'error'; error: Error | null};

status

'initial' | 'loading' | 'done' | 'error'

The current state of the Telegram authentication flow.

error

Error | null

The error that occurred during the Telegram authentication flow.

Callbacks

Pass callbacks into the useLoginWithTelegram hook to run custom logic after a successful login or to handle errors.

`onComplete`

onComplete?: ((params: {
    user: User;
    isNewUser: boolean;
    wasAlreadyAuthenticated: boolean;
    loginMethod: LoginMethod | null;
    loginAccount: LinkedAccountWithMetadata | null;
}) => void) | undefined

Parameters

user

User

The user object corresponding to the authenticated user.

isNewUser

boolean

Whether the user is a new user or an existing user.

wasAlreadyAuthenticated

boolean

Whether the user entered the application already authenticated.

The method used by the user to login.

The account corresponding to the loginMethod used.

`onError`

onError: (error: Error) => void

Parameters

error

Error

The error that occurred during the login flow.

Resources

React starter repo

Get started with React and Privy.

Next.js starter repo

Get started with Next.js and Privy.

Whitelabel starter repo

Get started with a whitelabel Privy integration.

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 authentication in the Privy Dashboard under Telegram settings (or per-client via the app client Telegram override).
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:

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

Link Telegram

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

Field	Type	Description
type	`'telegram'`	Account type identifier
telegram_user_id	`string`	ID of the user’s Telegram account
first_name	`string`	First name displayed on the Telegram account
last_name	`string`	(Optional) Last name displayed on the Telegram account
username	`string`	(Optional) Username displayed on the Telegram account
photo_url	`string`	(Optional) URL of the Telegram account profile picture

Authentication

Using Privy authentication

Using your own authentication

Configure Telegram

Create a Telegram bot

Domain requirements

Content Security Policy

Secure your bot secret

Per-client configuration

How it works

Configure in the Dashboard

Usage

Tracking flow state

Callbacks

`onComplete`

Parameters

`onError`

Parameters

Resources

React starter repo

Next.js starter repo

Whitelabel starter repo

How it works

Linking Telegram accounts

Link Telegram

Seamless linking within a Mini App

TelegramAccount type

​Configure Telegram

​Create a Telegram bot

​Domain requirements

​Content Security Policy

​Secure your bot secret

​Per-client configuration

​How it works

​Configure in the Dashboard

​Standard login

​Usage

​Tracking flow state

​Callbacks

​onComplete

Parameters

​onError

Parameters

​Resources

React starter repo

Next.js starter repo

Whitelabel starter repo

​Seamless login

​How it works

​Enable seamless login

​Configure login methods (optional)

​Linking Telegram accounts

​Link Telegram

​Seamless linking within a Mini App

​TelegramAccount type

Configure Telegram

Create a Telegram bot

Domain requirements

Content Security Policy

Secure your bot secret

Per-client configuration

How it works

Configure in the Dashboard

Standard login

Usage

Tracking flow state

Callbacks

`onComplete`

`onError`

Resources

Seamless login

How it works

Enable seamless login

Configure login methods (optional)

Linking Telegram accounts

Link Telegram

Seamless linking within a Mini App

TelegramAccount type