What Telegram Mini Apps are, and when you need one

What a Mini App is

A normal bot talks in messages. It sends text, photos and rows of buttons, and the user replies. A Mini App is different: it's a web page built with HTML and JavaScript, the same tools used to build websites, that Telegram opens in a panel inside the app. To the user, it feels like part of Telegram rather than a separate site.

Every Mini App belongs to a bot. The bot is the account people find, open and chat with. The Mini App is an extra screen the bot can open when a chat isn't the best way to do something.

Because Telegram opens the app itself, it can pass the app basic details about the user, such as their name and language. That means the user doesn't need to create an account or log in, which removes one of the biggest reasons people give up on a new website.

Mini Apps are widely used. Telegram says more than 500 million of its 950 million users interact with Mini Apps every month. That figure covers all Mini Apps, including large games and services. It doesn't mean your bot needs one.

Ways to open a Mini App

There are several entry points, and a bot can use more than one:

• The menu button. The button next to the message field in a bot's chat normally shows the bot's commands. It can instead open a Mini App, so the app is always one tap away. You lose the command list in that spot, so plan your commands with that in mind.
• The bot's main Mini App. A bot can have one main Mini App that people can launch straight from the bot itself.
• A button in a message. The bot sends a message with a button, and tapping it opens the app. This is the most common way to open an app for one specific task.
• Inline mode. A Mini App can be opened from the bot's inline mode, the feature that lets people use a bot from any chat by typing its username.
• Links. A t.me link can open a Mini App directly, so you can share the app anywhere you'd share a link.
• The attachment menu. Some apps appear in the menu people use to attach files. This is only available to bots Telegram has approved.

What Mini Apps are good for

A Mini App earns its place when a task needs a real screen. Good examples:

• Browsing many items. A catalog with photos, filters and a cart is much easier to scan as a grid than as a stream of messages.
• Long forms. A booking with a date picker, a time slot and a few fields is one screen in an app, but ten back-and-forth messages in a chat.
• Visual and live things. Maps, charts, a spinning wheel for a draw, or a game with animation.
• Dashboards. Settings and statistics that are easier to read on one page than in several messages.

Payments work too. Bots and Mini Apps must use Telegram Stars to sell digital goods and services inside Telegram, so a Mini App that sells a digital product follows the same rules as a bot. See Telegram Stars explained.

Mini App or a normal chat bot?

Chat bots are underrated. Messages arrive as notifications, stay in the chat history, work on slow connections and need no design work. For a support inbox, a file converter or a menu of answers, a chat bot is simply better. Mini Apps win when the job is really a small website.

The honest downsides

Mini Apps are often presented as the future of Telegram bots. They're powerful, but they come with real costs:

• You need web development. A Mini App is a website. Someone has to design and build it in HTML and JavaScript, make it work on small phones and large desktops, and handle Telegram's light and dark themes so it doesn't look out of place.
• You need hosting. The app has to live on a web server with a secure HTTPS address, on top of whatever runs the bot. That's one more thing to pay for, update and keep online.
• Two things to maintain. The bot and the web app have to stay in sync. A change to one often means a change to the other.
• More to test. Telegram runs on phones, tablets, desktop apps and the web. A Mini App has to work in all of them, and bugs are harder to spot than in plain messages.
• It can be slower. A chat reply is instant. An app has to load first, and on a weak connection that wait is noticeable.
• It can be overkill. If your bot asks three questions and sends a result, a Mini App adds work without making anything better for the user.

A sensible approach is to start with a chat bot, see which tasks feel clumsy in messages, and build a Mini App only for those.

Getting a Mini App without building one

If you're a developer, you build the web app, host it, and connect it to your bot through the Bot API and your bot's settings in @BotFather.

If you're not, some templates already include the web part. In Echo Maker, two templates use a Mini App next to their normal chat buttons:

• Contests: people join a giveaway through a web app opened from the Join now button.
• Roulette: the start screen has a Mini App button, alongside the regular options to create a draw room.

The web part of these templates is already built and hosted, so you don't write any code. The Button Bot template also lets you put a web app link behind a button, so you can open a page you already have.

For the full picture of how a bot comes together, see how to create a Telegram bot. For what a bot can do without any web app, start with what a Telegram bot is.