Skip to main content
EVMSolana

​
Overview

Configure a Telegram bot to enable Telegram authentication for Embedded Wallets. This guide walks you through creating a bot via BotFather, configuring its domain, and integrating with CDP. Time to complete: ~10 minutes
React Native is not currently supported. Telegram social login is only available for web applications. React Native support is not yet available.

​
Prerequisites

Before you begin, ensure you have:
  • Telegram account: An active Telegram account
  • CDP Project ID: Available in your CDP Portal dashboard
  • Access to CDP Portal: Permission to configure Embedded Wallets settings

​
Step 1: Create a Telegram bot

  1. Open Telegram and search for @BotFather, or navigate directly to BotFather
  2. Start a conversation and send /newbot
  3. Follow the prompts:
    • Name: Enter a display name for your bot (e.g., “My App Login”)
    • Username: Enter a unique username ending in bot (e.g., myapp_auth_bot)
  4. BotFather will respond with your bot token — copy and save it immediately
Use your brand or application name as the bot username to prevent user confusion during the login flow. For example, if your app is called “Acme”, name your bot acme_auth_bot.

​
Step 2: Configure bot branding

The bot’s profile picture and name are displayed to users during the Telegram login flow. Configure these to match your application’s branding:
  1. In BotFather, send /setuserpic and select your bot
  2. Upload your application logo or brand image
  3. Optionally, send /setdescription to set a description users see when they open the bot

​
Step 3: Set the bot domain

Link your bot to the CDP callback domain so Telegram can route authentication requests:
  1. In BotFather, send /setdomain
  2. Select your bot from the list
  3. Enter the domain of your application

​
Step 4: Configure CDP Portal

Now that your bot is configured, add the credentials to CDP Portal:
  1. Navigate to the CDP Portal
  2. Select your project
  3. Go to Embedded Wallets > Authentication
  4. Find the Telegram section
  5. Toggle Enable Telegram to on
  6. Paste your Bot Token from Step 1
  7. Enter your Bot Username (e.g., myapp_auth_bot)
  8. Click Save Changes
Your Telegram configuration is now active. Any new authentication attempts will use your Telegram bot.

​
Step 5: Verification

Test your Telegram configuration:
  1. In your application, ensure you’re calling the Telegram sign-in method (see SDK Integration below)
  2. Click “Sign in with Telegram”
  3. Verify that the Telegram login widget shows your bot’s name and profile picture
  4. Complete the authentication flow
  5. Check that the user successfully signs in and their wallet is accessible

​
SDK Integration

Integrate Telegram authentication in your application using CDP’s SDK: 
import { useSignInWithOAuth } from '@coinbase/cdp-hooks';

function LoginButton() {
  const { signInWithOAuth } = useSignInWithOAuth();

  return (
    <button onClick={() => signInWithOAuth('telegram')}>
      Sign in with Telegram
    </button>
  );
}
The SDK automatically uses your Telegram bot configuration when available. No code changes are needed when updating your bot settings.

​
Production considerations

The bot token is the most critical credential in Telegram authentication:
  • Store securely: Use environment variables or a secrets manager — never commit to source control
  • Rotate periodically: Use BotFather’s /revoke command to generate a new token if compromised
  • Limit access: Restrict who can access the bot token in your organization
  • Monitor activity: Watch for unexpected authentication patterns that could indicate token compromise
If you suspect your bot token has been compromised, immediately revoke it via BotFather and update it in CDP Portal.
Users see your bot’s profile during the Telegram login flow:
  • Bot name: Use your official product name for brand recognition
  • Profile picture: Upload a high-quality logo that matches your app’s branding
  • Bot username: Choose something recognizable (e.g., yourapp_auth_bot)
  • Description: Set a clear description explaining the bot’s purpose
  • Domain verification: Ensure only api.cdp.coinbase.com is set as the bot domain
  • Token rotation: Rotate the bot token periodically and update CDP Portal accordingly
  • Access control: Limit who can manage the bot via BotFather
  • Monitoring: Track authentication attempts for anomalous patterns

​
Troubleshooting

Cause: The bot domain in BotFather doesn’t match the URL of your application.Solution:
  1. Open BotFather and send /setdomain
  2. Select your bot
  3. Set the domain to exactly match the URL you are initiating Telegram authentication from
  4. Try authentication again
Cause: The bot token in CDP Portal is incorrect, expired, or has been revoked.Solution:
  1. Open BotFather and send /token to view your current token
  2. If the token was revoked, send /revoke to generate a new one
  3. Update the token in CDP Portal
  4. Ensure no extra spaces or characters were copied
Cause: The bot username in CDP Portal doesn’t match the actual bot username.Solution:
  1. Open BotFather and send /mybots to see your bots
  2. Verify the exact username (including the bot suffix)
  3. Update the username in CDP Portal to match exactly
Cause: The bot’s profile hasn’t been configured or was recently changed.Solution:
  1. In BotFather, use /setuserpic to set or update the bot’s profile picture
  2. Use /setname to update the display name
  3. Changes may take a few minutes to propagate
Cause: This is likely an issue with your CDP configuration, not Telegram.Solution:
  1. Check CDP status page for potential outages
  2. Verify your CDP Project ID is correct in your application
  3. Ensure you’re using the latest SDK version
  4. Contact CDP support if the issue persists

Custom Social Login Overview

Return to social login overview

Google OAuth Setup

Configure Google OAuth

Apple OAuth Setup

Configure Apple Sign In

X OAuth Setup

Configure X OAuth