From b7a4ccbf34fe4e66b9f7a1418505dd272f110278 Mon Sep 17 00:00:00 2001
From: Coalus <im-coalus@proton.me>
Date: Thu, 19 Mar 2026 10:30:53 +0300
Subject: [PATCH 1/4] feat(tma): enhance tma overview page, add page describing
 apps communication

---
 docs.json                            |   1 +
 ecosystem/tma/apps-communication.mdx | 116 +++++++++++++++++++++++++++
 ecosystem/tma/overview.mdx           |  43 ++++++++--
 resources/dictionaries/custom.txt    |   2 +
 4 files changed, 156 insertions(+), 6 deletions(-)
 create mode 100644 ecosystem/tma/apps-communication.mdx

diff --git a/docs.json b/docs.json
index 96339f2c9..91741a2b5 100644
--- a/docs.json
+++ b/docs.json
@@ -226,6 +226,7 @@
             "group": "TMA: Telegram Mini Apps",
             "pages": [
               "ecosystem/tma/overview",
+              "ecosystem/tma/apps-communication",
               "ecosystem/tma/create-mini-app",
               {
                 "group": "Telegram UI",
diff --git a/ecosystem/tma/apps-communication.mdx b/ecosystem/tma/apps-communication.mdx
new file mode 100644
index 000000000..c5fc2a603
--- /dev/null
+++ b/ecosystem/tma/apps-communication.mdx
@@ -0,0 +1,116 @@
+---
+title: "Apps communication"
+---
+
+The Telegram client and a Mini App communicate through a message-passing interface. The exact transport depends on the platform, but the protocol is the same: the Mini App sends **methods** to the Telegram client, and the Telegram client sends **events** back to the Mini App.
+
+## Methods and events
+
+Two terms describe the communication directions:
+
+- **Methods** — calls sent from the Mini App to the Telegram client. A method triggers an action in the native app (for example, showing a popup or expanding the viewport).
+- **Events** — signals sent from the Telegram client to the Mini App. An event notifies the Mini App that something happened (for example, the viewport changed or a button was pressed).
+
+Internally both are messages, but "methods" and "events" distinguish the direction throughout the Mini Apps platform.
+
+## Transport by platform
+
+The transport mechanism varies by Telegram client:
+
+| Platform | Transport | Details |
+|----------|-----------|---------|
+| Web (Telegram Web A, Web K) | `window.parent.postMessage` | The Mini App runs in an `<iframe>`. Messages are JSON strings passed between frames. |
+| Desktop and mobile (Android, iOS, macOS, tdesktop) | `window.TelegramWebviewProxy.postEvent` | Telegram injects a global function into the WebView. |
+| Windows Phone | `window.external.notify` | Same JSON format as the web version. |
+
+## Calling methods
+
+### Web
+
+The web version displays the Mini App in an `<iframe>`. Communication uses `window.parent.postMessage` with a JSON string:
+
+```typescript
+const data = JSON.stringify({
+  eventType: 'web_app_setup_back_button',
+  eventData: { is_visible: true },
+});
+
+window.parent.postMessage(data, 'https://web.telegram.org');
+```
+
+Pass a [target origin](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#targetorigin) to restrict which parent frame can receive the message. Use `https://web.telegram.org` as the default.
+
+### Desktop and mobile
+
+Desktop and mobile clients inject `window.TelegramWebviewProxy.postEvent` into the WebView:
+
+```typescript
+window.TelegramWebviewProxy.postEvent(
+  'web_app_setup_back_button',
+  JSON.stringify({ is_visible: true })
+);
+```
+
+### Windows Phone
+
+The Windows Phone client provides `window.external.notify` with the same JSON format as the web version:
+
+```typescript
+window.external.notify(JSON.stringify({
+  eventType: 'web_app_setup_back_button',
+  eventData: { is_visible: true },
+}));
+```
+
+## Listening to events
+
+### Web
+
+The parent iframe sends events via `window.postMessage`. Add a `message` listener:
+
+```typescript
+window.addEventListener('message', ({ data }) => {
+  const { eventType, eventData } = JSON.parse(data);
+  console.log(eventType, eventData);
+});
+```
+
+<Aside type="caution">
+In production, validate that the `message` event originates from the Telegram application and that `data` is a string before parsing.
+</Aside>
+
+### Desktop, mobile, and Windows Phone
+
+These platforms deliver events by calling a globally defined function:
+
+| Platform | Function path |
+|----------|--------------|
+| Telegram Desktop | `window.TelegramGameProxy.receiveEvent` |
+| Telegram for iOS and Android | `window.Telegram.WebView.receiveEvent` |
+| Windows Phone | `window.TelegramGameProxy_receiveEvent` |
+
+All functions share the same signature:
+
+```typescript
+type ReceiveEvent = (eventType: string, eventData: unknown) => void;
+```
+
+To handle events on all platforms, assign a handler function to all three paths.
+
+## Using the SDK
+
+The [@tma.js/sdk](https://www.npmjs.com/package/@tma.js/sdk) package abstracts away platform differences and provides a unified API for calling methods and listening to events:
+
+```typescript
+import { postEvent, on } from '@tma.js/sdk';
+
+// Call a method
+postEvent('web_app_set_header_color', { color_key: 'bg_color' });
+
+// Listen to an event
+const removeListener = on('viewport_changed', payload => {
+  console.log('Viewport changed:', payload);
+});
+```
+
+For the full list of available methods and events, see the [@tma.js/sdk documentation](https://docs.telegram-mini-apps.com/packages/tma-js-sdk).
diff --git a/ecosystem/tma/overview.mdx b/ecosystem/tma/overview.mdx
index 4906c03c0..abb815945 100644
--- a/ecosystem/tma/overview.mdx
+++ b/ecosystem/tma/overview.mdx
@@ -1,9 +1,9 @@
 ---
-title: "TMA: Telegram Mini Apps overview"
+title: "Telegram Mini Apps overview"
 sidebarTitle: "Overview"
 ---
 
-Telegram Mini Apps (TMAs) are web applications that run within the Telegram messenger. They are built using web technologies — HTML, CSS, and JavaScript.
+Telegram Mini Apps (TMAs) are web applications that run inside the Telegram messenger. Built with standard web technologies — HTML, CSS, and JavaScript — they display in a WebView provided by the Telegram client.
 
 <video
   autoPlay
@@ -15,10 +15,41 @@ Telegram Mini Apps (TMAs) are web applications that run within the Telegram mess
   Your browser does not support the \<video> tag.
 </video>
 
-Mini Apps run within Telegram and are instantly accessible — without the need for installation or redirects.
+Mini Apps are an extension of [Telegram Bots](https://core.telegram.org/bots). Every Mini App is associated with a bot, which serves as the entry point. The bot provides the application URL, and Telegram loads it in a WebView.
+
+## Why use Mini Apps
+
+Telegram Bots communicate through a text-based, console-like interface. This works well for simple commands but limits the user experience for complex workflows. Mini Apps solve this by providing a full graphical interface while keeping the bot connection for backend logic.
+
+Use a Mini App when a standard bot interface is not sufficient — for example, when the application requires forms, rich media, interactive lists, or payment flows.
+
+## Required technologies
+
+A Mini App is a standard web application. Any frontend stack works: plain HTML/CSS/JavaScript, or frameworks such as React, Vue, or Svelte. Telegram only requires a publicly accessible HTTPS URL that serves the application.
+
+For production applications, consider TypeScript and a component framework for maintainability. The [@tma.js/sdk](https://www.npmjs.com/package/@tma.js/sdk) package provides type-safe access to the Telegram Mini Apps API.
+
+## Supported Telegram clients
+
+| Client | Platform identifier |
+|--------|-------------------|
+| [Telegram for Android](https://github.com/DrKLO/Telegram) | `android` |
+| [Telegram for iOS](https://github.com/TelegramMessenger/Telegram-iOS) | `ios` |
+| [Telegram for macOS](https://github.com/overtake/TelegramSwift) | `macos` |
+| [Telegram Desktop](https://github.com/telegramdesktop/tdesktop) | `tdesktop` |
+| [Telegram Web A](https://github.com/Ajaxy/telegram-tt) | `weba` |
+| [Telegram Web K](https://github.com/morethanwords/tweb) | `web` |
+
+Each client is developed independently. Implementations may vary — report discrepancies to the [Telegram Mini Apps issues tracker](https://github.com/Telegram-Mini-Apps/issues).
 
 ## TMA developer tools
 
-- [TMA create CLI](/ecosystem/tma/create-mini-app)
-- [Telegram UI Kit](/ecosystem/tma/telegram-ui/overview)
-- [Analytics](/ecosystem/tma/analytics/analytics)
+<Columns cols={3}>
+  <Card title="Create Mini App CLI" icon="terminal" href="/ecosystem/tma/create-mini-app" />
+  <Card title="Telegram UI Kit" icon="palette" href="/ecosystem/tma/telegram-ui/overview" />
+  <Card title="Analytics" icon="chart-simple" href="/ecosystem/tma/analytics/analytics" />
+</Columns>
+
+## Platform fundamentals
+
+- [Apps communication](/ecosystem/tma/apps-communication) — how Mini Apps exchange data with the Telegram client
diff --git a/resources/dictionaries/custom.txt b/resources/dictionaries/custom.txt
index b314f0a4b..ec1c11673 100644
--- a/resources/dictionaries/custom.txt
+++ b/resources/dictionaries/custom.txt
@@ -722,8 +722,10 @@ TES
 Testgiver
 testnet
 Testnet
+tdesktop
 Tezos
 timepoint
+tma
 TMA
 TMAs
 tock

From 1e63da6976fdaded406fd70e8a15c3f20e51323b Mon Sep 17 00:00:00 2001
From: Coalus <im-coalus@proton.me>
Date: Thu, 19 Mar 2026 10:41:34 +0300
Subject: [PATCH 2/4] fix styling

---
 ecosystem/tma/apps-communication.mdx | 26 ++++++++++----------
 ecosystem/tma/overview.mdx           | 36 +++++++++++++++++++---------
 2 files changed, 39 insertions(+), 23 deletions(-)

diff --git a/ecosystem/tma/apps-communication.mdx b/ecosystem/tma/apps-communication.mdx
index c5fc2a603..abbe05d6d 100644
--- a/ecosystem/tma/apps-communication.mdx
+++ b/ecosystem/tma/apps-communication.mdx
@@ -17,11 +17,11 @@ Internally both are messages, but "methods" and "events" distinguish the directi
 
 The transport mechanism varies by Telegram client:
 
-| Platform | Transport | Details |
-|----------|-----------|---------|
-| Web (Telegram Web A, Web K) | `window.parent.postMessage` | The Mini App runs in an `<iframe>`. Messages are JSON strings passed between frames. |
-| Desktop and mobile (Android, iOS, macOS, tdesktop) | `window.TelegramWebviewProxy.postEvent` | Telegram injects a global function into the WebView. |
-| Windows Phone | `window.external.notify` | Same JSON format as the web version. |
+| Platform                                           | Transport                               | Details                                                                              |
+| -------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
+| Web (Telegram Web A, Web K)                        | `window.parent.postMessage`             | The Mini App runs in an `<iframe>`. Messages are JSON strings passed between frames. |
+| Desktop and mobile (Android, iOS, macOS, tdesktop) | `window.TelegramWebviewProxy.postEvent` | Telegram injects a global function into the WebView.                                 |
+| Windows Phone                                      | `window.external.notify`                | Same JSON format as the web version.                                                 |
 
 ## Calling methods
 
@@ -75,19 +75,21 @@ window.addEventListener('message', ({ data }) => {
 });
 ```
 
-<Aside type="caution">
-In production, validate that the `message` event originates from the Telegram application and that `data` is a string before parsing.
+<Aside
+  type="caution"
+>
+  In production, validate that the `message` event originates from the Telegram application and that `data` is a string before parsing.
 </Aside>
 
 ### Desktop, mobile, and Windows Phone
 
 These platforms deliver events by calling a globally defined function:
 
-| Platform | Function path |
-|----------|--------------|
-| Telegram Desktop | `window.TelegramGameProxy.receiveEvent` |
-| Telegram for iOS and Android | `window.Telegram.WebView.receiveEvent` |
-| Windows Phone | `window.TelegramGameProxy_receiveEvent` |
+| Platform                     | Function path                           |
+| ---------------------------- | --------------------------------------- |
+| Telegram Desktop             | `window.TelegramGameProxy.receiveEvent` |
+| Telegram for iOS and Android | `window.Telegram.WebView.receiveEvent`  |
+| Windows Phone                | `window.TelegramGameProxy_receiveEvent` |
 
 All functions share the same signature:
 
diff --git a/ecosystem/tma/overview.mdx b/ecosystem/tma/overview.mdx
index abb815945..bb52beed0 100644
--- a/ecosystem/tma/overview.mdx
+++ b/ecosystem/tma/overview.mdx
@@ -31,23 +31,37 @@ For production applications, consider TypeScript and a component framework for m
 
 ## Supported Telegram clients
 
-| Client | Platform identifier |
-|--------|-------------------|
-| [Telegram for Android](https://github.com/DrKLO/Telegram) | `android` |
-| [Telegram for iOS](https://github.com/TelegramMessenger/Telegram-iOS) | `ios` |
-| [Telegram for macOS](https://github.com/overtake/TelegramSwift) | `macos` |
-| [Telegram Desktop](https://github.com/telegramdesktop/tdesktop) | `tdesktop` |
-| [Telegram Web A](https://github.com/Ajaxy/telegram-tt) | `weba` |
-| [Telegram Web K](https://github.com/morethanwords/tweb) | `web` |
+| Client                                                                | Platform identifier |
+| --------------------------------------------------------------------- | ------------------- |
+| [Telegram for Android](https://github.com/DrKLO/Telegram)             | `android`           |
+| [Telegram for iOS](https://github.com/TelegramMessenger/Telegram-iOS) | `ios`               |
+| [Telegram for macOS](https://github.com/overtake/TelegramSwift)       | `macos`             |
+| [Telegram Desktop](https://github.com/telegramdesktop/tdesktop)       | `tdesktop`          |
+| [Telegram Web A](https://github.com/Ajaxy/telegram-tt)                | `weba`              |
+| [Telegram Web K](https://github.com/morethanwords/tweb)               | `web`               |
 
 Each client is developed independently. Implementations may vary — report discrepancies to the [Telegram Mini Apps issues tracker](https://github.com/Telegram-Mini-Apps/issues).
 
 ## TMA developer tools
 
 <Columns cols={3}>
-  <Card title="Create Mini App CLI" icon="terminal" href="/ecosystem/tma/create-mini-app" />
-  <Card title="Telegram UI Kit" icon="palette" href="/ecosystem/tma/telegram-ui/overview" />
-  <Card title="Analytics" icon="chart-simple" href="/ecosystem/tma/analytics/analytics" />
+  <Card
+    title="Create Mini App CLI"
+    icon="terminal"
+    href="/ecosystem/tma/create-mini-app"
+  />
+
+  <Card
+    title="Telegram UI Kit"
+    icon="palette"
+    href="/ecosystem/tma/telegram-ui/overview"
+  />
+
+  <Card
+    title="Analytics"
+    icon="chart-simple"
+    href="/ecosystem/tma/analytics/analytics"
+  />
 </Columns>
 
 ## Platform fundamentals

From 1791326d2bcfc66d56e3e5c9dd4df46535de1210 Mon Sep 17 00:00:00 2001
From: Coalus <im-coalus@proton.me>
Date: Thu, 19 Mar 2026 19:28:01 +0300
Subject: [PATCH 3/4] fix(tma): rewrite mini apps vs bots section

---
 ecosystem/tma/overview.mdx | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/ecosystem/tma/overview.mdx b/ecosystem/tma/overview.mdx
index bb52beed0..61ab3531a 100644
--- a/ecosystem/tma/overview.mdx
+++ b/ecosystem/tma/overview.mdx
@@ -17,17 +17,15 @@ Telegram Mini Apps (TMAs) are web applications that run inside the Telegram mess
 
 Mini Apps are an extension of [Telegram Bots](https://core.telegram.org/bots). Every Mini App is associated with a bot, which serves as the entry point. The bot provides the application URL, and Telegram loads it in a WebView.
 
-## Why use Mini Apps
+## Mini Apps vs default bot interface
 
-Telegram Bots communicate through a text-based, console-like interface. This works well for simple commands but limits the user experience for complex workflows. Mini Apps solve this by providing a full graphical interface while keeping the bot connection for backend logic.
-
-Use a Mini App when a standard bot interface is not sufficient — for example, when the application requires forms, rich media, interactive lists, or payment flows.
+Bots are limited to text messages, inline buttons, and menus. Mini Apps remove that constraint: they render arbitrary web interfaces inside a Telegram WebView — forms, dashboards, storefronts, games — while the bot behind them handles authentication, payments, and push notifications through the [Bot API](https://core.telegram.org/bots/api).
 
 ## Required technologies
 
 A Mini App is a standard web application. Any frontend stack works: plain HTML/CSS/JavaScript, or frameworks such as React, Vue, or Svelte. Telegram only requires a publicly accessible HTTPS URL that serves the application.
 
-For production applications, consider TypeScript and a component framework for maintainability. The [@tma.js/sdk](https://www.npmjs.com/package/@tma.js/sdk) package provides type-safe access to the Telegram Mini Apps API.
+Instead of handling platform differences manually (see [Apps communication](/ecosystem/tma/apps-communication)), use the [@tma.js/sdk](https://www.npmjs.com/package/@tma.js/sdk) package — a typed TypeScript API covering all Mini Apps methods and events.
 
 ## Supported Telegram clients
 

From 692f47379ca187b045384314b2fbbd810b2d6338 Mon Sep 17 00:00:00 2001
From: Coalus <im-coalus@proton.me>
Date: Mon, 23 Mar 2026 10:52:41 +0300
Subject: [PATCH 4/4] fix: fix import

---
 ecosystem/tma/apps-communication.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/ecosystem/tma/apps-communication.mdx b/ecosystem/tma/apps-communication.mdx
index abbe05d6d..ce9800721 100644
--- a/ecosystem/tma/apps-communication.mdx
+++ b/ecosystem/tma/apps-communication.mdx
@@ -2,6 +2,8 @@
 title: "Apps communication"
 ---
 
+import { Aside } from '/snippets/aside.jsx';
+
 The Telegram client and a Mini App communicate through a message-passing interface. The exact transport depends on the platform, but the protocol is the same: the Mini App sends **methods** to the Telegram client, and the Telegram client sends **events** back to the Mini App.
 
 ## Methods and events