> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Authenticate users with their Telegram account via standard login or seamless Mini App authentication

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.

<Tip>
  Enable Telegram authentication in the [Privy
  Dashboard](https://dashboard.privy.io/apps?page=login-methods\&logins=socials) before implementing
  this feature.
</Tip>

## Configure Telegram

### Create a Telegram bot

Follow [this guide](https://core.telegram.org/bots/tutorial#obtain-your-bot-token) 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](https://dashboard.privy.io/apps?page=login-methods\&logins=socials):

* 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.

<Info>
  Since the bot's allowed domain must match your app's domain, use a tunneling tool for local
  development such as [Cloudflare
  tunnels](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/) or
  [ngrok](https://ngrok.com/).
</Info>

### 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)

<Tip>
  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](https://dashboard.privy.io?page=settings).
</Tip>

### Secure your bot secret

<Warning>
  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.**
</Warning>

## 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**.

## Standard login

<View title="React" icon="react">
  <Info>
    To authenticate users with Privy's out-of-the-box UIs, check out [UI
    components](/authentication/user-authentication/ui-component).
  </Info>

  Use the `useLoginWithTelegram` hook to authenticate users with Telegram.

  ```tsx theme={"system"}
  login: () => Promise<void>;
  ```

  ### Usage

  ```tsx theme={"system"}
  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.

  ```ts theme={"system"}
  type TelegramAuthFlowState =
    | {status: 'initial'}
    | {status: 'loading'}
    | {status: 'done'}
    | {status: 'error'; error: Error | null};
  ```

  <ResponseField name="status" type="'initial' | 'loading' | 'done' | 'error'">
    The current state of the Telegram authentication flow.
  </ResponseField>

  <ResponseField name="error" type="Error | null">
    The error that occurred during the Telegram authentication flow.
  </ResponseField>

  ### Callbacks

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

  #### `onComplete`

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

  ##### Parameters

  <ParamField path="user" type="User">
    The user object corresponding to the authenticated user.
  </ParamField>

  <ParamField path="isNewUser" type="boolean">
    Whether the user is a new user or an existing user.
  </ParamField>

  <ParamField path="wasAlreadyAuthenticated" type="boolean">
    Whether the user entered the application already authenticated.
  </ParamField>

  <ParamField path="loginMethod" type="LoginMethod | null">
    The method used by the user to login.
  </ParamField>

  <ParamField path="loginAccount" type="LinkedAccountWithMetadata | null">
    The account corresponding to the loginMethod used.
  </ParamField>

  #### `onError`

  ```tsx theme={"system"}
  onError: (error: Error) => void
  ```

  ##### Parameters

  <ParamField path="error" type="Error">
    The error that occurred during the login flow.
  </ParamField>

  ### Resources

  <Columns cols={3}>
    <Card title="React starter repo" href="https://github.com/privy-io/examples/tree/main/privy-react-starter" icon="github" arrow="true">
      Get started with React and Privy.
    </Card>

    <Card title="Next.js starter repo" href="https://github.com/privy-io/examples/tree/main/privy-next-starter" icon="github" arrow="true">
      Get started with Next.js and Privy.
    </Card>

    <Card title="Whitelabel starter repo" href="https://github.com/privy-io/examples/tree/main/privy-react-whitelabel-starter" icon="github" arrow="true">
      Get started with a whitelabel Privy integration.
    </Card>
  </Columns>
</View>

<View title="Android" icon="android">
  On Android, Telegram authentication is supported via OAuth. Follow the [OAuth integration guide](/authentication/user-authentication/login-methods/oauth#android) to set up Telegram login in your mobile application.
</View>

<View title="Swift" icon="swift">
  On iOS, Telegram authentication is supported via OAuth. Follow the [OAuth integration guide](/authentication/user-authentication/login-methods/oauth#swift) to set up Telegram login in your mobile application.
</View>

<View title="Flutter" icon="flutter">
  On Flutter, Telegram authentication is supported via OAuth. Follow the [OAuth integration guide](/authentication/user-authentication/login-methods/oauth#flutter) to set up Telegram login in your mobile application.
</View>

<View title="React Native" icon="react">
  On Expo, Telegram authentication is supported via OAuth. Follow the [OAuth integration guide](/authentication/user-authentication/login-methods/oauth#react-native) to set up Telegram login in your mobile application.
</View>

## 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](https://dashboard.privy.io/apps?page=login-methods\&logins=socials) under Telegram settings (or per-client via the app client Telegram override).
2. Send your website URL via one of these Telegram bot methods:

```jsx theme={"system"}
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:

* [KeyboardButton](https://core.telegram.org/bots/api#keyboardbutton)
* [InlineKeyboardButton](https://core.telegram.org/bots/api#inlinekeyboardbutton)

### 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.

```jsx theme={"system"}
<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.

```jsx theme={"system"}
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`:

```jsx theme={"system"}
import {retrieveLaunchParams} from '@telegram-apps/bridge';

const {linkTelegram} = usePrivy();
const launchParams = retrieveLaunchParams();
linkTelegram({launchParams});
```

<Warning>Telegram `launchParams` are treated as expired after five minutes for security.</Warning>

## TelegramAccount type

The `user` object contains information about [all accounts](/user-management/users/the-user-object) 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 |