Skip to main content
Telegram is an end to end encrypted messaging platform with in-application experiences. Privy enables your application to easily integrate Login with Telegram in multiple ways. From a regular web environment, users can authenticate to your application with their Telegram account.
Enable Telegram authentication in the Privy Dashboard before implementing this feature.
Telegram does not support .xyz domains for authentication. If your application uses a .xyz domain, Telegram will not send authentication messages during the login flow. To work around this limitation, you must use a different top-level domain (TLD) for your application, or set up a separate domain with a different TLD specifically for handling Telegram authentication.
Privy also enables seamless login within Telegram, so users can zero-click authenticate to your Telegram bot or mini-app. Check out our recipe for setting up seamless login with Telegram.
  • React
To authenticate your users with Privy’s out of the box UIs, check out UI components here.
To authenticate your users with Telegram, use the useLoginWithTelegram hook.
login: () => Promise<void>

​
Usage

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

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

  const handleLogin = async () => {
    try {
      // Telegram's authentication pop-up will emerge, the user can then follow the steps to link its account.
      // If the login is successful, the user will be authenticated and the authentication information will be returned as a result
      const authenticationInfo = await login();
    } catch (err) {
      // Handle errors due to network availability, captcha failure, or input validation here
    }
  };

  return <button onClick={handleLogin}>Log in with Telegram</button>;
}
Before using the useLoginWithTelegram hook, ensure that Telegram is enabled in Socials tab of the Login Methods page on the the Privy dashboard

​
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

You can optionally pass callbacks into the useLoginWithTelegram hook to run custom logic after a successful login or to handle errors that occur during the flow.

​
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.
​
loginMethod
LoginMethod | null
The method used by the user to login.
​
loginAccount
LinkedAccountWithMetadata | null
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.
⌘I