TryBit

Posted on Aug 31

Telegram Mini Apps Explained: How to Build One and Get Paid Inside Telegram

#telegram #webdev #tutorial

Telegram Mini Apps run inside the messenger, so a customer can open a store, a booking form, or a subscription page without installing anything. This guide explains how to create a Telegram Mini App, from the first BotFather command to a working payment flow.

What a Telegram Mini App Really Is

Developers new to the platform usually start with the same question: what is Telegram Mini App and how does it differ from a regular website? A Telegram Mini App is a web application that is linked to a bot and opened inside the Telegram client. Technically it is a normal web page built with HTML, CSS, and JavaScript, plus a JavaScript bridge that connects the page to the messenger.

Telegram Mini Apps are not installed on the device. The interface opens in a built-in web view, and data about user actions is passed to the bot or to your backend through the Bot API. The bridge gives the page access to the current user, the active color theme, the native main button, haptic feedback, and the closing confirmation dialog. Everything outside that list is still ordinary web development, with the usual rules for hosting, storage, and authorization.

The format suits a wide range of products: online stores, booking and appointment systems, customer dashboards, subscription services, and Telegram Mini Apps games. Because there is no app store review and no installation step, teams also use the format to release an MVP quickly, reach an audience that already lives in the messenger, automate order processing through the bot, and sell digital goods directly in the chat.

What to Prepare Before You Start

Several questions are worth answering before the first line of code:

goal of the application: customer account access, paid subscriptions, appointment scheduling, order payments, donation collection;
main interface elements: catalogs, checkout forms, order status screens, user dashboards;
user accounts and transaction history, if the product involves registration or loyalty programs;
notifications the bot will send: order status changes, reminders, payment confirmations;
hosting and an HTTPS domain, because Telegram refuses to open an application over plain HTTP.

Two practical decisions belong here as well. The first is the development model: small teams usually build the front end themselves, while companies with tight deadlines and a complex catalog either hire Telegram Mini App developers or buy Telegram Mini App development services from an external contractor. The second is a local development setup, since a laptop has no public HTTPS address by default. It also helps to keep the official Telegram Mini Apps docs open in a tab, because the SDK gains new methods regularly and each one is version-gated.

Building a Telegram Mini App Step by Step

Step 1. Create a Bot in BotFather

Every Mini App is attached to a bot, so the bot comes first. Open BotFather, send the /newbot command, then enter a display name and a unique username ending in bot. In response BotFather returns an API token, which is used for Bot API calls and for verifying data on the backend. The same chat is where you add a description, upload an avatar, configure the command list, and later create Telegram Mini App menu buttons.

Treat the token as a production secret. It is enough to control the bot and to forge user data, so it belongs in environment variables, not in the repository.

Step 2. Build the Web App Interface

The implementation depends on the product: a catalog, a checkout form, a dashboard, or a game screen. Many teams build Telegram Mini App front ends with plain HTML, CSS, and JavaScript, and frameworks work as well, since Telegram only needs a URL that returns a page.

The only mandatory addition is the official script. Here is a minimal Telegram Mini App example:

<!DOCTYPE html>
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script src="https://telegram.org/js/telegram-web-app.js"></script>
  </head>
  <body>
    <h1 id="greeting">Loading</h1>
    <div id="catalog"></div>
    <script src="app.js"></script>
  </body>
</html>

The script must be loaded from telegram.org and not bundled with the rest of the assets. A self-hosted copy will not receive updates and may break on newer clients.

Step 3. Initialize the Telegram Web Apps SDK

The bridge becomes available as window.Telegram.WebApp. Calling ready() tells the client that the interface is drawn, and expand() opens the app to full height instead of the default half-screen sheet.

const tg = window.Telegram.WebApp;

tg.ready();
tg.expand();

document.body.style.backgroundColor = tg.themeParams.bg_color || "#ffffff";
document.body.style.color = tg.themeParams.text_color || "#000000";

const user = tg.initDataUnsafe.user;
document.getElementById("greeting").textContent = `Hi, ${user?.first_name ?? "there"}`;

tg.MainButton.setText("Checkout").show();
tg.MainButton.onClick(() => {
  fetch("/api/orders", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ initData: tg.initData, productId: "sub-monthly" }),
  })
    .then((res) => res.json())
    .then(({ paymentUrl }) => tg.openLink(paymentUrl));
});

The naming is a deliberate warning from the platform. The initDataUnsafe object is convenient for rendering a greeting, but it is client-side data and can be modified. The signed string in tg.initData is what the backend should receive, and the Telegram Mini Apps documentation marks every method with the client version that introduced it, so a feature check is safer than an assumption.

Step 4. Validate initData on the Backend

This is the step most tutorials skip, and it is the one that decides whether the product is secure. The initData string is signed with a key derived from the bot token, so the server can confirm that the user identity really came from Telegram.

import crypto from "node:crypto";

export function checkInitData(initData, botToken) {
  const params = new URLSearchParams(initData);
  const hash = params.get("hash");
  params.delete("hash");

  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([key, value]) => `${key}=${value}`)
    .join("\n");

  const secretKey = crypto
    .createHmac("sha256", "WebAppData")
    .update(botToken)
    .digest();

  const signature = crypto
    .createHmac("sha256", secretKey)
    .update(dataCheckString)
    .digest("hex");

  return signature === hash;
}

A valid signature is necessary but not sufficient. The auth_date field should also be checked, because a signed string stays valid forever and can be replayed later. Rejecting anything older than a few hours closes that gap.

Step 5. Host the App Over HTTPS

Telegram requires a valid HTTPS certificate. A static app fits comfortably on cloud hosting or a CDN, while a project with a catalog, orders, and webhooks usually needs a server that also runs the backend and the bot.

During development a tunnel is enough to get a public address:

ngrok http 3000

Two configuration details cause most of the early confusion. The web view is a separate origin from your API, so CORS must allow it. And an aggressive Content-Security-Policy will block the Telegram script unless telegram.org is allowed as a script source.

Step 6. Link the App to the Bot

The bot needs to know which domain belongs to the application. Send /setdomain to BotFather, choose the bot, and enter the application URL.

The launch button is configured in the same place. Open /mybots, select the bot, go to «Bot Settings», then «Menu Button», then «Configure menu button», and enter the URL. After that the application is activated through «Configure Mini App» in the bot settings. Beyond the menu button, an app can also be opened from an inline keyboard button, from a direct link, or from an attachment menu entry, which is useful when different entry points need different screens.

Step 7. Test on Mobile and Desktop

Testing a Mini App means testing several clients at once. The checklist that catches the most defects:

launch from every entry point in use: the menu button, an inline button, a direct link;
rendering in both light and dark themes, with the theme switched while the app is open;
layout on a small screen and in the desktop window, including the safe area at the bottom;
data exchange in both directions: an order reaches the backend, and the bot replies with a confirmation;
behavior when the user closes the app in the middle of a flow;
a full payment cycle in the provider's test mode.

Accepting Payments Inside a Mini App

Payment processing is the feature that turns a Mini App into a sales channel. The flow is consistent across providers: the customer picks a product in the interface, the order is sent to the bot or to the backend, the server creates a payment link or an invoice, the customer pays, and the confirmation returns to the chat.

The important part is where each step happens. Prices, order totals, and payment status belong on the server, because anything computed in the web view can be edited by the client.

app.post("/api/orders", async (req, res) => {
  const { initData, productId } = req.body;

  if (!checkInitData(initData, process.env.BOT_TOKEN)) {
    return res.status(403).json({ error: "Invalid initData" });
  }

  const order = await createOrder(productId); // price comes from the server
  const paymentUrl = await createInvoice(order); // provider or gateway call

  res.json({ paymentUrl });
});

There are four practical ways to collect the money.

Telegram Payments suits physical goods and services. It requires a supported provider such as Stripe, and card data never enters the app.
Telegram Stars are for digital goods and in-app content. Telegram's rules require Stars for digital items, and the balance is withdrawn separately.
An external checkout page works when you already have web billing in place. It opens outside the app, so the return flow needs handling.
A crypto payment gateway fits international and cross-border payments. The asset and network must match on both sides, and settlement rules are set by the provider.

Telegram Stars deserve a separate note, because they are not optional. For digital products sold inside a Mini App, such as subscriptions to in-app content, extra levels, or virtual items, Telegram's platform rules point to Stars rather than to a card provider. Physical goods, services, and payments that happen outside the app are where external providers and crypto gateways apply.

Connecting a Crypto Payment Gateway

Cryptocurrency is a common choice for products with an international audience, mostly because settlement is fast, fees are predictable, and there is no dependence on local card schemes. Trybit can be connected to a Telegram bot either through one of the ready-made integration options for popular bot builders or through the API.

The API route takes six steps:

Create an account using an email address and a Telegram account.
Add a project in the personal account settings.
Download the SDK library from the knowledge base and add it to the project structure.
Insert the API Key and Shop ID into the code, copying both from «Integration and API» in the project settings.
Run a test payment.
Enable payment processing in the web application.

The gateway supports popular cryptocurrencies, checkout customization, automatic conversion of incoming payments, automatic withdrawals, WalletConnect payments, and AML transaction checks, with fees starting from 0.4%. Both checkout integration and plain payment links are available, which matters when the same catalog has to work inside the Mini App and in a regular browser.

Common Mistakes When Building Mini Apps

Most problems in production come from a handful of repeated errors:

Trusting initData without checking the signature. A frequent question is are Telegram Mini Apps safe, and the honest answer is that the platform is, while an application that accepts unverified user data is not. Anyone can open the page outside Telegram and send an arbitrary user ID.
Ignoring themeParams. Hardcoded colors look acceptable in the light theme and turn into unreadable text in the dark one.
Keeping prices on the front end. Order totals sent from the web view can be edited before they reach the server.
Forgetting the /setdomain command. The application opens in a browser but refuses to launch from the bot, which is easy to misdiagnose as a hosting problem.
Testing only in the desktop client. Viewport height, the main button, and the safe area behave differently on iOS and Android.
Leaving the interrupted payment unhandled. A customer who closes the app mid-checkout should still receive the order status from the bot.

Two of these are why a Telegram Mini App development company is often brought in for payment-heavy projects: signature validation and server-side pricing are cheap to implement and expensive to retrofit.

From Bot to Working Mini App

A Mini App is a web application plus two things that are specific to Telegram: a correct link between the bot and the domain, and verified data exchange between the client and the server. Everything else follows familiar web development practice, which is why a working prototype can be assembled in days rather than months.

The payment layer is the part worth choosing deliberately, because it depends on what is being sold and to whom. For businesses serving customers in different countries, Trybit automates cryptocurrency payments with a ready-made checkout, fast integration, and fees starting from 0.4%.

Keep Up With the Crypto Market

Trybit provides businesses with the tools they need to accept cryptocurrency payments on digital platforms. From competitive fees and flexible integrations to ongoing support, the service helps simplify payment processing for companies of different sizes.

DEV Community