Set up the Telegram Mini App SDK
Before writing a single line of TON integration code, you must establish the bridge between your web interface and the Telegram client. This process involves two distinct actions: configuring the bot entry point in BotFather and initializing the SDK in your frontend code.
Open the Telegram BotFather and create a new bot. Once created, use the /newapp command to register a Mini App. BotFather will ask for a direct URL to your hosted web application. Ensure this URL is served over HTTPS. After registration, BotFather provides a short link (e.g., t.me/mybot/app) that users will use to launch your app. This link serves as the entry point for the SDK initialization.
Add the official Telegram Web Apps script to your project’s index.html file. This single script tag injects the Telegram.WebApp object into the global scope, allowing your frontend to communicate with the client. Do not rely on third-party wrappers for this initial setup; the official library is lightweight and maintained directly by Telegram.
<script src="https://telegram.org/js/telegram-web-app.js"></script>
In your main JavaScript entry point, immediately initialize the WebApp object. Call Telegram.WebApp.ready() to signal that your UI is loaded, and Telegram.WebApp.expand() to utilize the full vertical height of the available space. This ensures your app looks native from the first millisecond of load.
const tg = window.Telegram.WebApp;
tg.ready();
tg.expand();
With the SDK initialized, your Mini App is now technically connected to the Telegram client. The next step is to prepare your environment for TON blockchain interactions, which requires installing specific wallet libraries.
Integrate TON Connect for Wallets
TON Connect v2 is the standard protocol for linking Telegram Mini Apps to TON wallets. It handles the secure communication layer, allowing your app to request signatures and send transactions without exposing private keys. This integration turns your mini-app into a functional crypto portal.
Add the @tonconnect/ui-react package to your project. This library provides pre-built UI components and the underlying logic to interact with the TON blockchain. It supports React, Vue, and vanilla JavaScript environments.
npm install @tonconnect/ui-react
Create a tonconnect-manifest.json file. This file tells the wallet which app is requesting the connection. Include your app’s name, URL, and icon. Host this file on your server and reference its URL in your initialization code.
{
"url": "https://your-app.com",
"name": "My Mini App",
"iconUrl": "https://your-app.com/icon.png"
}
Wrap your application in the TonConnectUIProvider. Pass your manifest URL as a prop. This initializes the connection bridge between your Mini App and the user’s wallet. The provider manages the session state automatically.
<TonConnectUIProvider manifestUrl="https://your-app.com/tonconnect-manifest.json">
<App />
</TonConnectUIProvider>
Use the useTonConnectUI hook to trigger the wallet connection. This opens a QR code or deep link in Telegram, allowing the user to approve the connection in their wallet. Once approved, you gain access to the user’s public address.
const [tonConnectUI] = useTonConnectUI();
const connectWallet = () => {
tonConnectUI.openModal();
};
Design the In-Game Economy
You need to decide how value moves through your Telegram Mini App before writing the first line of smart contract code. The TON blockchain offers two primary paths for in-game currency: native TON transfers and Jetton tokens. Choosing the right structure affects your development complexity, transaction costs, and how users perceive the value of your assets.
Compare Native TON vs. Jetton Tokens
Native TON is the base currency of the network. It is simple to implement but lacks the flexibility of a dedicated in-game economy. Jetton tokens are fungible assets deployed on TON that allow you to create custom currencies with specific rules, such as inflation control or transfer restrictions.
| Feature | Native TON | Jetton Token |
|---|---|---|
| Setup Complexity | Low | Medium |
| Transaction Fees | Standard TON gas | Standard TON gas + Jetton logic |
| Custom Logic | None | Yes (mint, burn, limits) |
| User Recognition | Universal | Requires Wallet Support |
Issue Assets on TON
If you choose Jettons, you will deploy a Jetton Master contract. This contract acts as the source of truth for your token’s supply and metadata. You can then mint Jetton Wallets for users when they interact with your Mini App. This process is handled via smart contract calls, which the Telegram frontend triggers through the TON Connect SDK.
Process Payments Securely
Payments in Telegram Mini Apps are initiated by the user clicking a payment button in your UI. The frontend constructs a transaction payload containing the amount and the destination Jetton Wallet address. The user approves this transaction in their wallet (e.g., Tonkeeper or Telegram Wallet). Once the blockchain confirms the transaction, your backend verifies the event and updates the user’s balance in your game state.
Always verify transactions on-chain. Do not trust the frontend’s success callback alone. Use a lightweight indexer or TON API to confirm that the Jetton transfer was actually processed before granting in-game rewards.
Test and Deploy the Mini App
Before exposing your Telegram Mini App to users, you must verify its behavior in a controlled environment. Telegram provides a debug mode that allows you to run the app locally while connecting to the Telegram WebApp API. This setup mirrors the production environment, catching integration errors before they reach the public.
1. Enable Debug Mode
Debug mode bypasses the standard launch restrictions, allowing you to test the Mini App directly from your local development server. You do not need to publish the bot or create a permanent link to test functionality. Instead, use the Telegram.WebApp object within your local browser context to simulate user interactions, such as opening the app from a keyboard button or inline menu.
2. Run the Local Server
Start your local development server (e.g., using Vite, Webpack, or Next.js). Ensure the server is accessible via localhost or 127.0.0.1. Telegram’s debug mode requires the app to be served over HTTPS in production, but for local testing, HTTP is sufficient. Verify that your bot’s WebApp configuration points to the correct local URL or that you are using the debug launcher provided by Telegram’s developer tools.
3. Validate API Integration
Use the Telegram.WebApp API to test key features: user data retrieval, theme parameters, and expansion behavior. Check that the app correctly handles the ready event and expands to full height when necessary. If your app relies on TON Connect or other blockchain interactions, ensure the wallet integration initializes correctly in this simulated environment.
4. Deploy to a Static Host
Once testing is complete, deploy the Mini App to a static hosting provider that supports HTTPS. Platforms like Vercel, Netlify, or GitHub Pages are standard choices. The deployment URL must be valid and accessible to Telegram’s servers. Update your bot’s WebApp configuration to point to this new production URL.
5. Verify Production Launch
Test the Mini App in a live Telegram session. Open your bot and launch the Mini App to ensure it loads correctly. Check that user data, themes, and any external API calls function as expected in the production environment. If issues arise, review the browser console for errors and ensure your server’s CORS policies allow requests from t.me.
Use Telegram’s debug launcher to run your app locally. This bypasses standard launch restrictions, allowing you to test the WebApp API without publishing your bot. Verify that the Telegram.WebApp object is accessible in your local browser context.
Start your local development server. Ensure it is accessible via localhost. No HTTPS is required for local testing, but the server must be running and reachable by the debug launcher. Configure your bot’s WebApp URL to point to this local endpoint if needed.
Test key features using the Telegram.WebApp API. Check user data retrieval, theme parameters, and expansion behavior. Ensure the app handles the ready event correctly. If using TON Connect, verify that the wallet integration initializes without errors in this simulated environment.
Deploy the Mini App to a static hosting provider that supports HTTPS, such as Vercel, Netlify, or GitHub Pages. Update your bot’s WebApp configuration to point to the new production URL. Ensure the deployment is live and accessible to Telegram’s servers.
Test the Mini App in a live Telegram session. Open your bot and launch the app to confirm it loads correctly. Check that user data, themes, and external API calls function as expected. Review the browser console for any production-specific errors.
Common Mistakes in TON Mini Apps
Even with a working TON wallet connection, your Mini App can fail if it ignores Telegram’s specific rendering constraints or underestimates blockchain latency. These pitfalls are not just cosmetic; they break trust and transaction integrity.
Ignoring Telegram’s UI Guidelines
Telegram enforces strict design standards to ensure Mini Apps feel native. If your app uses standard web buttons or ignores the Telegram WebApp SDK for viewport resizing, users will experience jarring layout shifts. Always use Telegram.WebApp.expand() and adhere to the official color schemes.
Failing to Handle Network Latency
TON transactions are not instantaneous. A common error is assuming a signed transaction is confirmed immediately. You must implement loading states and polling for transaction status via TON Connect or direct RPC calls. Without this, users may double-click buttons, causing duplicate transactions or failed states.
Overlooking Mobile Viewport Issues
Many developers test only on desktop browsers. Telegram Mini Apps run in a constrained mobile WebView. Ensure your touch targets are at least 44x44 pixels and that horizontal scrolling is avoided. Test on actual iOS and Android devices to catch rendering bugs that desktop emulators miss.
No comments yet. Be the first to share your thoughts!