Log in with Telegram using Privy

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

You need to request access to Telegram from the login methods page.

Configure Telegram login

Once you have access, 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
• Bot name

Note that when configuring Telegram login:

• Your domain must be configured as your bot's allowed domain.
• 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.

TIP

To use your app as a Telegram Mini-App in the Telegram web client, add http://web.telegram.org to your allowed domains in the dashboard Settings page.

INFO

Since you need to set your bot's allowed domain you'll need to use a tunneling tool for local development such as Cloudflare tunel or ngrok.

Essential: Secure your bot secret

WARNING

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.

• If enabled, Privy will automatically log your user in when your user initiates login from within Telegram. You do not have to call login from the usePrivy hook in this case!
• To enable seamless login, send your website URL using KeyboardButton.web_app, InlineKeyboardButton.web_app or InlineKeyboardButton.login_url or use a direct link (ex: t.me/xxx_bot/xxx)
• For reference, see these docs:
  • https://core.telegram.org/bots/api#keyboardbutton
  • https://core.telegram.org/bots/api#inlinekeyboardbutton

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.

Link Telegram

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:

• linkTelegram: https://docs.privy.io/reference/sdk/react-auth/interfaces/PrivyInterface#linktelegram
• unlinkTelegram: https://docs.privy.io/reference/sdk/react-auth/interfaces/PrivyInterface#unlinktelegram

const {linkTelegram, unlinkTelegram} = usePrivy();

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

Field	Type	Description
type	'telegram'	N/A
telegram_user_id	string	ID of a user's telegram account.
first_name	string	The first name displayed on a user's telegram account.
last_name	string	(Optional) The last name displayed on a user's telegram account.
username	string	(Optional) The username displayed on a user's telegram account.
photo_url	string	(Optional) The url of a user's telegram account profile picture.