How to Build Telegram Mini-Apps with React

Telegram Mini-Apps allow developers to reach over 950 million active users within a single messenger. Built with standard web technologies like React, these lightweight apps bypass the friction of separate downloads.

What is a Telegram Mini-App?

A Telegram Mini-App is a web application that runs directly inside the Telegram interface. It uses the Telegram Web Apps SDK to interact with the bot API, allowing for a seamless experience that feels native to the messenger. By integrating Openfort, developers can add on-chain features like non-custodial wallets and NFT minting, making it easy for players to earn and trade digital assets without leaving their chat.

In this guide, you’ll learn how to build a React-based Mini-App with Openfort to handle on-chain interactions.

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 on-chain 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 on-chain interactions, such as NFT minting.

For further details, check:

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

Related reading

• How to build a Telegram Mini-App with Unity WebGL -- if you are building a game-based Mini-App, this guide covers Unity WebGL integration with Openfort
• Embedded wallets explained -- understand how the non-custodial wallets created in this tutorial work under the hood
• Cross-app wallets explained -- learn how wallets can follow users across multiple apps in an ecosystem
• Onboard users instantly with guest accounts -- reduce onboarding friction even further by letting users start without authentication
• Introducing global wallets with the Ecosystem SDK -- see how ecosystem wallets unify the player experience across games and apps