Meet us in Devcon Bangkok

Book a coffee!

Telegram Mini-Apps: A Guide to 950 Million Users

5 min read

telegram-mini-apps.svg

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

telegram-screenshot.png


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:

_10
git clone https://github.com/openfort-xyz/sample-telegram-mini-app-embedded-wallet
_10
cd sample-telegram-mini-app-embedded-wallet

  1. Create environment files:

_10
# In /next-app directory
_10
cp .env.example .env
_10
_10
# In /telegram-bot directory
_10
cp .env.example .env

  1. Configure environment variables:

In /next-app/.env:


_11
NEXT_PUBLIC_TELEGRAM_BOT_TOKEN=<your-bot-token>
_11
_11
NEXT_PUBLIC_OPENFORT_PUBLISHABLE_KEY=<from-openfort-dashboard>
_11
NEXT_PUBLIC_OPENFORT_SHIELD_PUBLISHABLE_KEY=<from-openfort-dashboard>
_11
NEXT_PUBLIC_OPENFORT_POLICY_ID=<your-policy-id>
_11
NEXT_PUBLIC_OPENFORT_CHAIN_ID=<your-chain-id>
_11
NEXT_PUBLIC_OPENFORT_CONTRACT_ID=<your-contract-id>
_11
_11
OPENFORT_SECRET_KEY=<from-openfort-dashboard>
_11
OPENFORT_SHIELD_SECRET_KEY=<from-openfort-dashboard>
_11
OPENFORT_SHIELD_ENCRYPTION_SHARE=<from-openfort-dashboard>

In /telegram-bot/.env:


_10
BOT_TOKEN=<your-bot-token>
_10
FRONTEND_APP_ORIGIN=<your-ngrok-url>

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:

_10
# In /next-app directory
_10
cd next-app && yarn install
_10
_10
# In /telegram-bot directory
_10
cd ../telegram-bot && yarn install

  1. Start both services:

_10
# In /next-app directory
_10
yarn dev
_10
_10
# In /telegram-bot directory (new terminal)
_10
yarn dev

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:


_10
feature.command('start', async (ctx) => {
_10
const keyboard = new InlineKeyboard().webApp(
_10
'Launch App',
_10
`${process.env.FRONTEND_APP_ORIGIN}/login/telegram`,
_10
)
_10
return ctx.reply('Click to launch.', { reply_markup: keyboard })
_10
})

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:

Share this article