Telegram Mini-Apps: A Guide to 950 Million Users

Telegram Mini-Apps have emerged as a powerful tool 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, offer a seamless and integrated user experience without the need for separate downloads or installations.

The recent milestone of the TON blockchain surpassing 1 billion transactions, with half of this volume recorded in just the last three months, underscores the growing popularity and potential of Telegram Mini-Apps. This rapid growth is driven by innovative applications across various categories, including games, management tools, and utilities.

Key Benefits of Telegram Mini-Apps:

1. Instant access: Users can engage with Mini-Apps directly from a Telegram chat, bypassing traditional app distribution challenges.
2. Seamless integration: The familiar Telegram interface reduces friction and enhances user engagement.
3. Bot interaction: Leverage Telegram Bots for automated experiences and interactive features.
4. Massive user base: Tap into Telegram's existing pool of 950 million monthly active users.
5. Monetization opportunities: Explore various revenue streams through in-app purchases, subscriptions, or advertising on the TON blockchain.

How to build a Telegram mini-app with Openfort

In this tutorial, we'll walk through the process of building a web3 Telegram mini app using Openfort's SDK. The full mini-app repository can be found here.

You can also test it out in your Telegram app by chatting with "@OpenfortMiniAppBot".

By the end of this guide, you will have a fully functioning web3 Telegram mini app that allows users to:

• Authenticate using their Telegram account
• Generate a non-custodial smart wallet
• Mint NFTs directly from Telegram
• View their wallet information

---

Note: There are two methods of authentication with telegram. Telegram auth requires the botUsername as an OAuth2 authentication flow with telegram, similarly to how you login with Google with an access/refresh token returned. This method goes through the screen you have seen with the Continue with Telegram button.

The other method, telegramMiniApp, uses the signed initDataRaw from the telegramSDK available in the mini app as third party authentication. It does not have any kind of refresh token since telegram is in charge of issuing new authentications. This method can be used directly from the mini app without requiring interaction with the user as he is already authenticated with the mini app.

So the telegram method can be used for example in a normal browser like firefox, chrome or unity or another platform. The telegramMiniApp method is specially designed to work in mini apps an it's the one used in this guide.

---

Prerequisites

• Openfort account
• Telegram account
• Node.js and yarn installed
• ngrok or similar tunneling service for local development

Step 1: Create a Telegram Mini App with BotFather

1. Add BotFather to your Telegram
2. Enter the command /newbot (new bot must be created first before creating an app)
3. Choose and enter a name and username for your bot
4. You will be given an access token - go to Openfort authentication providers and add the bot_token in the Telegram Mini-app section.
5. Create a new mini app with the command /newapp
6. Select your bot and follow the prompts for app name, description, and photo
7. When asked for the URL, you'll need your ngrok URL (we'll set this up later)

Step 2: Project Setup

1. Clone the repository:

2. Create environment files:

3. Configure environment variables:

In /next-app/.env:

In /telegram-bot/.env:

Step 3: Set Up Public URL

1. Install ngrok: npm install -g ngrok
2. Start ngrok: ngrok http 3000
3. Copy the HTTPS URL provided by ngrok
4. Update your Mini App URL in BotFather with this URL
5. Add the URL to FRONTEND_APP_ORIGIN in /telegram-bot/.env

Step 4: Configure Openfort

1. Create an account on Openfort Dashboard
2. Create a new application
3. Get your API keys (Standard and Shield)
4. Create a new Asset and Policy
5. Add all IDs and keys to your environment variables

Step 5: Install Dependencies and Run

1. Install dependencies:

2. Start both services:

Step 6: Test the Integration

1. Open your Telegram bot
2. Send the /start command
3. Click the "Launch App" button
4. The mini app should open and:
   • Authenticate you using your Telegram account
   • Generate a non-custodial wallet
   • Allow you to mint an NFT

Key Components

Telegram Bot

The bot is configured in /telegram-bot/src/bot/features/openfort.ts:

API Routes

The Next.js app includes three main API routes:

1. /api/createAuthConfig - Configures Telegram Mini App authentication
2. /api/createEncryptionSession - Creates encryption session for non-custodial wallet
3. /api/mintNft - Handles NFT minting

Main App Page

The main app logic is in /next-app/src/app/login/telegram/page.tsx, handling:

• Telegram authentication
• Wallet configuration
• NFT minting interface

For more detailed information, refer to the repository README.

Conclusion

You now have a working Telegram mini app that:

• Authenticates users via Telegram
• Creates self-custodial smart wallets
• Allows users to mint NFTs
• Handles sponsored transactions securely through Openfort's infrastructure

The mini app provides a seamless web3 experience without requiring users to leave Telegram, making it more accessible to mainstream users.

For more information and advanced features, refer to:

• Openfort Documentation
• Telegram Bot API Documentation
• Telegram Mini Apps Documentation