Skip to main content
Privy enables developers to quickly integrate Login with Telegram into their applications. With the Privy Telegram integration, users can log in with Telegram and link Telegram accounts. From a web environment, Privy enables Telegram login via the Telegram Login widget. Privy also enables seamless Telegram login directly from within a Telegram bot or within Telegram Mini-Apps!

​
Configure Telegram

​
Configure Telegram login

Follow this guide to create a telegram bot. After creating a Telegram bot, you must set your domain using the /setdomain command in the @BotFather chat. You will need to provide the following to Privy via the Privy Dashboard upon completion:
  • Bot token (eg: 1234567890:AzByCxDwEvFuGtHsIr1k2M4o5Q6s7U8w9Y0)
  • Bot handle (eg: @MyBot_bot)
Note that when configuring Telegram login:
  • Your domain must be configured as your bot’s allowed domain.
  • Important: Telegram does not support .xyz domains for authentication. If your application uses a .xyz domain, you must use a different top-level domain (TLD) for Telegram authentication to function properly.
  • If you have CSP enforcement, you’ll need to update these directives:
    • script-src must allow https://telegram.org in order to be able to download Telegram’s widget script.
    • frame-src must allow https://oauth.telegram.org in order to be able to render 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 Configuration > App settings > Domains tab.
Since you need to set your bot’s allowed domain you’ll need to use a tunneling tool for local development such as Cloudflare tunnels or ngrok.

​
Essential: Secure your bot secret

Telegram login requires developers to create a Telegram bot with a bot secret. This bot secret controls the Telegram bot and is also used as a symmetric key for authentication. Control over this key enables a developer to sign over authentication data, meaning compromise of this key puts your users (and their accounts) at risk.Securing this symmetric key is essential for the security of all of your app’s Telegram logins.

​
Integration interfaces

​
[optional] Enable Telegram in your client-side loginMethods

You must enable Telegram in the Privy Dashboard to enable login with Telegram. If you additionally have loginMethods configured client-side in your PrivyProvider config, make sure you add "telegram" to that list as well. Client-side login method configuration is only necessary if you want 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"],
      ...
    }}
  >

​
Seamless login with Telegram

You can integrate Privy to enable login directly from within a Telegram bot or Telegram mini-app. 
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'}
        }
      ]
    ]
  }
});

​
Login with Telegram

Once Telegram is enabled, you will automatically see Telegram in the Privy login modal. You can also list 'telegram' when configuring login methods client-side, in the PrivyProvider. You can use the linkTelegram and unlinkTelegram methods from the usePrivy hook to add or remove Telegram accounts from a user. See the SDK reference for more details: 
const {linkTelegram, unlinkTelegram} = usePrivy();
You can use the linkTelegram methods from the usePrivy hook within a Telegram Mini App to add to a user seamlessly by passing launchParams as a parameter. See the SDK reference for more details: 
// Sample library to retrieve 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 of the accounts a user has linked with Privy. 
Use the fields:
- **`user.linkAccounts`** to get a list of all the user's linked accounts
- **`user.telegram`** to get the user's Telegram account
TelegramAccount extends LinkedAccount
FieldTypeDescription
type’telegram’N/A
telegram_user_idstringID of a user’s telegram account.
first_namestringThe first name displayed on a user’s telegram account.
last_namestring(Optional) The last name displayed on a user’s telegram account.
usernamestring(Optional) The username displayed on a user’s telegram account.
photo_urlstring(Optional) The url of a user’s telegram account profile picture.