Telegram Mini Apps Platform - Telemora/telemora-web GitHub Wiki

Let's start with the very foundation: the Telegram Mini Apps Platform.

What is the Telegram Mini Apps Platform?

Imagine you're building a web application, just like any website you visit daily using HTML, CSS, and JavaScript. Now, imagine that web application running directly inside your Telegram chat window, controlled by a bot. That's the core idea behind Telegram Mini Apps!

Think of your Telegram chat as not just a place for messages, but also a space where you can run small, interactive web applications.

However, it's not just a standard web browser window embedded in the app. The Telegram Mini Apps Platform provides special powers and tools that allow your web app to feel more like a native part of Telegram.

It's like Telegram gives your web app:

  1. A dedicated canvas: A designated area within the chat window where your web app is displayed (this is technically a browser feature called a WebView).
  2. A basic toolbox: Special commands and interface elements that your web app can use to interact with the Telegram app itself.

This platform is the fundamental layer that enables the magic of Mini Apps. It's the stage your web app performs on and the basic set of controls it can use.

Why Use the Platform?

Why would you want your web app running inside Telegram? The main reason is to create a much richer and more user-friendly experience compared to traditional bot interfaces.

Consider a simple task, like ordering a coffee through a bot:

  • Traditional Bot: You might send commands like /order. The bot replies with text options ("Choose size: Small, Medium, Large"). You reply "Medium". The bot asks "Add milk? Yes/No?". You reply "Yes". This is functional, but relies heavily on text commands and predefined replies.
  • Mini App: You tap a button on the bot's message. A Mini App opens displaying a beautiful coffee menu with pictures, sizes, and customization options in a visual interface. You tap buttons, select options using dropdowns or toggles, see the total price update dynamically, and confirm with a single tap on a prominent "Order" button. This is much more intuitive and visually appealing.

The Telegram Mini Apps Platform makes this "Mini App" experience possible by providing the environment and tools for your web app to display this rich interface and communicate back to Telegram.

How It Works (The Very Basics)

At its heart, a Telegram Mini App is a standard web application. You build it using familiar web technologies:

  • HTML: For structuring your content.
  • CSS: For styling how it looks.
  • JavaScript: For making it interactive.

You host this web application on your own server, just like any other website.

When a user interacts with your bot (e.g., clicks a button on a message or types a command), the bot tells the Telegram app to open your Mini App's URL. The Telegram app then launches a special embedded browser window (the WebView) and loads your web app from that URL.

Here's a simplified look at the flow:

sequenceDiagram
    participant User
    participant Telegram App
    participant Bot
    participant Web App

    User->>Bot: Interact (e.g., click button)
    Bot->>Telegram App: Command to open Mini App URL
    Telegram App->>Web App: Open WebView and load URL
    Web App-->>Telegram App: Load complete
    Web App->>Web App: Render UI
    Web App->>Telegram App: Use platform features (e.g., show MainButton)
    Telegram App->>User: Display Mini App interface

For more details on the technical stack and how to set up your first Mini App URL with BotFather, you can refer to the official documentation and guides like About the Platform and Creating New App.

What Tools Does the Platform Provide?

The "basic toolbox" provided by the platform allows your web app to:

  • Control basic Telegram UI: Like showing a large button at the bottom (MainButton) or a "Back" button at the top (BackButton).
  • Get information about the user and chat: Safely retrieve details like the user's ID or the chat type.
  • Request UI feedback: Ask Telegram to show a popup, a confirmation dialog, or trigger haptic feedback (vibration).
  • Communicate back to the bot: Send data from the web app back to the bot associated with it.

These tools are exposed through a special JavaScript object (Telegram.WebApp) that is available in the WebView environment. Your web app code interacts with this object to use the platform's features.

Conclusion

The Telegram Mini Apps Platform is the essential foundation for building rich, interactive experiences within Telegram. It provides the environment (WebView) and a basic set of tools for your web application to interact with the Telegram client itself. While it's just a WebView loading your standard web app files, the platform's unique APIs are what make the experience feel integrated and powerful.