For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Telegram sign-in with Embedded Wallets

Telegram Login lets users authenticate with a Telegram account. Choose the default connection for the quickest setup, or configure a custom connection when you need your own Telegram bot, branding, or identity provider.

The web SDK value for this provider is AUTH_CONNECTION.TELEGRAM. Mobile and gaming SDKs documented in this site don't include a Telegram AuthConnection value.

Default Telegram sign-in​

The default connection uses the Telegram credentials managed by Embedded Wallets. You don't need a Telegram bot.

Caveats​

  • The Telegram login widget identifies the application managed by Embedded Wallets, not your dapp.
  • You can't change the Telegram bot configuration, because you don't own the credentials.
  • The default connection and a custom connection are separate connections, so they produce different wallet addresses for the same person unless you link them with a group connection.

Configure the default connection​

  1. Open your project in the MetaMask Developer Dashboard.
  2. Select Social Connections.
  3. Enable Telegram.
Telegram in the Social Connections settings

The SDK reads the connection from the dashboard. You don't need to add Telegram credentials to your SDK configuration.

Custom Telegram sign-in​

Use a custom connection when Telegram authorization belongs to your bot or an identity platform you control. Your Telegram bot token sits in Auth0 or your own backend.

Telegram credentials can't go in the dashboard

Telegram Login is a widget authenticated with a bot token, not an OAuth 2.0 public client. You can't register a Telegram bot token as a social Client ID the way you can for Google, Discord, or Twitch.

Preserve wallet addresses

Decide between the default and a custom connection before you onboard users. Moving from the default Telegram connection to Auth0 or your own JWT connection changes every user's wallet address unless both connections are in a group connection with matching user identifiers.

Auth0​

Auth0 lists Telegram in the social connections catalog. Configure Telegram there, then create an Auth0 connection in the MetaMask Developer Dashboard. Set extraLoginOptions.connection to the name Auth0 assigned (commonly telegram).

Firebase Authentication and Amazon Cognito don't offer Telegram as a first-party social provider.

Your own backend​

  1. Complete Telegram Login Widget authentication in your client and send the signed payload to your backend.
  2. Verify the HMAC signature with your bot token as described in Telegram Login Widget before trusting the identity.
  3. Issue a fresh JWT with an iat no more than 60 seconds old and expose the signing public key through a JSON Web Key Set (JWKS) endpoint.
  4. Create a custom JWT connection that validates your issuer, audience, JWKS, and user identifier.
  5. Pass your JWT and custom connection ID to Embedded Wallets.

Don't send a Telegram bot token to a client application.

Group Telegram connections​

A group connection gives the same person one wallet address across several login methods.

Default Telegram and Telegram through Auth0 are separate connections. They produce different wallet addresses unless you group them and every connection in the group uses the same JWT user identifier (email or an aligned sub). Telegram often doesn't return an email address, so grouping with Google or email passwordless only works if you normalize another stable identifier.

Pass both the child connection ID and grouped connection ID when you bypass the modal:

await connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.CUSTOM,
  authConnectionId: '<TELEGRAM_AUTH_CONNECTION_ID>',
  groupedAuthConnectionId: '<GROUPED_AUTH_CONNECTION_ID>',
  idToken,
})

Usage examples​

The implicit examples open the default Telegram authorization flow on web. The JWT examples assume your Auth0 or backend integration has already returned a fresh ID token.

Default implicit flow

import { AUTH_CONNECTION, WALLET_CONNECTORS } from '@web3auth/modal'
import { useWeb3AuthConnect } from '@web3auth/modal/react'

const { connectTo } = useWeb3AuthConnect()

await connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.TELEGRAM,
})

Auth0 implicit flow

These examples use the Auth0 custom connection configured for your SDK. Replace the connection ID and domain with your Auth0 values. For Android and iOS, add the connection to authConnectionConfig during initialization. Flutter, Unity, and Unreal Engine currently use their platform's loginConfig; configure it by following the custom authentication guide for Flutter, Unity, or Unreal Engine.

await connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.CUSTOM,
  authConnectionId: '<AUTH0_CONNECTION_ID>',
  extraLoginOptions: {
    connection: 'telegram',
  },
})

JWT flow

Obtain a fresh ID token from your identity aggregator or backend before calling Embedded Wallets. The token issuer and claims must match the custom connection in the dashboard.

const idToken = await getIdToken()

await connectTo(WALLET_CONNECTORS.AUTH, {
  authConnection: AUTH_CONNECTION.CUSTOM,
  authConnectionId: '<CUSTOM_CONNECTION_ID>',
  idToken,
})
On this page