How to create Telegram mini-app with React

Telegram Mini-Apps are powerful tools for developers to reach over 950 million monthly active users directly within the Telegram messenger. These lightweight applications, built using web technologies like HTML, CSS, and JavaScript, provide a seamless, integrated experience without requiring separate downloads or installations.

In this guide, you'll learn how to create a Telegram Mini-App integrated with Openfort's SDK to enable Web3 features like non-custodial wallets and NFT minting. This article is optimized for technical readers looking for a practical starting point, and you'll find a fully functional sample repository linked below.

The repository for this tutorial can be found here.

Test it live via Telegram by chatting with @OpenfortMiniAppBot.

Step 0: Overview and Architecture

Before diving into the implementation, it’s important to understand the high-level structure and flow of the Telegram Mini-App you’ll build.

Key Components

1. Frontend (Client-Side):

   • Built with React using the Telegram Web Apps SDK.
   • Handles the user interface and state management.
   • Processes initData received from Telegram for authentication.
   • Provides interactions for minting NFTs and viewing wallet information.

2. Backend (Server-Side):

   • Built with Node.js and Express.
   • Validates initData for security and ensures the user is authenticated.
   • Integrates with Openfort’s SDK to manage smart wallets and sponsored transactions.
   • Exposes API endpoints for NFT minting and wallet generation.

Telegram Authentication Flows

Telegram provides two distinct methods for authentication within Mini-Apps:

1. initData Flow:

   • Used within the Mini-App environment.
   • Relies on Telegram to authenticate the user via the initData object.
   • No refresh token is involved, as Telegram handles re-authentication for subsequent sessions.

2. OAuth Flow:

   • More versatile and works in browsers or platforms outside the Mini-App context.
   • Returns an access token/refresh token pair, similar to logging in with Google.
   • Suitable for broader integrations where the user isn't already within the Telegram app.

This guide focuses on the initData flow, which is specially designed for seamless use in Telegram Mini-Apps.

High-Level Flow

Here’s how the application will work end-to-end:

1. The user opens the Telegram Mini-App from a bot.
2. Telegram sends initData to the Mini-App containing signed user information.
3. The frontend sends this initData to the backend for validation.
4. The backend:
   • Validates initData using Telegram-provided cryptographic methods.
   • Creates a self-custodial wallet using Openfort.
   • Returns relevant user data and wallet information to the frontend.
5. The user interacts with the Mini-App:
   • Minting NFTs.
   • Viewing wallet details.
   • Executing blockchain transactions.

Objectives

By the end of this tutorial, you will have:

1. Set up a Telegram Mini-App using React.
2. Integrated Openfort’s SDK for embedded wallet creation.
3. Built backend routes to handle Telegram authentication and Web3 interactions.

Step 1: Set Up the Telegram Mini-App

1.1 Create a Bot and Mini-App with BotFather

1. Add BotFather to your Telegram and run /newbot.
2. Follow the prompts to name your bot and get its access token.
3. Add this token to the Openfort authentication provider settings.
4. Run /newapp to create a Mini-App linked to your bot. Use your ngrok URL as the app’s URL (we’ll set this up next).

Step 2: Clone and Configure the Project

2.1 Clone the Repository

2.2 Set Up Environment Variables

In the /frontend and /backend directories, copy and configure .env.example files:

• Frontend .env:

  
  

  _10

  NEXT_PUBLIC_TELEGRAM_BOT_TOKEN=<your-bot-token>

  _10

  NEXT_PUBLIC_OPENFORT_PUBLISHABLE_KEY=<your-publishable-key>

  _10

  NEXT_PUBLIC_OPENFORT_POLICY_ID=<your-policy-id>

  _10

  NEXT_PUBLIC_OPENFORT_CHAIN_ID=<your-chain-id>

  
  

• Backend .env:

  
  

  _10

  BOT_TOKEN=<your-bot-token>

  _10

  FRONTEND_APP_ORIGIN=<your-ngrok-url>

  
  

Step 3: Run the Application

3.1 Install Dependencies

3.2 Start Services

Use ngrok to expose your local server:

Update the Mini-App URL in BotFather with your ngrok HTTPS link.

Step 4: Key Integration Features

Telegram Authentication

The app uses initDataRaw from the Telegram Web Apps SDK for third-party authentication. No additional refresh tokens are needed.

Embedded Wallet

With Openfort’s SDK, users can:

1. Create a non-custodial wallet.
2. Mint NFTs using predefined policies.

API Routes

The backend provides endpoints for:

1. /api/createAuthConfig: Configures authentication.
2. /api/createEncryptionSession: Sets up a session for wallet creation.
3. /api/mintNft: Facilitates NFT minting.

Example Code Snippets

Telegram Bot Integration

In /backend/src/bot/features/openfort.ts:

Wallet Initialization

In /frontend/src/app/login/telegram/page.tsx:

Conclusion

You’ve built a Telegram Mini-App with React that:

• Authenticates users via the Telegram SDK.
• Generates EVM-compatible non-custodial wallets.
• Facilitates Web3 interactions, such as NFT minting.

For further details, check:

• Openfort Documentation
• Telegram Web Apps SDK Docs
• Repository README