Create a wallet in a single-click from your telegram mini-app.

Introduction

Attention Required: Telegram Bot Secret Security

To use automatic wallet creation for Telegram, developers must create a Telegram bot configured with a bot secret, which serves as both the control mechanism for the bot and as a symmetric key for authentication. This key technically grants the developer an ability to sign authentication data and actions with a wallet. Any compromise of the bot secret internally or externally can expose users and their accounts to significant risk. Securing this symmetric key is critical to ensuring the integrity of all Telegram login sessions in your application.

No transactional MFA must also be enabled to use this feature. Please let us know in Slack if you need it by DMing Matthew Foyle your Environment ID along with a description of your request.

Seamless Telegram Login with Telegram Web Apps improves user experience by enabling quick access directly within Telegram Messenger. Users can launch a mini app and get automatically logged in.

Live example of a Dynamic Seamless Telegram Login @DynamicMiniAppBot on Telegram App.

Live Demo

🤖 Open Dynamic Mini App Bot in Telegram

Integration guide

To begin, you can clone the provided Mini App example and repository as a foundation for your project.

Step-by-Step Instructions

  1. Create an Account on Dynamic

  2. Clone the Repository and Deploy

    • Clone Mini App example and repository to your local machine.
    • Follow steps in the README
    • Deploy the application online. With Next.js, you can deploy a web app within minutes. Follow the deployment instructions here.
  3. Create a Telegram App and Bot

    • Use BotFather to create a new app and bot. For detailed steps, refer to our comprehensive guide here.
  4. Configure Settings in Dynamic Dashboard

  5. Update Bot Configuration

    • Use the Bot TOKEN from Telegram and set your web app URL as the LOGIN_URL in scripts/bot.ts or add them as environment variables.
  6. Run the Telegram Bot

    • Run the Telegram bot using the following command:
      npx ts-node scripts/bot.ts
      
  7. Start the Bot in Telegram

    • Open Telegram, go to your newly created bot, and type /start.

Success!

You should now have Dynamic’s Seamless Telegram Login fully functional in your Mini App. 🎉

If you have any questions or need help with the integration, feel free to reach out to us in Slack.

Telegram Authentication Check for Existing Users

This feature avoids accidental duplicate account creation by ensuring that users with existing accounts don’t create unnecessary new ones if their account is not yet linked to Telegram. The isAuthWithTelegram() function verifies whether the user is authenticated through Telegram.

If the user is linked with Telegram, they are automatically logged in. If not, a splash modal prompts the user to confirm if they have an account. Based on the user’s response, they are either are prompted to log in or a new account is automatically created and logged in. This ensures app owners can maintain a single user identity, avoiding duplicate accounts.

Hook is available from SDK version 3.1.3
Full working example in our Telegram Mini App repository here

  1. Import the necessary Telegram authentication functions:

    import { useTelegramLogin } from "@dynamic-labs/sdk-react-core";
    
    const { telegramSignIn, isAuthWithTelegram } = useTelegramLogin();
    
  2. Check if the user is authenticated via Telegram:

    Use isAuthWithTelegram() to determine if the user is linked with Telegram.

    const checkTelegramConnection = async () => {
      const isLinkedWithTelegram = await isAuthWithTelegram();
    
      if (isLinkedWithTelegram) {
        // Auto login if Telegram is connected
        await telegramSignIn();
      } else {
        // Show modal splash page
      }
    };
    
  3. Handle the modal splash response:

    If the user has an account: Prompt developer’s login into the app without creating a new account. If the user doesn’t have an account: Automatically create a new account and log the user in.

    const handleModalResponse = async (hasAccount: boolean) => {
      if (hasAccount) {
        // Prompt developer's login
        console.log("User already has an account on XYZ");
      } else {
        // Call signIn with autoCreate: true
        console.log(
          "User does not have an account on XYZ => Auto Create + Auto Login"
        );
        await telegramSignIn({ forceCreateUser: true });
      }
    };
    

You can clone the provided full working example in our Telegram Mini App repository here

Providing the Telegram auth token to Dynamic

The Telegram Auto-Wallets feature allows you to authenticate your end user with Dynamic using a Telegram authentication token directly. There are currently two ways to provide this token to our SDK.

  1. Pass the auth token as a query parameter when the mini app is launched.

In this approach, your Telegram Bot script generates the Telegram auth token and appends it to your mini app URL. When telegramSignIn is called within your mini app, the token is grabbed from the URL query parameters and used to authenticate the user

  1. Pass the auth token directly into the telegramSignIn hook

In this approach, you directly pass the Telegram auth token into the telegramSignIn hook. This is useful if you are generating the Telegram auth token somewhere outside of Telegram such as your backend.

await telegramSignIn({ forceCreateUser: true, authToken: 'telegram-auth-token-goes-here' });

FAQ

What do I need to do to ensure that Telegram Auto-Wallets is working correctly?

  1. CORS Origin Setup: Ensure that your CORS Origin is correctly configured to include your domain(s). Go to Dashboard > Security > CORS and verify that your domain(s) are listed.

  2. Telegram Social Provider: Verify that the Telegram Social Provider is enabled and configured with the correct Bot details. Navigate to Dashboard > Log In & User Profile > Telegram and confirm that it is turned on, with the BotName and Bot Token entered correctly.

  3. Session keys: Please reach out to us in Slack to request access.

  4. Email Profile Information Requirement: Make sure that the option to require profile information for email login is turned off. Go to Dashboard > Log In & User Profile > Email ⚙️ and confirm that Profile Information required is off.

  5. Bot Code & Telegram Mini Web App: Clone the provided Mini App example and repository as a foundation for your project. Double-check that the Telegram bot code and the Telegram Mini Web App are functioning without any errors. Check the environment variable are loaded correctly LOGIN_URL and TOKEN. Ensure that the logic for seamless login and user verification is working as expected, both server-side and on the front end.

  6. SDK and Package Versions: Verify that the SDK and any packages you’re using are up to date. Hook is available from SDK version 3.1.3

How do I fix MetaMask wallet connection issues?

MetaMask wallet connection does not work on Telegram mobile devices. To resolve this issue, use the following workaround:

Open your app within the mobile version of the MetaMask app. This will allow the wallet connection to function correctly on mobile. If you encounter further issues, ensure that MetaMask is up to date.