Choose your app launch method

Before writing code, decide how users will enter your Mini App. Telegram supports seven distinct entry points, but three are the most common for new developers. Your choice dictates the user experience and the technical setup required.

Profile button

The profile button appears directly on your bot’s profile. It is the most visible entry point because it is always present in the chat header. Users launch the app by tapping the button before or during a conversation. This method is ideal for standalone tools or services that do not require context from a specific message.

Keyboard button

A keyboard button sits inside the chat interface, replacing or supplementing the standard text input area. This method is best for conversational flows where the app is a direct response to a user’s input. For example, a payment bot might show a "Pay Now" button only after the user requests a quote. The button appears in the custom keyboard, making the action feel native to the chat.

Inline button

Inline buttons are attached to specific messages sent by your bot. They appear below the message text and are context-dependent. This method is perfect for actions tied to a single piece of content, such as a poll result, a product listing, or a game level. Users launch the app by clicking the button associated with that exact message.

Telegram mini-apps

Comparison of launch methods

Use this table to compare the technical complexity and user intent for each method.

MethodVisibilityUser IntentSetup Complexity
Profile ButtonAlways visible in chat headerStandalone tool accessLow
Keyboard ButtonAppears in custom keyboardContextual action within chatMedium
Inline ButtonAttached to specific messagesAction tied to message contentMedium

Set up the development environment

Before writing code, you need a working Telegram bot and a web server to host your Mini App. Telegram Mini Apps are essentially web applications launched inside Telegram, so they require a valid HTTPS endpoint to function securely.

Create the bot via BotFather

Start by opening Telegram and searching for BotFather. Send the /newbot command and follow the prompts to name your bot and generate a unique username. BotFather will provide you with an API token, which you will need later to authenticate requests to the Telegram Bot API.

Telegram mini-apps
1
Create the bot

Open BotFather in Telegram, run /newbot, name your bot, and copy the generated API token. This token is your primary credential for interacting with the Telegram API.

Telegram mini-apps
2
Set the menu button

In BotFather, run /newapp and select your newly created bot. You will be prompted to set a menu button URL. This is the direct link to your Mini App’s web interface, which Telegram will use to launch the app when users tap the menu button.

The Telegram Mini-App Boom
3
Verify the HTTPS endpoint

Ensure your web app URL is served over HTTPS. Telegram requires secure connections for Mini Apps. If you are testing locally, use a tunneling service like ngrok to expose your local development server to the internet with a valid SSL certificate.

With the bot created and the menu button pointing to your hosted web app, your development environment is ready. You can now proceed to build the actual Mini App interface.

Integrate TON blockchain features

Connecting your mini-app to the TON blockchain unlocks native wallet functionality and on-chain transactions. This integration allows users to interact with decentralized applications (dApps) directly within Telegram, enabling crypto gaming, token transfers, and NFT management without leaving the chat interface.

1
Install the TON Connect SDK

Begin by adding the @tonconnect/ui or @tonconnect/sdk package to your project. This library provides the pre-built UI components and core logic required to communicate with TON wallets. It handles the complex protocol details, allowing you to focus on your app’s specific logic.

Shell
Shell
npm install @tonconnect/ui-react

For React-based mini-apps, wrap your application in the TonConnectUIProvider component, passing your app’s manifest URL. This manifest tells the wallet which app is requesting the connection and what permissions are required.

2
Implement Wallet Connection

Use the SDK’s connect() method to trigger the wallet selection modal. When a user clicks a "Connect Wallet" button, the SDK opens a list of compatible TON wallets (such as Tonkeeper, MyTonWallet, or Telegram’s built-in wallet).

Once the user selects a wallet and approves the connection, the SDK returns the wallet’s public address. Store this address securely in your app’s state to identify the user for subsequent transactions or on-chain interactions.

3
Execute On-Chain Transactions

To send TON coins or tokens, construct a transaction object using the SDK. Define the destination address, the amount in nanotons (1 TON = 1,000,000,000 nanotons), and any optional payload data. Call the sendTransaction() method, which prompts the user’s wallet to review and sign the transaction.

For crypto games, this step is critical for minting NFTs, transferring in-game assets, or paying for premium features. Ensure your transaction handling includes error management for cases like insufficient funds or user rejection.

4
Verify Transaction Status

After sending a transaction, monitor its status using the TON blockchain explorer or the SDK’s event listeners. The SDK provides callbacks for transactionSent and transactionConfirmed events. This feedback loop is essential for user experience, confirming that assets have been successfully transferred or minted.

Implement a loading state while waiting for confirmation, and display a success or error message based on the final transaction status. This transparency builds trust and ensures users understand the outcome of their actions.

By following these steps, you create a seamless bridge between your mini-app and the TON ecosystem. This integration not only enhances user engagement through native crypto features but also opens new monetization avenues for your application.

Design for mobile-first performance

Telegram Mini Apps run inside a WebView, meaning they share the same rendering engine as the browser your user is already using. If your app feels sluggish, users won't wait for a reload; they'll simply swipe away. Optimizing for mobile-first performance is the difference between a retained user and a bounced one.

Start by minimizing the initial payload. Telegram users expect instant interaction. Keep your JavaScript bundle under 150KB and defer non-critical scripts. Use lazy loading for images and avoid heavy frameworks like React if a simpler library suffices. The goal is to get the first paint visible within 1 second.

Touch interactions must be precise. Mobile screens vary in size and density. Ensure all interactive elements have a minimum touch target of 44x44 pixels. Avoid hover states entirely, as they don't exist on touch devices. Use touch-action: manipulation in your CSS to prevent double-tap zoom delays, which feel jarring in a native-like environment.

Optimize for variable network conditions. Many users access Mini Apps on cellular data with fluctuating signal strength. Implement optimistic UI updates so the interface feels responsive even before the server confirms the action. Show skeleton loaders instead of spinners to maintain context.

The Telegram Mini-App Boom

Test your app on low-end Android devices, which represent a significant portion of Telegram's global user base. High-end iPhones may render your app smoothly, but lag on older hardware will drive away a large segment of your audience. Use Chrome DevTools' "Network Throttling" to simulate 3G speeds and identify bottlenecks.

Callout: Performance is not just about speed; it's about perceived reliability. A fast app that crashes under load is worse than a slightly slower, stable one.

Test and deploy to production

Before making your Telegram Mini App public, you need to validate functionality across different environments. Testing ensures that the Web App behaves correctly when launched from various entry points, such as profile buttons or inline keyboard buttons, as outlined in Telegram’s official documentation.

Telegram mini-apps
1
Test on multiple devices

Verify your Mini App renders correctly on both iOS and Android devices. Check for layout shifts, touch responsiveness, and proper handling of the Telegram Web App SDK. Ensure the app adapts to different screen sizes and dark/light modes.

Telegram mini-apps
2
Validate production environment

Deploy your frontend to a secure HTTPS server. Configure your bot’s menu button or inline buttons to point to the production URL. Test the full user journey from bot interaction to app launch and back.

3
Check TON wallet connectivity

If your app uses TON Connect, test wallet linking and transaction signing in a production-like environment. Ensure that user data is handled securely and that error states are managed gracefully.

Checklist

  • HTTPS is enforced on the production domain
  • TON wallet integration is tested end-to-end
  • Mobile responsiveness is verified on iOS and Android
  • Bot menu button points to the live URL
  • Error handling is implemented for network failures

Frequently asked questions about building Telegram Mini-Apps

Developers and founders often ask how Telegram Mini-Apps compare to traditional web or mobile development, especially when planning for 2026. Below are the most common technical and strategic questions we receive.