Как открыть Mini App в Telegram: способы запуска

Mini App в Telegram открывается кнопкой в чате с ботом, кнопкой запуска в профиле бота или по ссылке вида t.me/имя_бота/имя_приложения. Устанавливать ничего не нужно, приложение живёт внутри мессенджера. Если вы разработчик и хотите вывести своё приложение в канал, группу или на сайт, кнопка web_app туда не ставится: по документации Bot API она доступна только в личном чате с ботом. Для канала и группы работает прямая ссылка.

Ниже сначала взгляд пользователя: четыре места, где обычно стоит кнопка. Затем взгляд разработчика: все способы запуска из документации одной таблицей, где каждый работает и что приложение узнаёт о человеке, ссылка в канал с параметром, кнопка в профиле, ярлык на экране телефона. В конце семь причин, по которым приложение не открывается, включая Telegram Desktop. Сверено с Bot API 10.3 от 24 августа 2026 и разделом Implementing Mini Apps документации на 19 сентября 2026. Если приложения у вас ещё нет, начните с разбора, что такое Mini App и как собрать своё: там про бота, https-адрес и проверку подписи.

Где пользователь находит и открывает Mini App

Со стороны пользователя приложение выглядит как кнопка. Она бывает в четырёх местах.

В сообщении бота. Бот присылает текст, под ним кнопка, нажатие раскрывает приложение поверх чата. Так устроены витрины, записи и анкеты.

Слева от поля ввода. У бота может быть настроена кнопка меню с названием вроде «Открыть» или «Каталог». Она стоит рядом с полем ввода в чате с ботом и доступна всегда, даже если сообщений с кнопками в чате нет.

В профиле бота. Если у бота настроено главное приложение, в его профиле появляется кнопка запуска, а под ней видео и снимки экрана с описанием. Такие боты после первого запуска показываются во вкладке «Приложения» в поиске Telegram.

По ссылке. Ссылка вида t.me/имя_бота/имя_приложения открывает приложение из любого чата, канала, сайта или QR-кода. Если у бота включено главное приложение, ссылка короче: t.me/имя_бота?startapp.

Чужого бота это тоже касается: если у него есть приложение, вы откроете его кнопкой в чате, кнопкой в профиле или по ссылке от автора. У бота без приложения открывать нечего, и со стороны пользователя это не меняется. Что приложение узнаёт о вас в момент запуска и когда оно вправе просить номер телефона, разобрано в статье безопасно ли открывать Mini App.

Способы запуска и что получает приложение

Документация Telegram перечисляет семь способов запуска, и в июне 2026 к ним добавился восьмой: приложение при заявке на вступление в чат, его показывает бот, назначенный охранником чата. Для разработчика между способами два различия: где кнопка может стоять и что приложение узнаёт о человеке, который её нажал.

Второе различие определяет, будет ли работать авторизация. Подписанные данные о пользователе приходят при запуске с инлайн-кнопки, с кнопки меню, по прямой ссылке, из профиля, из меню вложений и при заявке на вступление. При запуске с кнопки клавиатуры и из инлайн-режима объект с данными пуст, так записано в описании WebAppInitData. Приложение откроется, а кто пришёл, оно не узнает. У инлайн-кнопки и кнопки меню есть ещё query_id: одноразовый идентификатор сессии, через который приложение отправляет сообщение в чат от имени пользователя.

Кнопка в чате с ботом: инлайн, меню или клавиатура

Приложению, которое живёт в чате с ботом, хватает двух кнопок: инлайн-кнопки под приветствием и кнопки меню. Обе дают приложению подписанные данные и query_id: документация прямо говорит, что приложение из кнопки меню работает точно так же, как из инлайн-кнопки, и может отправить сообщение в чат от имени пользователя. Разница только в том, где кнопка стоит: под конкретным сообщением или постоянно рядом с полем ввода.

Инлайн-кнопка задаётся в коде бота: у InlineKeyboardButton заполняется поле web_app с адресом приложения. Пример на aiogram с этой кнопкой есть в статье про устройство Mini App, там же проверка подписи на сервере.

Кнопку меню задают двумя способами. В BotFather командой /setmenubutton или через Bot Settings и Menu Button: текст кнопки и адрес, одинаковые для всех. Методом setChatMenuButton в Bot API: и для всех, и для отдельного пользователя, так показывают разный текст по языку или разные приложения разным людям. В объект кнопки меню вместо адреса приложения можно поставить ссылку t.me на приложение бота, тогда кнопка сработает как переход по этой ссылке, с параметром startapp и без второго адреса в настройках.

Кнопка клавиатуры остаётся для одного случая: приложению не нужно знать, кто пришёл, а результат оно возвращает боту одной строкой через sendData. Календарь для выбора даты, колесо выбора, форма без личных данных. Всё, где есть заказ, кабинет или история, идёт через инлайн-кнопку или меню.

Прямая ссылка: как вывести приложение в канал, группу и на сайт

После запуска в чате следующий вопрос: пост в канале или группа. Кнопка web_app туда не ставится: в описании поля у инлайн-кнопки Bot API стоит «Available only in private chats between a user and the bot», то есть только в личных чатах между пользователем и ботом. Попытка отправить сообщение с такой кнопкой в группу или канал отклоняется самим Bot API, бот получает ошибку BUTTON_TYPE_INVALID, и сообщение не уходит.

Для канала и группы есть прямая ссылка. Документация раздела о Mini Apps: приложения могут быть запущены по прямой ссылке в любом чате. Ссылка выглядит как t.me/имя_бота/имя_приложения. Имя приложения заводится в BotFather командой /newapp: у одного бота может быть несколько именованных приложений, и различаются они этим коротким именем. Ссылку можно вставить текстом в пост, положить в закреп группы, на сайт или в QR-код на стойке. Кнопку под постом канала со ссылкой отправляет бот, добавленный в канал администратором с правом публиковать: из самого приложения Telegram кнопку к посту не прикрепить, только ссылку в тексте. Открывается ссылка внутри Telegram, поверх текущего чата.

К ссылке добавляется параметр startapp. Его значение приложение получает в поле start_param и в GET-параметре tgWebAppStartParam. Так один и тот же экран узнаёт, откуда пришёл человек: из канала, из закрепа группы, с визитки. Вместе с параметром приложению приходят тип чата и обезличенный признак chat_instance, общий для всех участников этого чата, поэтому оно может вести общее состояние на чат: групповой заказ, доска, игра на несколько участников. Читать сообщения и писать от имени человека приложение по ссылке не может.

Начиная с Bot API 7.6 приложение по прямой ссылке открывается сразу на полную высоту. Если нужно окно на половину экрана, в ссылку добавляют mode=compact.

Главное приложение: кнопка в профиле бота и вкладка «Приложения»

Если бот и есть приложение, в BotFather для него включают главное приложение (Main Mini App, появилось в Bot API 7.8 в июле 2024). После этого в профиле бота появляется кнопка запуска, а рядом можно загрузить видео и снимки экрана с описанием, в том числе на разных языках. Дальше бот попадает во вкладку «Приложения» в поиске у тех, кто его уже запускал, и получает короткую ссылку t.me/имя_бота?startapp, с параметром t.me/имя_бота?startapp=promo. Высоту окна по умолчанию для главного приложения меняют в BotFather.

Отдельная витрина у Telegram тоже есть: боты с главным приложением, принимающие оплату в Stars, могут попасть в подборку Mini App Store. Документация советует загрузить качественные превью и следовать рекомендациям по дизайну; гарантий попадания нет.

Ярлык на экране телефона и полный экран

С Bot API 8.0 (ноябрь 2024) приложение может попросить пользователя добавить его ярлык на главный экран телефона: вызов Telegram.WebApp.addToHomeScreen() из кода приложения, например по кнопке «Добавить на экран», показывает системный запрос, а checkHomeScreenStatus заранее проверяет, поддерживает ли устройство ярлык и не добавлен ли он уже. После этого приложение открывается с экрана, как обычное, хотя внутри всё так же работает Telegram. Запрос делает само приложение, поэтому если ярлыка нет, значит разработчик его не предусмотрел; документация описывает ярлыки только для мобильных устройств.

Там же появился полный экран: requestFullscreen разворачивает приложение на весь экран, включая горизонтальную ориентацию. Для витрины это лишнее, для игр и редакторов полезно.

Почему Mini App не открывается

Семь причин, которые стоит проверить по порядку.

Адрес без https. Поле url у приложения в Bot API описано как «An HTTPS URL». Кнопку с обычным http-адресом Bot API отклоняет ещё при отправке, бот получает ошибку. Ссылки без сертификата допустимы только в тестовой среде Telegram. Пока приложение живёт на вашем ноутбуке, нужен туннель с https-адресом; где держать фронтенд потом, разобрано в статье про хостинг фронта.

Кнопка web_app в группе или канале. Она работает только в личном чате с ботом. Признак: в личке сообщение с кнопкой уходит, при отправке в группу или канал бот получает ошибку BUTTON_TYPE_INVALID. Лечится заменой на url-кнопку с прямой ссылкой из раздела выше.

Приложение не отвечает. Telegram открывает ваш адрес во встроенном браузере; если сервер лежит, сертификат просрочен или домен не находится по имени, пользователь видит пустое окно. Проверка простая: открыть тот же адрес в обычном браузере на телефоне.

Старая версия Telegram. Каждая возможность привязана к версии Bot API: главное приложение к 7.8, ярлыки и полный экран к 8.0. На старом клиенте кнопка в профиле или ярлык не появятся. Обновить Telegram, потом проверять заново.

Telegram Desktop на Windows. Настольный клиент показывает приложения через системный компонент WebView2. В трекере Telegram Desktop есть жалобы, где на Windows приложение с кнопки не открывается или показывает ошибку «Could not initialize WebView»; в одном из разборов помогла правка прав доступа к исполняемому файлу WebView2. Первые шаги те же: обновить клиент, убедиться, что WebView2 от Microsoft установлен (он ставится отдельно от Telegram, со страницы Microsoft по названию компонента), и сверить, что на телефоне то же приложение открывается.

Ссылка на несуществующее приложение. Опечатка в имени бота или в коротком имени после t.me/имя_бота/, либо приложение с таким именем у бота не заведено. Проверяется в BotFather: список приложений бота командой /myapps и точное короткое имя.

Тестовая среда. Приложение создано в тестовой среде Telegram, а открывают его из основной. Среды полностью раздельны: бот и его приложение из тестовой среды для основной не существуют.

Что сделать сегодня

Для приложения, которое уже работает в чате: настроить кнопку меню в BotFather, чтобы вход был всегда под рукой. Завести именованное приложение и получить ссылку t.me/имя_бота/имя_приложения. Поставить ссылку в закреп канала или под пост с параметром startapp и посмотреть в приложении, что параметр доходит. Открыть на телефоне и на компьютере. Если бот целиком про приложение, включить главное приложение и загрузить превью.

Если приложения ещё нет, а нужна панель с клиентами и рассылками внутри Telegram, есть готовый шаблон на Python: бот и панель в одном процессе, кнопка запуска уже настроена. Когда после ссылки в канале выясняется, что приложению нужны каталог, оплата и связь с учётной системой, это уже разработка по часам: объём и вилки лежат на странице услуги Telegram Mini Apps.