Set up the Telegram Bot API
To host a Telegram Mini App with TON integration, you first need a bot to serve as the entry point. Telegram Mini Apps are essentially web interfaces that run inside the Telegram client, but they require a bot to launch them and handle user interactions. This bot acts as the bridge between the user’s Telegram account and your TON blockchain logic.
Start by opening Telegram and searching for @BotFather. This is Telegram’s official bot management tool. Send the /newbot command to begin the creation process. You will be prompted to enter a display name for your bot, which is what users see in chats. After that, you must choose a unique username. This username must end with the word bot (e.g., MyTonApp_bot) and cannot be used by any other account.
Once BotFather confirms the creation, it will provide you with an API Token. This string of characters is the key to controlling your bot. Store this token securely in your environment variables or secret manager. Never commit it to public code repositories. With this token, you can now use the Bot API to configure the bot’s behavior, such as setting up commands that will launch your Mini App.
Initialize the Web App SDK
To bridge your frontend JavaScript environment with Telegram's native features, you must initialize the Web App SDK. This package provides the necessary objects to access the user's profile, handle theme changes, and interact with the platform's UI components.
Install the official package
Start by installing the @twa-dev/sdk package in your project directory. This is the recommended wrapper for modern React and Vue environments, ensuring type safety and easier integration.
npm install @twa-dev/sdk
Import and initialize
Once installed, import the init function from the SDK in your main entry file (e.g., App.tsx or main.js). Call init() immediately during the application's startup phase. This establishes the connection between your web view and the Telegram client.
import { init } from '@twa-dev/sdk';
// Initialize the SDK
init();
Verify the connection
After initialization, verify that the SDK has successfully connected by checking the Telegram.WebApp object. You can log the user's data or expand the app to full screen to confirm that native features are active.
import { expand } from '@twa-dev/sdk';
// Expand to full height
expand();
// Log user data for debugging
console.log('User:', Telegram.WebApp.initDataUnsafe.user);
Integrate TON Connect for Wallets
To enable transactions and asset management, you must connect your mini app to the user's TON wallet. TON Connect serves as the standardized protocol for this handshake, allowing your JavaScript interface to request signatures and send transactions securely without exposing private keys.
Import the @tonconnect/ui package into your project. This library provides the pre-built UI components and logic needed to manage the connection state. For React applications, you can wrap your app in a TonConnectUIProvider to make wallet data available throughout your component tree.
Create a TonConnect instance in your main entry point. You must provide a manifestUrl that points to a JSON file hosted on your server. This manifest contains your app's name, logo, and website URL, which the wallet displays to the user during the connection request to prevent phishing.
Listen for connection status changes using the connectionRestored$ and statusChange$ observables. When a user connects, the wallet returns their public address. Store this address in your app's state to enable personalized features, such as displaying the user's TON balance or recent transaction history.
Use the sendTransaction method to initiate on-chain actions. Define the transaction details, including the destination address, value in nanotons, and payload data. The TON Connect SDK handles the serialization and sends the request to the user's wallet app, which prompts them to review and approve the action.
After the user approves the transaction, monitor the status to confirm it has been processed on the TON blockchain. You can use the lastTransaction property returned by the SDK or query a TON blockchain explorer API using the transaction hash to ensure the state change is final before updating your UI.
Handle Payments and Transactions
Build a Telegram Mini App With TON Integration works best as a sequence, not a scramble through settings. Do the minimum first: confirm compatibility, connect the core hardware, update only when needed, and test the result before adding optional features. That order keeps the task understandable and makes failures easier to isolate. After each step, pause long enough for the interface to finish syncing. Many setup problems are timing problems disguised as configuration problems. If the same step fails twice, record the exact error, restart the smallest affected piece, and retry before moving deeper.
Test the App in Development Mode
Before launching your Telegram Mini App with TON integration, verify that the interface, wallet connection, and payment flows work correctly. Use Telegram’s built-in testing tools to catch issues early.
Open Telegram settings, navigate to Advanced, and toggle on Developer Mode. This unlocks the ability to preview Mini Apps directly from your development server without publishing them to the App Directory.
Use a TON testnet wallet (like Tonkeeper Testnet) to simulate transactions. Verify that the app correctly initializes the TON Connect SDK and handles connection events without errors.
Test both successful and failed transaction scenarios. Ensure the app displays appropriate feedback for each outcome and that the UI remains responsive during network delays.
Test the Mini App on different screen sizes and orientations. Verify that all elements scale correctly and that no content is clipped or overlapping.
Review the permissions requested by your app. Ensure it only asks for necessary data access and that sensitive operations are protected against unauthorized access.
No comments yet. Be the first to share your thoughts!