Разработка и тестирование мини-приложений: Полное руководство

С помощью Mini Apps разработчики могут использовать JavaScript для создания бесконечно гибких интерфейсов, которые можно запускать прямо внутри Telegram — и они могут полностью заменить любой веб-сайт.

Как и боты, Mini Apps поддерживают бесшовную авторизацию, платежи через сторонних платежных провайдеров (с поддержкой Google Pay и Apple Pay из коробки), отправку персонализированных push-уведомлений пользователям, и многое другое.

Проектирование мини-приложений

Цветовые схемы

Мини-приложения всегда получают данные о текущей цветовой теме пользователя в реальном времени, так что вы можете настроить внешний вид своих интерфейсов в соответствии с ней. Например, когда пользователи переключаются между дневным и ночным режимами или используют различные пользовательские темы.

Перейти к технической информации

Руководство по дизайну

Приложения Telegram известны своей быстротой, плавностью и следованием последовательному кроссплатформенному дизайну. Ваше Мини-приложение должно в идеале отражать эти принципы.

Все элементы должны быть отзывчивыми и разработаны с учетом мобильного подхода.
Интерактивные элементы должны имитировать стиль, поведение и намерения уже существующих компонентов пользовательского интерфейса.
Все включенные анимации должны быть плавными, в идеале 60fps.
Все вводимые данные и изображения должны содержать метки для обеспечения доступности.
Приложение должно обеспечивать бесшовный опыт, отслеживая динамические цветовые схемы, предоставляемые API, и используя их соответственно.
Убедитесь, что интерфейс приложения уважает безопасную область и безопасную область контента, чтобы избежать наложения на элементы управления, особенно при использовании полноэкранного режима.
Для устройств Android учитывайте дополнительную информацию в User-Agent (см. детали User-Agent) и корректируйте в зависимости от класса производительности устройства, минимизируя анимации и визуальные эффекты на устройствах с низкой производительностью для обеспечения плавной работы.

Реализация мини-приложений

Telegram в настоящее время поддерживает семь различных способов запуска Мини Приложений: основное Мини Приложение с кнопки профиля, с кнопки клавиатуры, с инлайн-кнопки, с кнопки меню бота, через инлайн-режим, с прямой ссылки – и даже с меню вложений.

Мини-приложения на кнопках клавиатуры

Кратко: Мини-приложения, запущенные из кнопки web_app типа кнопка клавиатуры, могут отправлять данные обратно боту в сервисном сообщении с помощью Telegram.WebApp.sendData. Это позволяет боту генерировать ответ без взаимодействия с внешними серверами.

Пользователи могут взаимодействовать с ботами, используя настраиваемые клавиатуры, кнопки под сообщениями бота, а также отправляя свободные текстовые сообщения или любые из типов вложений, поддерживаемых Telegram: фотографии и видео, файлы, местоположения, контакты и опросы. Для еще большей гибкости боты могут использовать всю мощь HTML5 для создания удобных интерфейсов ввода.

Вы можете отправить кнопку web_app типа KeyboardButton, которая открывает Мини-приложение по указанному URL.

Чтобы передать данные от пользователя обратно к боту, Мини-приложение может вызвать метод Telegram.WebApp.sendData. Данные будут переданы боту в виде строки в сервисном сообщении. Бот может продолжить общение с пользователем после их получения.

Подходит для:

Настраиваемых интерфейсов ввода данных (персонализированный календарь для выбора дат; выбор данных из списка с расширенными параметрами поиска; рандомайзер, который позволяет пользователю «крутить колесо» и выбирать один из доступных вариантов и т.д.)
Повторно используемых компонентов, которые не зависят от конкретного бота.

Мини-приложения с инлайн-кнопками

Кратко: Для более интерактивных мини-приложений, таких как @DurgerKingBot, используйте тип web_app Inline KeyboardButton, который получает базовую информацию о пользователе и может быть использован для отправки сообщения от имени пользователя в чат с ботом.

Если получение только текстовых данных недостаточно или вам нужен более продвинутый и персонализированный интерфейс, вы можете открыть мини-приложение с помощью типа web_app Inline KeyboardButton.

При нажатии на кнопку откроется мини-приложение с URL-адресом, указанным в кнопке. В дополнение к настройкам темы пользователя, оно получит базовую информацию о пользователе (ID, name, username, language_code) и уникальный идентификатор сессии, query_id, который позволяет отправлять сообщения от имени пользователя обратно боту.

Бот может вызвать метод Bot API answerWebAppQuery, чтобы отправить инлайн-сообщение от пользователя обратно боту и закрыть мини-приложение. После получения сообщения бот может продолжить общение с пользователем.

Подходит для:

Полноценных веб-сервисов и интеграций любого рода.
Сферы применения фактически неограничены.

Запуск мини-приложений из кнопки меню

Кратко: Мини-приложения могут быть запущены из настроенной кнопки меню. Это просто предлагает более быстрый способ доступа к приложению и в остальном идентично запуску мини-приложения из встроенной кнопки.

По умолчанию чаты с ботами всегда показывают удобную кнопку меню, которая предоставляет быстрый доступ ко всем перечисленным командам. С Bot API 6.0 эта кнопка может быть использована для запуска мини-приложения вместо этого.

Чтобы настроить кнопку меню, вы должны указать текст, который она должна отображать, и URL мини-приложения. Существует два способа задать эти параметры:

Чтобы настроить кнопку для всех пользователей, используйте @BotFather (команда /setmenubutton или Настройки бота > Кнопка меню).
Чтобы настроить кнопку как для всех пользователей, так и для конкретных пользователей, используйте метод setChatMenuButton в Bot API. Например, измените текст кнопки в зависимости от языка пользователя или покажите ссылки на разные мини-приложения в зависимости от настроек пользователя в вашем боте.

Кроме этого, мини-приложения, открытые через кнопку меню, работают точно так же, как при использовании встроенных кнопок.

@DurgerKingBot позволяет запускать свое мини-приложение как из встроенной кнопки, так и из кнопки меню.

Запуск основного Мини-приложения

Кратко: Если ваш бот является мини-приложением, вы можете добавить заметную кнопку Запустить приложение, а также качественные демонстрационные видео и скриншоты в профиль бота. Для этого перейдите к @BotFather и настройте Основное Мини-приложение вашего бота.

Если ваш бот является мини-приложением, вы можете разблокировать ряд функций, которые упрощают и облегчают способ, которым пользователи просматривают и взаимодействуют с ним. Для этого перейдите к @BotFather и настройте Основное Мини-приложение вашего бота.

После настройки основного мини-приложения вы сможете загружать подробные демонстрации медиа-превью, чтобы публично выделить ключевые функции вашего приложения в его профиле. Также появится кнопка Запустить приложение, позволяющая пользователям открывать ваше приложение непосредственно из его профиля. Боты, которые активировали основное мини-приложение, будут отображаться на вкладке Приложения в поиске для пользователей, которые их запустили.

Медиа-превью поддерживают несколько языков – вы можете загружать переведенные версии ваших превью, которые будут показываться пользователям в зависимости от их языка приложения.

Основное Мини-приложение бота также можно открыть в текущем чате по прямой ссылке в формате https://t.me/botusername?startapp. Если в ссылке указан непустой параметр startapp, он будет передан в Мини-приложение в поле start_param и в GET-параметре tgWebAppStartParam.

Примеры

https://t.me/botusername?startapp
https://t.me/botusername?startapp=command
https://t.me/botusername?startapp=command&mode=compact

В этом режиме Мини-приложения могут использовать параметры chat_type и chat_instance для отслеживания текущего контекста чата. Это вводит поддержку одновременного и совместного использования несколькими участниками чата – для создания живых досок, групповых заказов, многопользовательских игр и подобных приложений.

По умолчанию основное Мини-приложение открывается на полный экран, и пользователи не могут уменьшить его до половины высоты. Однако вы можете изменить это поведение через @BotFather или включив параметр mode=compact в ссылку на Мини-приложение, в этом случае оно будет открываться на половину высоты экрана по умолчанию.

Хорошо для:

Полнофункциональные веб-сервисы и интеграции, которые любой пользователь может открыть одним нажатием.
Кооперативные, многопользовательские или ориентированные на командную работу сервисы в контексте чата.
Области применения фактически безграничны.

Успешные боты, которые активируют основное Мини-приложение и принимают платежи в Telegram Stars, могут быть представлены в Магазине Мини-приложений Telegram. Чтобы увеличить шансы на представление, мы рекомендуем загружать качественные медиа, демонстрирующие ваше приложение в профиле вашего бота, и следовать нашим дизайнерским рекомендациям.

Мини-приложения в режиме инлайн

Кратко: Мини-приложения, запущенные через тип web_app InlineQueryResultsButton, могут использоваться в любом месте в режиме инлайн. Пользователи могут создавать контент в веб-интерфейсе и затем без проблем отправлять его в текущий чат через режим инлайн.

Вы можете использовать параметр button в методе answerInlineQuery, чтобы отобразить специальную кнопку 'Переключиться на Мини-приложение' либо над результатами инлайн, либо вместо них. Эта кнопка откроет Мини-приложение по указанному URL. После этого вы можете вызвать метод Telegram.WebApp.switchInlineQuery, чтобы вернуть пользователя в режим инлайн.

Мини-приложения в режиме инлайн не имеют доступа к чату – они не могут читать сообщения или отправлять новые от имени пользователя. Чтобы отправить сообщения, пользователь должен быть перенаправлен в режим инлайн и активно выбрать результат.

Хорошо для:

Полнофункциональных веб-сервисов и интеграций в режиме инлайн.

Прямые ссылки на Мини Приложения

Кратко: Мини Приложения-боты могут быть запущены по прямой ссылке в любом чате. Они поддерживают параметр startapp и осведомлены о текущем контексте чата.

Вы можете использовать прямые ссылки для открытия Мини Приложения непосредственно в текущем чате. Если в ссылке указан непустой параметр startapp, он будет передан Мини Приложению в поле start_param и в GET-параметре tgWebAppStartParam.

В этом режиме Мини Приложения могут использовать параметры chat_type и chat_instance для отслеживания текущего контекста чата. Это вводит поддержку одновременного и совместного использования несколькими участниками чата – для создания живых досок, групповых заказов, многопользовательских игр и аналогичных приложений.

Мини Приложения, открытые по прямой ссылке, имеют нет доступа к чату – они не могут читать сообщения или отправлять новые от имени пользователя. Чтобы отправить сообщения, пользователя необходимо перенаправить в инлайн-режим и активно выбрать результат.

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

Примеры

https://t.me/botusername/appname
https://t.me/botusername/appname?startapp=command
https://t.me/botusername/appname?startapp=command&mode=compact

Хорошо для:

Полнофункциональные веб-сервисы и интеграции, которые любой пользователь может открыть одним нажатием.
Совместные, многопользовательские или ориентированные на командную работу сервисы в контексте чата.
Сферы применения фактически безграничны.

Запуск мини-приложений из меню вложений

Кратко: Мини-приложения-боты могут запрашивать добавление непосредственно в меню вложений пользователя, что позволяет быстро запускать их из любого чата. Чтобы попробовать этот режим, откройте ссылку на меню вложений для @DurgerKingBot, затем используйте меню в любом типе чата.

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

Интеграция меню вложений в настоящее время доступна только для крупных рекламодателей на Telegram Ad Platform. Однако все боты могут использовать его в тестовом серверном окружении.

Чтобы включить эту функцию для вашего бота, откройте @BotFather из аккаунта на тестовом сервере и отправьте команду /setattach – или перейдите в Настройки бота > Настроить меню вложений. Затем укажите URL, который будет открыт для запуска мини-приложения бота через его иконку в меню вложений.

Вы можете добавить пункт 'Настройки' в контекстное меню вашего мини-приложения с помощью @BotFather. Когда пользователи выбирают эту опцию из меню, ваш бот получит событие settingsButtonClicked.

Кроме настроек темы пользователя, бот получит основную информацию о пользователе (ID, name, username, language_code, photo), а также публичную информацию о собеседнике (ID, name, username, photo) или информацию о чате (ID, type, title, username, photo) и уникальный идентификатор для сессии веб-просмотра query_id, который позволяет отправлять сообщения любого типа в чат от имени пользователя, открывшего бота.

Бот может вызвать метод Bot API answerWebAppQuery, который отправляет встроенное сообщение от пользователя через бота в чат, где он был запущен, и закрывает мини-приложение.

Вы можете узнать больше о добавлении ботов в меню вложений здесь.

Инициализация мини-приложений

Чтобы подключить ваше Мини-приложение к клиенту Telegram, поместите скрипт telegram-web-app.js в тег <head> перед любыми другими скриптами, используя следующий код:

<script src="https://telegram.org/js/telegram-web-app.js?56"></script>

После подключения скрипта объект window.Telegram.WebApp станет доступен с следующими полями:

Поле	Тип	Описание
initData	String	Строка с необработанными данными, переданными в Мини-приложение, удобная для валидации данных. ВНИМАНИЕ: Проверьте данные из этого поля перед использованием на сервере бота.
initDataUnsafe	WebAppInitData	Объект с входными данными, переданными в Мини-приложение. ВНИМАНИЕ: Данные из этого поля не должны быть доверенными. Используйте только данные из initData на сервере бота и только после их валидации.
version	String	Версия Bot API, доступная в приложении Telegram пользователя.
platform	String	Название платформы приложения Telegram пользователя.
colorScheme	String	Цветовая схема, используемая в приложении Telegram. Либо “light”, либо “dark”. Также доступно как CSS переменная `var(--tg-color-scheme)`.
themeParams	ThemeParams	Объект, содержащий текущие настройки темы, используемые в приложении Telegram.
isActive ^{НОВИНКА}	Boolean	Bot API 8.0+ True, если Мини-приложение в настоящее время активно. False, если Мини-приложение свернуто.
isExpanded	Boolean	True, если Мини-приложение развернуто до максимальной доступной высоты. False, если Мини-приложение занимает часть экрана и может быть развернуто на полную высоту с помощью метода expand().
viewportHeight	Float	Текущая высота видимой области Мини-приложения. Также доступно в CSS как переменная `var(--tg-viewport-height)`. Приложение может отображать только верхнюю часть Мини-приложения, в то время как его нижняя часть остается вне области экрана. Из этого положения пользователь может “потянуть” Мини-приложение до максимальной высоты, в то время как бот может сделать то же самое, вызвав метод expand(). По мере изменения положения Мини-приложения текущее значение высоты видимой области будет обновляться в реальном времени. Обратите внимание, что частота обновления этого значения недостаточна для плавного отслеживания нижней границы окна. Его не следует использовать для закрепления элементов интерфейса внизу видимой области. Более уместно использовать значение поля `viewportStableHeight` для этой цели.
viewportStableHeight	Float	Высота видимой области Мини-приложения в его последнем стабильном состоянии. Также доступно в CSS как переменная `var(--tg-viewport-stable-height)`. Приложение может отображать только верхнюю часть Мини-приложения, в то время как его нижняя часть остается вне области экрана. Из этого положения пользователь может “потянуть” Мини-приложение до максимальной высоты, в то время как бот может сделать то же самое, вызвав метод expand(). В отличие от значения `viewportHeight`, значение `viewportStableHeight` не изменяется по мере изменения положения Мини-приложения с помощью жестов пользователя или во время анимаций. Значение `viewportStableHeight` будет обновлено после завершения всех жестов и анимаций, и Мини-приложение достигнет своего конечного размера. Обратите внимание на событие `viewportChanged` с переданным параметром `isStateStable=true`, которое позволит вам отслеживать, когда стабильное состояние высоты видимой области изменяется.
headerColor	String	Текущий цвет заголовка в формате `#RRGGBB`.
backgroundColor	String	Текущий цвет фона в формате `#RRGGBB`.
bottomBarColor	String	Текущий цвет нижней панели в формате `#RRGGBB`.
isClosingConfirmationEnabled	Boolean	True, если диалог подтверждения включен, когда пользователь пытается закрыть Мини-приложение. False, если диалог подтверждения отключен.
isVerticalSwipesEnabled	Boolean	True, если вертикальные свайпы для закрытия или минимизации Мини-приложения включены. False, если вертикальные свайпы для закрытия или минимизации Мини-приложения отключены. В любом случае пользователь все равно сможет минимизировать и закрыть Мини-приложение, проведя по заголовку Мини-приложения.
isFullscreen ^{НОВИНКА}	Boolean	True, если Мини-приложение в настоящее время отображается в полноэкранном режиме.
isOrientationLocked ^{НОВИНКА}	Boolean	True, если ориентация Мини-приложения в настоящее время заблокирована. False, если ориентация изменяется свободно в зависимости от поворота устройства.
safeAreaInset ^{НОВИНКА}	SafeAreaInset	Объект, представляющий безопасные области устройства, учитывающие элементы системного интерфейса, такие как вырезы или панели навигации.
contentSafeAreaInset ^NEW	ContentSafeAreaInset	Объект, представляющий безопасную зону для отображения контента внутри приложения, свободную от перекрывающихся элементов интерфейса Telegram.
BackButton	BackButton	Объект для управления кнопкой "Назад", которая может отображаться в заголовке Mini App в интерфейсе Telegram.
MainButton	BottomButton	Объект для управления главной кнопкой, которая отображается внизу Mini App в интерфейсе Telegram.
SecondaryButton	BottomButton	Объект для управления второстепенной кнопкой, которая отображается внизу Mini App в интерфейсе Telegram.
SettingsButton	SettingsButton	Объект для управления пунктом "Настройки" в контекстном меню Mini App в интерфейсе Telegram.
HapticFeedback	HapticFeedback	Объект для управления тактильной обратной связью.
CloudStorage	CloudStorage	Объект для управления облачным хранилищем.
BiometricManager	BiometricManager	Объект для управления биометрией на устройстве.
Accelerometer ^NEW	Accelerometer	Объект для доступа к данным акселерометра на устройстве.
DeviceOrientation ^NEW	DeviceOrientation	Объект для доступа к данным ориентации устройства на устройстве.
Gyroscope ^NEW	Gyroscope	Объект для доступа к данным гироскопа на устройстве.
LocationManager ^NEW	LocationManager	Объект для управления геолокацией на устройстве.
isVersionAtLeast(version)	Function	Возвращает true, если приложение пользователя поддерживает версию Bot API, равную или выше версии, переданной в качестве параметра.
setHeaderColor(color)	Function	Bot API 6.1+ Метод, который устанавливает цвет заголовка приложения в формате `#RRGGBB`. Также можно использовать ключевые слова bg_color и secondary_bg_color. До Bot API 6.9 можно передавать только Telegram.WebApp.themeParams.bg_color или Telegram.WebApp.themeParams.secondary_bg_color как цвет или ключевые слова bg_color, secondary_bg_color.
setBackgroundColor(color)	Function	Bot API 6.1+ Метод, который устанавливает цвет фона приложения в формате `#RRGGBB`. Также можно использовать ключевые слова bg_color и secondary_bg_color.
setBottomBarColor(color)	Function	Bot API 7.10+ Метод, который устанавливает цвет нижней панели приложения в формате `#RRGGBB`. Также можно использовать ключевые слова bg_color, secondary_bg_color и bottom_bar_bg_color. Этот цвет также применяется к панели навигации на Android.
enableClosingConfirmation()	Function	Bot API 6.2+ Метод, который включает диалог подтверждения при попытке пользователя закрыть Mini App.
disableClosingConfirmation()	Function	Bot API 6.2+ Метод, который отключает диалог подтверждения при попытке пользователя закрыть Mini App.
enableVerticalSwipes()	Function	Bot API 7.7+ Метод, который включает вертикальные свайпы для закрытия или минимизации Mini App. Для удобства пользователя рекомендуется всегда включать свайпы, если они не конфликтуют с собственными жестами Mini App.
disableVerticalSwipes()	Function	Bot API 7.7+ Метод, который отключает вертикальные свайпы для закрытия или минимизации Mini App. Этот метод полезен, если ваш Mini App использует жесты свайпа, которые могут конфликтовать с жестами для минимизации и закрытия приложения.
requestFullscreen() ^NEW	Function	Bot API 8.0+ Метод, который запрашивает открытие Mini App в полноэкранном режиме. Хотя заголовок становится прозрачным в полноэкранном режиме, рекомендуется, чтобы Mini App устанавливал цвет заголовка с помощью метода setHeaderColor. Этот цвет помогает определить контрастный цвет для строки состояния и других элементов интерфейса.
exitFullscreen() ^NEW	Function	Bot API 8.0+ Метод, который запрашивает выход из полноэкранного режима.
lockOrientation() ^NEW	Function	Bot API 8.0+ Метод, который блокирует ориентацию Mini App в текущем режиме (портретном или ландшафтном). После блокировки ориентация остается фиксированной, независимо от поворота устройства. Это полезно, если требуется стабильная ориентация во время определенных взаимодействий.
unlockOrientation() ^NEW	Function	Bot API 8.0+ Метод, который разблокирует ориентацию Mini App, позволяя ей свободно следовать за поворотом устройства. Используйте этот метод для восстановления автоматической настройки ориентации на основе положения устройства.
addToHomeScreen() ^NEW	Function	Bot API 8.0+ Метод, который предлагает пользователю добавить Mini App на главный экран. После успешного добавления иконки событие `homeScreenAdded` будет вызвано, если это поддерживается устройством. Обратите внимание, что если устройство не может определить статус установки, событие может не быть получено, даже если иконка была добавлена.
checkHomeScreenStatus([callback]) ^NEW	Function	Bot API 8.0+ Метод, проверяющий, поддерживается ли добавление на главный экран и был ли уже добавлен Mini App. Если передан необязательный параметр callback, функция callback будет вызвана с одним аргументом status, который является строкой, указывающей статус главного экрана. Возможные значения для status: - unsupported – функция не поддерживается, и невозможно добавить иконку на главный экран, - unknown – функция поддерживается, и иконку можно добавить, но невозможно определить, была ли она уже добавлена, - added – иконка уже была добавлена на главный экран, - missed – иконка не была добавлена на главный экран.
onEvent(eventType, eventHandler)	Function	Метод, устанавливающий обработчик событий приложения. Проверьте список доступных событий.
offEvent(eventType, eventHandler)	Function	Метод, удаляющий ранее установленный обработчик событий.
sendData(data)	Function	Метод, используемый для отправки данных боту. Когда этот метод вызывается, служебное сообщение отправляется боту, содержащее данные data длиной до 4096 байт, и Mini App закрывается. См. поле web_app_data в классе Message. Этот метод доступен только для Mini Apps, запущенных через кнопку клавиатуры.
switchInlineQuery(query[, choose_chat_types])	Function	Bot API 6.7+ Метод, который вставляет имя пользователя бота и указанный инлайн-запрос query в поле ввода текущего чата. Запрос может быть пустым, в этом случае будет вставлено только имя пользователя бота. Если передан необязательный параметр choose_chat_types, клиент предложит пользователю выбрать конкретный чат, затем откроет этот чат и вставит имя пользователя бота и указанный инлайн-запрос в поле ввода. Вы можете указать, из каких типов чатов пользователь сможет выбирать. Это может быть один или несколько следующих типов: users, bots, groups, channels.
openLink(url[, options])	Function	Метод, открывающий ссылку во внешнем браузере. Mini App не будет закрыт. Bot API 6.4+ Если передан необязательный параметр options с полем try_instant_view=true, ссылка будет открыта в режиме Instant View, если это возможно. Обратите внимание, что этот метод может быть вызван только в ответ на взаимодействие пользователя с интерфейсом Mini App (например, клик внутри Mini App или на основную кнопку).
openTelegramLink(url)	Function	Метод, открывающий ссылку Telegram внутри приложения Telegram. Mini App не будет закрыт после вызова этого метода. До Bot API 7.0 Mini App будет закрыт после вызова этого метода.
openInvoice(url[, callback])	Function	Bot API 6.1+ Метод, открывающий счет по ссылке url. Mini App получит событие invoiceClosed, когда счет будет закрыт. Если передан необязательный параметр callback, функция callback будет вызвана, и статус счета будет передан как первый аргумент.
shareToStory(media_url[, params])	Function	Bot API 7.8+ Метод, открывающий нативный редактор историй с медиа, указанным в параметре media_url как HTTPS URL. Необязательный аргумент params типа StoryShareParams описывает дополнительные настройки обмена.
shareMessage(msg_id[, callback]) ^NEW	Function	Bot API 8.0+ Метод, который открывает диалог, позволяющий пользователю поделиться сообщением, предоставленным ботом. Если указан необязательный параметр callback, функция callback будет вызвана с логическим значением в качестве первого аргумента, указывающим, было ли сообщение успешно отправлено. Идентификатор сообщения, передаваемый этому методу, должен принадлежать PreparedInlineMessage, ранее полученному через метод Bot API savePreparedInlineMessage.
setEmojiStatus(custom_emoji_id[, params, callback])	Function	Bot API 8.0+ Метод, который открывает диалог, позволяющий пользователю установить указанный пользовательский эмодзи в качестве статуса. Необязательный аргумент params типа EmojiStatusParams определяет дополнительные настройки, такие как длительность. Если указан необязательный параметр callback, функция callback будет вызвана с логическим значением в качестве первого аргумента, указывающим, был ли статус установлен. Примечание: этот метод открывает нативный диалог и не может быть использован для установки статуса эмодзи без ручного взаимодействия пользователя. Для полностью программных изменений следует использовать метод Bot API setUserEmojiStatus после получения разрешения через метод Mini App requestEmojiStatusAccess.
requestEmojiStatusAccess([callback]) ^NEW	Function	Bot API 8.0+ Метод, который показывает нативное всплывающее окно с запросом разрешения боту управлять статусом эмодзи пользователя. Если передан необязательный параметр callback, функция callback будет вызвана при закрытии всплывающего окна, а первым аргументом будет логическое значение, указывающее, предоставил ли пользователь доступ.
downloadFile(params[, callback]) ^NEW	Function	Bot API 8.0+ Метод, который отображает нативное всплывающее окно, запрашивающее у пользователя загрузку файла, указанного аргументом params типа DownloadFileParams. Если указан необязательный параметр callback, функция callback будет вызвана при закрытии всплывающего окна, где первым аргументом будет логическое значение, указывающее, принял ли пользователь запрос на загрузку.
showPopup(params[, callback])	Function	Bot API 6.2+ Метод, который показывает нативное всплывающее окно, описанное аргументом params типа PopupParams. Mini App получит событие popupClosed при закрытии всплывающего окна. Если передан необязательный параметр callback, функция callback будет вызвана, и поле id нажатой кнопки будет передано в качестве первого аргумента.
showAlert(message[, callback])	Function	Bot API 6.2+ Метод, который показывает message в простом предупреждении с кнопкой "Закрыть". Если передан необязательный параметр callback, функция callback будет вызвана при закрытии всплывающего окна.
showConfirm(message[, callback])	Function	Bot API 6.2+ Метод, который показывает message в простом окне подтверждения с кнопками "OK" и "Отмена". Если передан необязательный параметр callback, функция callback будет вызвана при закрытии всплывающего окна, где первым аргументом будет логическое значение, указывающее, нажал ли пользователь кнопку "OK".
showScanQrPopup(params[, callback])	Function	Bot API 6.4+ Метод, который показывает нативное всплывающее окно для сканирования QR-кода, описанного аргументом params типа ScanQrPopupParams. Mini App будет получать событие qrTextReceived каждый раз, когда сканер захватывает код с текстовыми данными. Если передан необязательный параметр callback, функция callback будет вызвана, и текст из QR-кода будет передан в качестве первого аргумента. Возврат значения true внутри этой функции обратного вызова приведет к закрытию всплывающего окна. Начиная с Bot API 7.7, Mini App будет получать событие scanQrPopupClosed, если пользователь закроет нативное всплывающее окно для сканирования QR-кода.
closeScanQrPopup()	Function	Bot API 6.4+ Метод, который закрывает нативное всплывающее окно для сканирования QR-кода, открытого с помощью метода showScanQrPopup. Выполните его, если вы получили корректные данные в событии qrTextReceived.
readTextFromClipboard([callback])	Function	Bot API 6.4+ Метод, который запрашивает текст из буфера обмена. Mini App получит событие clipboardTextReceived. Если передан необязательный параметр callback, функция callback будет вызвана, и текст из буфера обмена будет передан в качестве первого аргумента. Примечание: этот метод можно вызывать только для Mini Apps, запущенных из меню вложений, и только в ответ на взаимодействие пользователя с интерфейсом Mini App (например, клик внутри Mini App или на главной кнопке).
requestWriteAccess([callback])	Function	Bot API 6.9+ Метод, который показывает нативное всплывающее окно с запросом разрешения боту отправлять сообщения пользователю. Если передан необязательный параметр callback, функция callback будет вызвана при закрытии всплывающего окна, где первым аргументом будет логическое значение, указывающее, предоставил ли пользователь доступ.
requestContact([callback])	Function	Bot API 6.9+ Метод, который показывает нативное всплывающее окно с запросом номера телефона пользователя. Если передан необязательный параметр callback, функция callback будет вызвана при закрытии всплывающего окна, где первым аргументом будет логическое значение, указывающее, предоставил ли пользователь свой номер телефона.
ready()	Function	Метод, который информирует приложение Telegram о том, что Mini App готов к отображению. Рекомендуется вызывать этот метод как можно раньше, как только все основные элементы интерфейса будут загружены. После вызова этого метода загрузочный плейсхолдер скрывается, и Mini App отображается. Если метод не вызывается, плейсхолдер будет скрыт только после полной загрузки страницы.
expand()	Function	Метод, который расширяет Mini App до максимальной доступной высоты. Чтобы узнать, расширен ли Mini App до максимальной высоты, обратитесь к значению параметра Telegram.WebApp.isExpanded.
close()	Function	Метод, который закрывает Mini App.

ThemeParams

Мини-приложения могут настраивать внешний вид интерфейса в реальном времени, чтобы он соответствовал приложению Telegram пользователя. Этот объект содержит текущие настройки темы пользователя:

Поле	Тип	Описание
bg_color	String	Необязательно. Цвет фона в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-bg-color)`.
text_color	String	Необязательно. Основной цвет текста в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-text-color)`.
hint_color	String	Необязательно. Цвет подсказок в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-hint-color)`.
link_color	String	Необязательно. Цвет ссылок в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-link-color)`.
button_color	String	Необязательно. Цвет кнопок в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-button-color)`.
button_text_color	String	Необязательно. Цвет текста кнопок в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-button-text-color)`.
secondary_bg_color	String	Необязательно. Bot API 6.1+ Вторичный цвет фона в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-secondary-bg-color)`.
header_bg_color	String	Необязательно. Bot API 7.0+ Цвет фона заголовка в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-header-bg-color)`.
bottom_bar_bg_color	String	Необязательно. Bot API 7.10+ Цвет фона нижней панели в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-bottom-bar-bg-color)`.
accent_text_color	String	Необязательно. Bot API 7.0+ Цвет акцентного текста в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-accent-text-color)`.
section_bg_color	String	Необязательно. Bot API 7.0+ Цвет фона для секции в формате `#RRGGBB`. Рекомендуется использовать это в сочетании с secondary_bg_color. Также доступен как CSS-переменная `var(--tg-theme-section-bg-color)`.
section_header_text_color	String	Необязательно. Bot API 7.0+ Цвет текста заголовка для секции в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-section-header-text-color)`.
section_separator_color	String	Необязательно. Bot API 7.6+ Цвет разделителя секции в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-section-separator-color)`.
subtitle_text_color	String	Необязательно. Bot API 7.0+ Цвет текста подзаголовка в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-subtitle-text-color)`.
destructive_text_color	String	Необязательно. Bot API 7.0+ Цвет текста для разрушительных действий в формате `#RRGGBB`. Также доступен как CSS-переменная `var(--tg-theme-destructive-text-color)`.

StoryShareParams

Этот объект описывает дополнительные настройки для совместного использования в нативном редакторе историй.

Поле	Тип	Описание
text	String	Необязательно. Подпись, которая будет добавлена к медиа, 0-200 символов для обычных пользователей и 0-2048 символов для премиум подписчиков.
widget_link	StoryWidgetLink	Необязательно. Объект, который описывает ссылку на виджет, которая будет включена в историю. Обратите внимание, что только премиум подписчики могут публиковать истории со ссылками.

StoryWidgetLink

Этот объект описывает ссылку на виджет, которая будет включена в историю.

Поле	Тип	Описание
url	String	URL, который будет включен в историю.
name	String	Необязательно. Имя, которое будет отображаться для ссылки на виджет, 0-48 символов.

ScanQrPopupParams

Этот объект описывает нативное всплывающее окно для сканирования QR-кодов.

Поле	Тип	Описание
text	String	Необязательно. Текст, который будет отображаться под заголовком 'Сканировать QR', 0-64 символа.

PopupParams

Этот объект описывает нативное всплывающее окно.

Поле	Тип	Описание
title	String	Необязательно. Текст, который будет отображаться в заголовке всплывающего окна, 0-64 символа.
message	String	Сообщение, которое будет отображаться в теле всплывающего окна, 1-256 символов.
buttons	Array of PopupButton	Необязательно. Список кнопок, которые будут отображаться во всплывающем окне, 1-3 кнопки. По умолчанию установлено [{“type”:“close”}].

PopupButton

Этот объект описывает нативную кнопку всплывающего окна.

Поле	Тип	Описание
id	String	Необязательно. Идентификатор кнопки, 0-64 символа. По умолчанию установлен в пустую строку. Если кнопка нажата, её id возвращается в обратном вызове и событии popupClosed.
type	String	Необязательно. Тип кнопки. По умолчанию установлен в default. Может принимать одно из следующих значений: - default, кнопка с обычным стилем, - ok, кнопка с локализованным текстом “OK”, - close, кнопка с локализованным текстом “Закрыть”, - cancel, кнопка с локализованным текстом “Отменить”, - destructive, кнопка со стилем, указывающим на разрушительное действие (например, “Удалить”, “Стереть” и т.д.).
text	String	Необязательно. Текст, который будет отображаться на кнопке, 0-64 символа. Обязателен, если type равен default или destructive. Не имеет значения для других типов.

EmojiStatusParams

Этот объект описывает дополнительные настройки для установки эмодзи-статуса.

Поле	Тип	Описание
duration	Integer	Необязательно. Продолжительность, на которую статус будет установлен, в секундах.

DownloadFileParams

Этот объект описывает параметры запроса на загрузку файла.

Примечание: Для обеспечения согласованного поведения загрузки файлов на разных платформах рекомендуется включать HTTP заголовок Content-Disposition: attachment; filename="<file_name>" в ответ сервера. Этот заголовок помогает инициировать действие загрузки и предлагает имя файла для загружаемого файла, особенно на веб-платформах, где принудительная загрузка не всегда может быть гарантирована.

Поле	Тип	Описание
url	String	HTTPS URL файла, который нужно загрузить.
file_name	String	Предложенное имя для загружаемого файла.

SafeAreaInset

Этот объект представляет собой системно определенные отступы безопасной области, предоставляя значения отступов, чтобы гарантировать, что контент остается в пределах видимых границ, избегая наложения на элементы пользовательского интерфейса системы, такие как выемки или панели навигации.

Поле	Тип	Описание
top	Integer	Верхний отступ в пикселях, представляющий пространство, которое следует избегать в верхней части экрана. Также доступно как CSS-переменная `var(--tg-safe-area-inset-top)`.
bottom	Integer	Нижний отступ в пикселях, представляющий пространство, которое следует избегать в нижней части экрана. Также доступно как CSS-переменная `var(--tg-safe-area-inset-bottom)`.
left	Integer	Левый отступ в пикселях, представляющий пространство, которое следует избегать с левой стороны экрана. Также доступно как CSS-переменная `var(--tg-safe-area-inset-left)`.
right	Integer	Правый отступ в пикселях, представляющий пространство, которое следует избегать с правой стороны экрана. Также доступно как CSS-переменная `var(--tg-safe-area-inset-right)`.

ContentSafeAreaInset

Этот объект представляет собой границы безопасной области, определяемые содержимым, предоставляя значения отступов, чтобы гарантировать, что содержимое остается в видимых границах, избегая перекрытия с элементами интерфейса Telegram.

Поле	Тип	Описание
top	Integer	Верхний отступ в пикселях, представляющий пространство, которое следует избегать в верхней части области содержимого. Также доступен как CSS переменная `var(--tg-content-safe-area-inset-top)`.
bottom	Integer	Нижний отступ в пикселях, представляющий пространство, которое следует избегать в нижней части области содержимого. Также доступен как CSS переменная `var(--tg-content-safe-area-inset-bottom)`.
left	Integer	Левый отступ в пикселях, представляющий пространство, которое следует избегать с левой стороны области содержимого. Также доступен как CSS переменная `var(--tg-content-safe-area-inset-left)`.
right	Integer	Правый отступ в пикселях, представляющий пространство, которое следует избегать с правой стороны области содержимого. Также доступен как CSS переменная `var(--tg-content-safe-area-inset-right)`.

BackButton

Этот объект управляет кнопкой назад, которая может отображаться в заголовке Мини-приложения в интерфейсе Telegram.

Поле	Тип	Описание
isVisible	Boolean	Показывает, видима ли кнопка. По умолчанию установлено false.
onClick(callback)	Function	Bot API 6.1+ Метод, который устанавливает обработчик события нажатия кнопки. Псевдоним для `Telegram.WebApp.onEvent('backButtonClicked', callback)`
offClick(callback)	Function	Bot API 6.1+ Метод, который удаляет обработчик события нажатия кнопки. Псевдоним для `Telegram.WebApp.offEvent('backButtonClicked', callback)`
show()	Function	Bot API 6.1+ Метод, который делает кнопку активной и видимой.
hide()	Function	Bot API 6.1+ Метод, который скрывает кнопку.

Все эти методы возвращают объект BackButton, поэтому их можно связывать.

BottomButton

Этот объект управляет кнопкой, которая отображается внизу Мини-приложения в интерфейсе Telegram.

Поле	Тип	Описание
type	String	Только для чтения. Тип кнопки. Это может быть main для основной кнопки или secondary для вторичной кнопки.
text	String	Текущий текст кнопки. По умолчанию установлен на Continue для основной кнопки и Cancel для вторичной кнопки.
color	String	Текущий цвет кнопки. По умолчанию установлен на themeParams.button_color для основной кнопки и themeParams.bottom_bar_bg_color для вторичной кнопки.
textColor	String	Текущий цвет текста кнопки. По умолчанию установлен на themeParams.button_text_color для основной кнопки и themeParams.button_color для вторичной кнопки.
isVisible	Boolean	Показывает, видима ли кнопка. По умолчанию установлен на false.
isActive	Boolean	Показывает, активна ли кнопка. По умолчанию установлен на true.
hasShineEffect	Boolean	Bot API 7.10+ Показывает, имеет ли кнопка эффект сияния. По умолчанию установлен на false.
position	String	Bot API 7.10+ Позиция вторичной кнопки. Не определена для основной кнопки. Применяется только если обе кнопки видимы. По умолчанию установлен на left. Поддерживаемые значения: - left, отображается слева от основной кнопки, - right, отображается справа от основной кнопки, - top, отображается выше основной кнопки, - bottom, отображается ниже основной кнопки.
isProgressVisible	Boolean	Только для чтения. Показывает, отображает ли кнопка индикатор загрузки.
setText(text)	Function	Метод для установки текста кнопки.
onClick(callback)	Function	Метод, который устанавливает обработчик события нажатия кнопки. Псевдоним для `Telegram.WebApp.onEvent('mainButtonClicked', callback)`
offClick(callback)	Function	Метод, который удаляет обработчик события нажатия кнопки. Псевдоним для `Telegram.WebApp.offEvent('mainButtonClicked', callback)`
show()	Function	Метод для отображения кнопки. Обратите внимание, что открытие Мини-приложения из меню вложений скрывает основную кнопку до тех пор, пока пользователь не взаимодействует с интерфейсом Мини-приложения.
hide()	Function	Метод для скрытия кнопки.
enable()	Function	Метод для включения кнопки.
disable()	Function	Метод для отключения кнопки.
showProgress(leaveActive)	Function	Метод для отображения индикатора загрузки на кнопке. Рекомендуется отображать прогресс загрузки, если действие, связанное с кнопкой, может занять много времени. По умолчанию кнопка отключена, пока действие выполняется. Если передан параметр `leaveActive=true`, кнопка остается включенной.
hideProgress()	Function	Метод для скрытия индикатора загрузки.
setParams(params)	Function	Метод для установки параметров кнопки. Параметр params является объектом, содержащим одно или несколько полей, которые необходимо изменить: text - текст кнопки; color - цвет кнопки; text_color - цвет текста кнопки; has_shine_effect - Bot API 7.10+ включить эффект сияния; position - позиция вторичной кнопки; is_active - включить кнопку; is_visible - показать кнопку.

Все эти методы возвращают объект BottomButton, так что их можно объединять в цепочку.

SettingsButton

Этот объект управляет пунктом Настройки в контекстном меню Мини-приложения в интерфейсе Telegram.

Поле	Тип	Описание
isVisible	Boolean	Показывает, виден ли пункт контекстного меню. По умолчанию установлено false.
onClick(callback)	Function	Bot API 7.0+ Метод, который устанавливает обработчик события нажатия для пункта Настройки в контекстном меню. Псевдоним для `Telegram.WebApp.onEvent('settingsButtonClicked', callback)`
offClick(callback)	Function	Bot API 7.0+ Метод, который удаляет обработчик события нажатия с пункта Настройки в контекстном меню. Псевдоним для `Telegram.WebApp.offEvent('settingsButtonClicked', callback)`
show()	Function	Bot API 7.0+ Метод, который делает пункт Настройки в контекстном меню видимым.
hide()	Function	Bot API 7.0+ Метод, который скрывает пункт Настройки в контекстном меню.

Все эти методы возвращают объект SettingsButton, поэтому их можно связывать.

HapticFeedback

Этот объект управляет тактильной обратной связью.

Поле	Тип	Описание
impactOccurred(style)	Функция	Bot API 6.1+ Метод сообщает о том, что произошло воздействие. Приложение Telegram может воспроизвести соответствующие тактильные эффекты в зависимости от переданного значения стиля. Стиль может быть одним из следующих значений: - light, указывает на столкновение между небольшими или легкими элементами интерфейса, - medium, указывает на столкновение между элементами интерфейса среднего размера или веса, - heavy, указывает на столкновение между крупными или тяжелыми элементами интерфейса, - rigid, указывает на столкновение между жесткими или негибкими элементами интерфейса, - soft, указывает на столкновение между мягкими или гибкими элементами интерфейса.
notificationOccurred(type)	Функция	Bot API 6.1+ Метод сообщает о том, что задача или действие завершилось успешно, неудачно или вызвало предупреждение. Приложение Telegram может воспроизвести соответствующие тактильные эффекты в зависимости от переданного значения типа. Тип может быть одним из следующих значений: - error, указывает на то, что задача или действие завершилось неудачно, - success, указывает на то, что задача или действие завершилось успешно, - warning, указывает на то, что задача или действие вызвало предупреждение.
selectionChanged()	Функция	Bot API 6.1+ Метод сообщает о том, что пользователь изменил выбор. Приложение Telegram может воспроизвести соответствующие тактильные эффекты. Не используйте эту обратную связь, когда пользователь делает или подтверждает выбор; используйте ее только при изменении выбора.

Все эти методы возвращают объект HapticFeedback, поэтому их можно связывать.

ОблачноеХранилище

Этот объект управляет облачным хранилищем. Каждый бот может хранить до 1024 элементов на пользователя в облачном хранилище.

Поле	Тип	Описание
setItem(key, value[, callback])	Функция	Bot API 6.9+ Метод, который сохраняет значение в облачном хранилище, используя указанный ключ. Ключ должен содержать 1-128 символов, разрешены только `A-Z`, `a-z`, `0-9`, `_` и `-`. Значение должно содержать 0-4096 символов. Вы можете хранить до 1024 ключей в облачном хранилище. Если был передан необязательный параметр callback, функция callback будет вызвана. В случае ошибки первым аргументом будет ошибка. В случае успеха первым аргументом будет null, а вторым аргументом будет логическое значение, указывающее, было ли значение сохранено.
getItem(key, callback)	Функция	Bot API 6.9+ Метод, который получает значение из облачного хранилища, используя указанный ключ. Ключ должен содержать 1-128 символов, разрешены только `A-Z`, `a-z`, `0-9`, `_` и `-`. В случае ошибки функция callback будет вызвана, и первым аргументом будет ошибка. В случае успеха первым аргументом будет null, а значение будет передано как второй аргумент.
getItems(keys, callback)	Функция	Bot API 6.9+ Метод, который получает значения из облачного хранилища, используя указанные ключи. Ключи должны содержать 1-128 символов, разрешены только `A-Z`, `a-z`, `0-9`, `_` и `-`. В случае ошибки функция callback будет вызвана, и первым аргументом будет ошибка. В случае успеха первым аргументом будет null, а значения будут переданы как второй аргумент.
removeItem(key[, callback])	Функция	Bot API 6.9+ Метод, который удаляет значение из облачного хранилища, используя указанный ключ. Ключ должен содержать 1-128 символов, разрешены только `A-Z`, `a-z`, `0-9`, `_` и `-`. Если был передан необязательный параметр callback, функция callback будет вызвана. В случае ошибки первым аргументом будет ошибка. В случае успеха первым аргументом будет null, а вторым аргументом будет логическое значение, указывающее, было ли значение удалено.
removeItems(keys[, callback])	Функция	Bot API 6.9+ Метод, который удаляет значения из облачного хранилища, используя указанные ключи. Ключи должны содержать 1-128 символов, разрешены только `A-Z`, `a-z`, `0-9`, `_` и `-`. Если был передан необязательный параметр callback, функция callback будет вызвана. В случае ошибки первым аргументом будет ошибка. В случае успеха первым аргументом будет null, а вторым аргументом будет логическое значение, указывающее, были ли значения удалены.
getKeys(callback)	Функция	Bot API 6.9+ Метод, который получает список всех ключей, хранящихся в облачном хранилище. В случае ошибки функция callback будет вызвана, и первым аргументом будет ошибка. В случае успеха первым аргументом будет null, а список ключей будет передан как второй аргумент.

Все эти методы возвращают объект ОблачноеХранилище, так что их можно связывать.

BiometricManager

Этот объект управляет биометрией на устройстве. Перед первым использованием этого объекта его необходимо инициализировать с помощью метода init.

Поле	Тип	Описание
isInited	Boolean	Показывает, инициализирован ли объект биометрии.
isBiometricAvailable	Boolean	Показывает, доступна ли биометрия на текущем устройстве.
biometricType	String	Тип биометрии, доступной на устройстве. Может быть одним из следующих значений: - finger, биометрия на основе отпечатков пальцев, - face, биометрия на основе лица, - unknown, биометрия неизвестного типа.
isAccessRequested	Boolean	Показывает, была ли запрошена разрешение на использование биометрии.
isAccessGranted	Boolean	Показывает, было ли предоставлено разрешение на использование биометрии.
isBiometricTokenSaved	Boolean	Показывает, сохранен ли токен в защищенном хранилище на устройстве.
deviceId	String	Уникальный идентификатор устройства, который можно использовать для сопоставления токена с устройством.
init([callback])	Function	Bot API 7.2+ Метод, который инициализирует объект BiometricManager. Его следует вызывать перед первым использованием объекта. Если был передан необязательный параметр callback, функция callback будет вызвана, когда объект будет инициализирован.
requestAccess(params[, callback])	Function	Bot API 7.2+ Метод, который запрашивает разрешение на использование биометрии в соответствии с аргументом params типа BiometricRequestAccessParams. Если был передан необязательный параметр callback, функция callback будет вызвана, и первый аргумент будет логическим значением, указывающим, предоставил ли пользователь доступ.
authenticate(params[, callback])	Function	Bot API 7.2+ Метод, который аутентифицирует пользователя с использованием биометрии в соответствии с аргументом params типа BiometricAuthenticateParams. Если был передан необязательный параметр callback, функция callback будет вызвана, и первый аргумент будет логическим значением, указывающим, успешно ли аутентифицировался пользователь. Если да, то второй аргумент будет биометрическим токеном.
updateBiometricToken(token, [callback])	Function	Bot API 7.2+ Метод, который обновляет биометрический токен в защищенном хранилище на устройстве. Чтобы удалить токен, передайте пустую строку. Если был передан необязательный параметр callback, функция callback будет вызвана, и первый аргумент будет логическим значением, указывающим, был ли токен обновлен.
openSettings()	Function	Bot API 7.2+ Метод, который открывает настройки доступа к биометрии для ботов. Полезно, когда необходимо запросить доступ к биометрии у пользователей, которые еще не предоставили его. Обратите внимание, что этот метод можно вызывать только в ответ на взаимодействие пользователя с интерфейсом Mini App (например, при нажатии внутри Mini App или на главную кнопку)

Все эти методы возвращают объект BiometricManager, поэтому их можно связывать.

BiometricRequestAccessParams

Этот объект описывает нативное всплывающее окно для запроса разрешения на использование биометрии.

Поле	Тип	Описание
reason	String	Необязательно. Текст, который будет отображаться пользователю во всплывающем окне, описывающий, почему боту нужен доступ к биометрии, 0-128 символов.

BiometricAuthenticateParams

Этот объект описывает нативное всплывающее окно для аутентификации пользователя с использованием биометрии.

Поле	Тип	Описание
reason	String	Необязательно. Текст, который будет отображен пользователю во всплывающем окне, описывающий, почему вы просите его пройти аутентификацию и какое действие вы будете предпринимать на основе этой аутентификации, 0-128 символов.

Акселерометр

Этот объект предоставляет доступ к данным акселерометра на устройстве.

Поле	Тип	Описание
isStarted	Boolean	Указывает, активно ли в данный момент отслеживание акселерометра.
x	Float	Текущая акселерация по оси X, измеряемая в м/с².
y	Float	Текущая акселерация по оси Y, измеряемая в м/с².
z	Float	Текущая акселерация по оси Z, измеряемая в м/с².
start(params[, callback])	Function	Bot API 8.0+ Начинает отслеживание данных акселерометра с использованием params типа AccelerometerStartParams. Если предоставлен необязательный параметр callback, функция callback будет вызвана с булевым значением, указывающим, было ли отслеживание успешно начато.
stop([callback])	Function	Bot API 8.0+ Останавливает отслеживание данных акселерометра. Если предоставлен необязательный параметр callback, функция callback будет вызвана с булевым значением, указывающим, было ли отслеживание успешно остановлено.

Все эти методы возвращают объект Accelerometer, поэтому их можно связывать.

AccelerometerStartParams

Этот объект определяет параметры для начала отслеживания акселерометра.

Поле	Тип	Описание
refresh_rate	Integer	Необязательно. Частота обновления в миллисекундах, допустимые значения варьируются от 20 до 1000. По умолчанию установлено 1000. Обратите внимание, что refresh_rate может не поддерживаться на всех платформах, поэтому фактическая частота отслеживания может отличаться от указанного значения.

DeviceOrientation

Этот объект предоставляет доступ к данным об ориентации устройства.

Поле	Тип	Описание
isStarted	Boolean	Указывает, активно ли в данный момент отслеживание ориентации устройства.
absolute	Boolean	Булевое значение, указывающее, предоставляет ли устройство данные об ориентации в абсолютных значениях.
alpha	Float	Вращение вокруг оси Z, измеряемое в радианах.
beta	Float	Вращение вокруг оси X, измеряемое в радианах.
gamma	Float	Вращение вокруг оси Y, измеряемое в радианах.
start(params[, callback])	Function	Bot API 8.0+ Начинает отслеживание данных об ориентации устройства, используя params типа DeviceOrientationStartParams. Если предоставлен необязательный параметр callback, функция callback будет вызвана с булевым значением, указывающим, успешно ли было начато отслеживание.
stop([callback])	Function	Bot API 8.0+ Останавливает отслеживание данных об ориентации устройства. Если предоставлен необязательный параметр callback, функция callback будет вызвана с булевым значением, указывающим, успешно ли было остановлено отслеживание.

Все эти методы возвращают объект DeviceOrientation, поэтому их можно цепочкой вызывать.

DeviceOrientationStartParams

Этот объект определяет параметры для начала отслеживания ориентации устройства.

Поле	Тип	Описание
refresh_rate	Integer	Необязательно. Частота обновления в миллисекундах, допустимые значения варьируются от 20 до 1000. По умолчанию установлено 1000. Обратите внимание, что refresh_rate может не поддерживаться на всех платформах, поэтому фактическая частота отслеживания может отличаться от указанного значения.
need_absolute	Boolean	Необязательно. Передайте true, чтобы получить данные об абсолютной ориентации, что позволит вам определить положение устройства относительно магнитного севера. Используйте эту опцию, если реализуете функции, такие как компас в вашем приложении. Если относительных данных достаточно, передайте false. По умолчанию установлено false. Примечание: Имейте в виду, что некоторые устройства могут не поддерживать данные об абсолютной ориентации. В таких случаях вы получите относительные данные, даже если передано need_absolute=true. Проверьте параметр DeviceOrientation.absolute, чтобы определить, являются ли предоставленные данные абсолютными или относительными.

Гироскоп

Этот объект предоставляет доступ к данным гироскопа на устройстве.

Поле	Тип	Описание
isStarted	Boolean	Указывает, активно ли в настоящее время отслеживание гироскопа.
x	Float	Текущая скорость вращения вокруг оси X, измеряемая в рад/с.
y	Float	Текущая скорость вращения вокруг оси Y, измеряемая в рад/с.
z	Float	Текущая скорость вращения вокруг оси Z, измеряемая в рад/с.
start(params[, callback])	Function	Bot API 8.0+ Начинает отслеживание данных гироскопа, используя params типа GyroscopeStartParams. Если предоставлен необязательный параметр callback, функция callback будет вызвана с булевым значением, указывающим, было ли отслеживание успешно начато.
stop([callback])	Function	Bot API 8.0+ Останавливает отслеживание данных гироскопа. Если предоставлен необязательный параметр callback, функция callback будет вызвана с булевым значением, указывающим, было ли отслеживание успешно остановлено.

Все эти методы возвращают объект Gyroscope, поэтому их можно связывать.

GyroscopeStartParams

Этот объект определяет параметры для начала отслеживания гироскопа.

Поле	Тип	Описание
refresh_rate	Integer	Необязательно. Частота обновления в миллисекундах, допустимые значения варьируются от 20 до 1000. По умолчанию установлено 1000. Обратите внимание, что refresh_rate может не поддерживаться на всех платформах, поэтому фактическая частота отслеживания может отличаться от указанного значения.

LocationManager

Этот объект управляет доступом к местоположению на устройстве. Перед первым использованием этого объекта его необходимо инициализировать с помощью метода init.

Поле	Тип	Описание
isInited	Boolean	Показывает, был ли инициализирован объект LocationManager.
isLocationAvailable	Boolean	Показывает, доступны ли службы определения местоположения на текущем устройстве.
isAccessRequested	Boolean	Показывает, был ли запрошен доступ к использованию местоположения.
isAccessGranted	Boolean	Показывает, был ли предоставлен доступ к использованию местоположения.
init([callback])	Function	Bot API 8.0+ Метод, который инициализирует объект LocationManager. Он должен быть вызван перед первым использованием объекта. Если предоставлен необязательный параметр callback, функция callback будет вызвана, когда объект будет инициализирован.
getLocation(callback)	Function	Bot API 8.0+ Метод, который запрашивает данные о местоположении. Функция callback будет вызвана с null в качестве первого аргумента, если доступ к местоположению не был предоставлен, или с объектом типа LocationData в качестве первого аргумента, если доступ был успешным.
openSettings()	Function	Bot API 8.0+ Метод, который открывает настройки доступа к местоположению для ботов. Полезно, когда необходимо запросить доступ к местоположению у пользователей, которые его еще не предоставили. Обратите внимание, что этот метод может быть вызван только в ответ на взаимодействие пользователя с интерфейсом Мини-приложения (например, клик внутри Мини-приложения или на главную кнопку).

Все эти методы возвращают объект LocationManager, поэтому их можно связывать.

LocationData

Этот объект содержит данные о текущем местоположении.

Поле	Тип	Описание
latitude	Float	Широта в градусах.
longitude	Float	Долгота в градусах.
altitude	Float	Высота над уровнем моря в метрах. null, если данные о высоте недоступны на устройстве.
course	Float	Направление, в котором движется устройство, в градусах (0 = Север, 90 = Восток, 180 = Юг, 270 = Запад). null, если данные о направлении недоступны на устройстве.
speed	Float	Скорость устройства в м/с. null, если данные о скорости недоступны на устройстве.
horizontal_accuracy	Float	Точность значений широты и долготы в метрах. null, если данные о горизонтальной точности недоступны на устройстве.
vertical_accuracy	Float	Точность значения высоты в метрах. null, если данные о вертикальной точности недоступны на устройстве.
course_accuracy	Float	Точность значения направления в градусах. null, если данные о точности направления недоступны на устройстве.
speed_accuracy	Float	Точность значения скорости в м/с. null, если данные о точности скорости недоступны на устройстве.

WebAppInitData

Этот объект содержит данные, которые передаются в Мини-приложение при его открытии. Он пуст, если Мини-приложение было запущено с кнопки клавиатуры или из инлайн-режима.

Поле	Тип	Описание
query_id	String	Необязательно. Уникальный идентификатор для сессии Мини-приложения, необходимый для отправки сообщений через метод answerWebAppQuery.
user	WebAppUser	Необязательно. Объект, содержащий данные о текущем пользователе.
receiver	WebAppUser	Необязательно. Объект, содержащий данные о собеседнике текущего пользователя в чате, где бот был запущен через меню вложений. Возвращается только для частных чатов и только для Мини-приложений, запущенных через меню вложений.
chat	WebAppChat	Необязательно. Объект, содержащий данные о чате, где бот был запущен через меню вложений. Возвращается для супергрупп, каналов и групповых чатов – только для Мини-приложений, запущенных через меню вложений.
chat_type	String	Необязательно. Тип чата, из которого было открыто Мини-приложение. Может быть “sender” для частного чата с пользователем, открывающим ссылку, “private”, “group”, “supergroup” или “channel”. Возвращается только для Мини-приложений, запущенных по прямым ссылкам.
chat_instance	String	Необязательно. Глобальный идентификатор, уникально соответствующий чату, из которого было открыто Мини-приложение. Возвращается только для Мини-приложений, запущенных по прямой ссылке.
start_param	String	Необязательно. Значение параметра startattach, переданное по ссылке. Возвращается только для Мини-приложений, запущенных из меню вложений по ссылке. Значение параметра `start_param` также будет передано в GET-параметре `tgWebAppStartParam`, чтобы Мини-приложение могло сразу загрузить правильный интерфейс.
can_send_after	Integer	Необязательно. Время в секундах, после которого сообщение может быть отправлено через метод answerWebAppQuery.
auth_date	Integer	Unix-время, когда была открыта форма.
hash	String	Хэш всех переданных параметров, который сервер бота может использовать для проверки их действительности.
signature ^NEW	String	Подпись всех переданных параметров (кроме hash), которую третья сторона может использовать для проверки их действительности.

WebAppUser

Этот объект содержит данные пользователя Мини-приложения.

Поле	Тип	Описание
id	Integer	Уникальный идентификатор пользователя или бота. Это число может иметь более 32 значащих бит, и некоторые языки программирования могут испытывать трудности или иметь скрытые ошибки при его интерпретации. Оно имеет не более 52 значащих бит, поэтому для хранения этого идентификатора безопасно использовать 64-битное целое число или тип с плавающей запятой двойной точности.
is_bot	Boolean	Необязательно. True, если этот пользователь является ботом. Возвращается только в поле receiver.
first_name	String	Имя пользователя или бота.
last_name	String	Необязательно. Фамилия пользователя или бота.
username	String	Необязательно. Имя пользователя или бота.
language_code	String	Необязательно. IETF языковой тег языка пользователя. Возвращается только в поле user.
is_premium	True	Необязательно. True, если этот пользователь является пользователем Telegram Premium.
added_to_attachment_menu	True	Необязательно. True, если этот пользователь добавил бота в меню вложений.
allows_write_to_pm	True	Необязательно. True, если этот пользователь разрешил боту отправлять ему сообщения.
photo_url	String	Необязательно. URL профиля пользователя. Фотография может быть в форматах .jpeg или .svg.

WebAppChat

Этот объект представляет собой чат.

Поле	Тип	Описание
id	Integer	Уникальный идентификатор этого чата. Это число может иметь более 32 значащих бит, и некоторые языки программирования могут испытывать трудности или иметь скрытые ошибки при его интерпретации. Но у него не более 52 значащих бит, поэтому для хранения этого идентификатора безопасно использовать знаковый 64-битный целочисленный тип или тип с плавающей запятой двойной точности.
type	String	Тип чата, может быть «группа», «супергруппа» или «канал»
title	String	Название чата
username	String	Необязательно. Имя пользователя чата
photo_url	String	Необязательно. URL фотографии чата. Фотография может быть в форматах .jpeg или .svg. Возвращается только для Мини-приложений, запущенных из меню вложений.

Проверка данных, полученных через Mini App

Чтобы проверить данные, полученные через Mini App, необходимо отправить данные из поля Telegram.WebApp.initData на сервер бота. Данные представляют собой строку запроса, которая состоит из серии пар "поле-значение".

Вы можете проверить целостность полученных данных, сравнив полученный параметр hash с шестнадцатеричным представлением подписи HMAC-SHA-256 для data-check-string с секретным ключом, который является подписью HMAC-SHA-256 для токена бота с постоянной строкой WebAppData, используемой в качестве ключа.

Data-check-string — это цепочка всех полученных полей, отсортированных в алфавитном порядке, в формате key=<value> с символом переноса строки ('\n', 0x0A), используемым в качестве разделителя – например, 'auth_date=<auth_date>\nquery_id=<query_id>\nuser=<user>'.

Полная проверка может выглядеть следующим образом:

data_check_string = ...
secret_key = HMAC_SHA256(<bot_token>, "WebAppData")
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) {
// данные от Telegram
}

Чтобы предотвратить использование устаревших данных, вы также можете дополнительно проверить поле auth_date, которое содержит Unix-метку времени, когда данные были получены Mini App.

После проверки данные могут быть использованы на вашем сервере. Сложные типы данных представлены в виде объектов, сериализованных в JSON.

Проверка данных для использования третьими сторонами

^{НОВИНКА} Если вам нужно поделиться данными с третьей стороной, они могут проверить данные без необходимости доступа к вашему токену бота. Просто предоставьте им данные из поля Telegram.WebApp.initData и ваш bot_id.

Целостность данных можно проверить, валидируя полученный параметр signature, который является представлением подписи Ed25519, закодированным в base64url, для data-check-string. Проверка выполняется с использованием открытого ключа, предоставленного Telegram.

Data-check-string создается следующим образом:
1. Предварительно добавьте bot_id, за которым следует : и постоянная строка WebAppData.
2. Добавьте символ перевода строки ('\n', 0x0A).
3. Приложите все полученные поля (за исключением hash и signature), отсортированные по алфавиту, в формате key=<value>.
4. Разделите каждую пару ключ-значение символом перевода строки ('\n', 0x0A).

Пример:
'12345678:WebAppData\nauth_date=<auth_date>\nquery_id=<query_id>\nuser=<user>'

Процесс проверки может выглядеть следующим образом:

data_check_string = ...
public_key = "<Telegram_public_key>"
if (Ed25519_verify(public_key, data_check_string, signature)) {
// данные действительны и поступили от Telegram
}

Telegram предоставляет следующие открытые ключи Ed25519 для проверки подписи:

Тестовая среда: 40055058a4ee38156a06562e52eece92a771bcd8346a8c4615cb7376eddf72ec (hex)
Продакшен: e7bf03a2fa4602af4580703d88dda5bb59f32ed8b02a56c187fe7d34caed242d (hex)

Чтобы предотвратить использование устаревших данных, третья сторона также должна дополнительно проверить поле auth_date. Это поле содержит метку времени Unix, указывающую, когда данные были получены Мини-приложением.

После проверки данные могут быть использованы. Сложные типы данных представлены как объекты, сериализованные в JSON.

События, доступные для Мини-приложений

Мини-приложение может получать события из приложения Telegram, к которому можно прикрепить обработчик с помощью метода Telegram.WebApp.onEvent(eventType, eventHandler). Внутри eventHandler объект this ссылается на Telegram.WebApp, набор параметров, отправляемых обработчику, зависит от типа события. Ниже приведен список возможных событий:

eventType	Описание
`activated` ^{НОВИНКА}	Bot API 8.0+ Происходит, когда Мини-приложение становится активным (например, открыто из свернутого состояния или выбрано среди вкладок). eventHandler не получает параметров.
`deactivated` ^{НОВИНКА}	Bot API 8.0+ Происходит, когда Мини-приложение становится неактивным (например, свернуто или перемещено на неактивную вкладку). eventHandler не получает параметров.
`themeChanged`	Происходит всякий раз, когда настройки темы изменяются в приложении Telegram пользователя (включая переключение на ночной режим). eventHandler не получает параметров, новые настройки темы и цветовая схема могут быть получены через this.themeParams и this.colorScheme соответственно.
`viewportChanged`	Происходит, когда изменяется видимая часть Мини-приложения. eventHandler получает объект с единственным полем isStateStable. Если isStateStable равно true, изменение размера Мини-приложения завершено. Если false, изменение размера продолжается (пользователь расширяет или сворачивает Мини-приложение или воспроизводится анимированный объект). Текущее значение высоты видимой части доступно в this.viewportHeight.
`safeAreaChanged` ^{НОВИНКА}	Bot API 8.0+ Происходит, когда изменяются границы безопасной области устройства (например, из-за изменения ориентации или корректировки экрана). eventHandler не получает параметров. Текущие значения отступов можно получить через this.safeAreaInset.
`contentSafeAreaChanged` ^{НОВИНКА}	Bot API 8.0+ Происходит, когда изменяется безопасная область для контента (например, из-за изменения ориентации или корректировки экрана). eventHandler не получает параметров. Текущие значения отступов можно получить через this.contentSafeAreaInset.
`mainButtonClicked`	Происходит, когда нажимается главная кнопка. eventHandler не получает параметров.
`secondaryButtonClicked`	Bot API 7.10+ Происходит, когда нажимается вторичная кнопка. eventHandler не получает параметров.
`backButtonClicked`	Bot API 6.1+ Происходит, когда нажимается кнопка назад. eventHandler не получает параметров.
`settingsButtonClicked`	Bot API 6.1+ Происходит, когда элемент "Настройки" в контекстном меню нажимается. eventHandler не получает параметров.
`invoiceClosed`	Bot API 6.1+ Происходит, когда открытый счет закрывается. eventHandler получает объект с двумя полями: url – ссылка на счет и status – один из статусов счета: - paid – счет был успешно оплачен, - cancelled – пользователь закрыл этот счет без оплаты, - failed – пользователь попытался оплатить, но оплата не прошла, - pending – оплата все еще обрабатывается. Бот получит служебное сообщение о успешной оплате, когда оплата будет успешно завершена.
`popupClosed`	Bot API 6.2+ Происходит, когда открытое всплывающее окно закрывается. eventHandler получает объект с единственным полем button_id – значение поля id нажатой кнопки. Если кнопки не были нажаты, поле button_id будет null.
`qrTextReceived`	Bot API 6.4+ Происходит, когда сканер QR-кодов захватывает код с текстовыми данными. eventHandler получает объект с единственным полем data, содержащим текстовые данные из QR-кода.
`scanQrPopupClosed`	Bot API 7.7+ Происходит, когда всплывающее окно сканера QR-кодов закрывается пользователем. eventHandler не получает параметров.
`clipboardTextReceived`	Bot API 6.4+ Происходит, когда вызывается метод `readTextFromClipboard`. eventHandler получает объект с единственным полем data, содержащим текстовые данные из буфера обмена. Если буфер обмена содержит не текстовые данные, поле data будет пустой строкой. Если у Мини-приложения нет доступа к буферу обмена, поле data будет null.
`writeAccessRequested`	Bot API 6.9+ Происходит, когда запрашивается разрешение на запись. eventHandler получает объект с единственным полем status, содержащим один из статусов: - allowed – пользователь предоставил боту разрешение на запись, - cancelled – пользователь отклонил этот запрос.
`contactRequested`	Bot API 6.9+ Происходит, когда был запрошен номер телефона пользователя. eventHandler получает объект с единственным полем status, содержащим один из статусов: - sent – пользователь поделился своим номером телефона с ботом, - cancelled – пользователь отклонил этот запрос.
`biometricManagerUpdated`	Bot API 7.2+ Происходит всякий раз, когда изменяется объект BiometricManager. eventHandler не получает параметров.
`biometricAuthRequested`	Bot API 7.2+ Происходит всякий раз, когда была запрошена биометрическая аутентификация. eventHandler получает объект с полем isAuthenticated, содержащим булево значение, указывающее на успешность аутентификации пользователя. Если isAuthenticated равен true, поле biometricToken будет содержать биометрический токен, хранящийся в защищенном хранилище устройства.
`biometricTokenUpdated`	Bot API 7.2+ Происходит всякий раз, когда биометрический токен был обновлен. eventHandler получает объект с единственным полем isUpdated, содержащим булево значение, указывающее на то, был ли обновлен токен.
`fullscreenChanged` ^NEW	Bot API 8.0+ Происходит всякий раз, когда Mini App переходит в полноэкранный режим или выходит из него. eventHandler не получает параметров. Текущее состояние полноэкранного режима можно проверить через this.isFullscreen.
`fullscreenFailed` ^NEW	Bot API 8.0+ Происходит, если запрос на переход в полноэкранный режим завершился неудачей. eventHandler получает объект с единственным полем error, описывающим причину сбоя. Возможные значения для error: UNSUPPORTED – полноэкранный режим не поддерживается на этом устройстве или платформе. ALREADY_FULLSCREEN – Mini App уже находится в полноэкранном режиме.
`homeScreenAdded` ^NEW	Bot API 8.0+ Происходит, когда Mini App успешно добавлена на домашний экран. eventHandler не получает параметров.
`homeScreenChecked` ^NEW	Bot API 8.0+ Происходит после проверки статуса домашнего экрана. eventHandler получает объект с полем status, которое является строкой, указывающей текущий статус домашнего экрана. Возможные значения для status: - unsupported – функция не поддерживается, и невозможно добавить значок на домашний экран, - unknown – функция поддерживается, и значок может быть добавлен, но невозможно определить, был ли он уже добавлен, - added – значок уже добавлен на домашний экран, - missed – значок не был добавлен на домашний экран.
`accelerometerStarted` ^NEW	Bot API 8.0+ Происходит, когда отслеживание акселерометра было успешно запущено. eventHandler не получает параметров.
`accelerometerStopped` ^NEW	Bot API 8.0+ Происходит, когда отслеживание акселерометра остановлено. eventHandler не получает параметров.
`accelerometerChanged` ^NEW	Bot API 8.0+ Происходит с указанной частотой после вызова метода `start`, отправляя текущие данные акселерометра. eventHandler не получает параметров, текущие значения ускорения можно получить через this.x, this.y и this.z соответственно.
`accelerometerFailed` ^NEW	Bot API 8.0+ Происходит, если запрос на запуск отслеживания акселерометра завершился неудачей. eventHandler получает объект с единственным полем error, описывающим причину сбоя. Возможные значения для error: UNSUPPORTED – отслеживание акселерометра не поддерживается на этом устройстве или платформе.
`deviceOrientationStarted` ^NEW	Bot API 8.0+ Occurs when device orientation tracking has started successfully. eventHandler receives no parameters.
`deviceOrientationStopped` ^NEW	Bot API 8.0+ Occurs when device orientation tracking has stopped. eventHandler receives no parameters.
`deviceOrientationChanged` ^NEW	Bot API 8.0+ Occurs with the specified frequency after calling the `start` method, sending the current orientation data. eventHandler receives no parameters, the current device orientation values can be received via this.alpha, this.beta and this.gamma respectively.
`deviceOrientationFailed` ^NEW	Bot API 8.0+ Occurs if a request to start device orientation tracking fails. eventHandler receives an object with the single field error, describing the reason for the failure. Possible values for error are: UNSUPPORTED – Device orientation tracking is not supported on this device or platform.
`gyroscopeStarted` ^NEW	Bot API 8.0+ Occurs when gyroscope tracking has started successfully. eventHandler receives no parameters.
`gyroscopeStopped` ^NEW	Bot API 8.0+ Occurs when gyroscope tracking has stopped. eventHandler receives no parameters.
`gyroscopeChanged` ^NEW	Bot API 8.0+ Occurs with the specified frequency after calling the `start` method, sending the current gyroscope data. eventHandler receives no parameters, the current rotation rates can be received via this.x, this.y and this.z respectively.
`gyroscopeFailed` ^NEW	Bot API 8.0+ Occurs if a request to start gyroscope tracking fails. eventHandler receives an object with the single field error, describing the reason for the failure. Possible values for error are: UNSUPPORTED – Gyroscope tracking is not supported on this device or platform.
`locationManagerUpdated` ^NEW	Bot API 8.0+ Occurs whenever LocationManager object is changed. eventHandler receives no parameters.
`locationRequested` ^NEW	Bot API 8.0+ Occurs when location data is requested. eventHandler receives an object with the single field locationData of type LocationData, containing the current location information.
`shareMessageSent` ^NEW	Bot API 8.0+ Occurs when the message is successfully shared by the user. eventHandler receives no parameters.
`shareMessageFailed` ^NEW	Bot API 8.0+ Occurs if sharing the message fails. eventHandler receives an object with the single field error, describing the reason for the failure. Possible values for error are: UNSUPPORTED – The feature is not supported by the client. MESSAGE_EXPIRED – The message could not be retrieved because it has expired. MESSAGE_SEND_FAILED – An error occurred while attempting to send the message. USER_DECLINED – The user closed the dialog without sharing the message. UNKNOWN_ERROR – An unknown error occurred.
`emojiStatusSet` ^NEW	Bot API 8.0+ Occurs when the emoji status is successfully set. eventHandler receives no parameters.
`emojiStatusFailed` ^NEW	Bot API 8.0+ Occurs if setting the emoji status fails. eventHandler receives an object with the single field error, describing the reason for the failure. Possible values for error are: UNSUPPORTED – The feature is not supported by the client. SUGGESTED_EMOJI_INVALID – One or more emoji identifiers are invalid. DURATION_INVALID – The specified duration is invalid. USER_DECLINED – The user closed the dialog without setting a status. SERVER_ERROR – A server error occurred when attempting to set the status. UNKNOWN_ERROR – An unknown error occurred.
`emojiStatusAccessRequested` ^NEW	Bot API 8.0+ Occurs when the write permission was requested. eventHandler receives an object with the single field status containing one of the statuses: - allowed – user granted emoji status permission to the bot, - cancelled – user declined this request.
`fileDownloadRequested` ^NEW	Bot API 8.0+ Occurs when the user responds to the file download request. eventHandler receives an object with the single field status containing one of the statuses: - downloading – the file download has started, - cancelled – user declined this request.
`deviceOrientationStarted` ^НОВОЕ	Bot API 8.0+ Происходит, когда отслеживание ориентации устройства было успешно запущено. eventHandler не получает параметров.
`deviceOrientationStopped` ^НОВОЕ	Bot API 8.0+ Происходит, когда отслеживание ориентации устройства остановлено. eventHandler не получает параметров.
`deviceOrientationChanged` ^НОВОЕ	Bot API 8.0+ Происходит с указанной частотой после вызова метода `start`, отправляя текущие данные об ориентации. eventHandler не получает параметров, текущие значения ориентации устройства можно получить через this.alpha, this.beta и this.gamma соответственно.
`deviceOrientationFailed` ^НОВОЕ	Bot API 8.0+ Происходит, если запрос на запуск отслеживания ориентации устройства завершился неудачно. eventHandler получает объект с единственным полем error, описывающим причину неудачи. Возможные значения для error: UNSUPPORTED – Отслеживание ориентации устройства не поддерживается на этом устройстве или платформе.
`gyroscopeStarted` ^НОВОЕ	Bot API 8.0+ Происходит, когда отслеживание гироскопа было успешно запущено. eventHandler не получает параметров.
`gyroscopeStopped` ^НОВОЕ	Bot API 8.0+ Происходит, когда отслеживание гироскопа остановлено. eventHandler не получает параметров.
`gyroscopeChanged` ^НОВОЕ	Bot API 8.0+ Происходит с указанной частотой после вызова метода `start`, отправляя текущие данные гироскопа. eventHandler не получает параметров, текущие скорости вращения можно получить через this.x, this.y и this.z соответственно.
`gyroscopeFailed` ^НОВОЕ	Bot API 8.0+ Происходит, если запрос на запуск отслеживания гироскопа завершился неудачно. eventHandler получает объект с единственным полем error, описывающим причину неудачи. Возможные значения для error: UNSUPPORTED – Отслеживание гироскопа не поддерживается на этом устройстве или платформе.
`locationManagerUpdated` ^НОВОЕ	Bot API 8.0+ Происходит всякий раз, когда изменяется объект LocationManager. eventHandler не получает параметров.
`locationRequested` ^НОВОЕ	Bot API 8.0+ Происходит при запросе данных местоположения. eventHandler получает объект с единственным полем locationData типа LocationData, содержащим текущую информацию о местоположении.
`shareMessageSent` ^НОВОЕ	Bot API 8.0+ Происходит, когда сообщение успешно разделено пользователем. eventHandler не получает параметров.
`shareMessageFailed` ^НОВОЕ	Bot API 8.0+ Происходит, если разделение сообщения завершилось неудачно. eventHandler получает объект с единственным полем error, описывающим причину неудачи. Возможные значения для error: UNSUPPORTED – Функция не поддерживается клиентом. MESSAGE_EXPIRED – Сообщение не может быть получено, так как оно истекло. MESSAGE_SEND_FAILED – Произошла ошибка при попытке отправить сообщение. USER_DECLINED – Пользователь закрыл диалог без разделения сообщения. UNKNOWN_ERROR – Произошла неизвестная ошибка.
`emojiStatusSet` ^НОВОЕ	Bot API 8.0+ Происходит, когда статус эмодзи успешно установлен. eventHandler не получает параметров.
`emojiStatusFailed` ^НОВОЕ	Bot API 8.0+ Происходит, если установка статуса эмодзи завершилась неудачно. eventHandler получает объект с единственным полем error, описывающим причину неудачи. Возможные значения для error: UNSUPPORTED – Функция не поддерживается клиентом. SUGGESTED_EMOJI_INVALID – Один или несколько идентификаторов эмодзи недействительны. DURATION_INVALID – Указанная длительность недействительна. USER_DECLINED – Пользователь закрыл диалог без установки статуса. SERVER_ERROR – Произошла серверная ошибка при попытке установить статус. UNKNOWN_ERROR – Произошла неизвестная ошибка.
`emojiStatusAccessRequested` ^НОВОЕ	Bot API 8.0+ Происходит, когда была запрошена запись разрешений. eventHandler получает объект с единственным полем status, содержащим один из статусов: - allowed – пользователь предоставил боту разрешение на использование статуса эмодзи, - cancelled – пользователь отклонил этот запрос.
`fileDownloadRequested` ^НОВОЕ	Bot API 8.0+ Происходит, когда пользователь отвечает на запрос загрузки файла. eventHandler получает объект с единственным полем status, содержащим один из статусов: - downloading – загрузка файла началась, - cancelled – пользователь отклонил этот запрос.

Добавление ботов в меню вложений

Интеграция меню вложений в настоящее время доступна только для крупных рекламодателей на Telegram Ad Platform. Однако все боты могут использовать его в тестовой серверной среде. Поговорите с Botfather на тестовом сервере, чтобы настроить интеграцию.

Для добавления ботов в меню вложений используется специальная ссылка:

https://t.me/botusername?startattach
или
https://t.me/botusername?startattach=command

Например, откройте эту ссылку меню вложений для @DurgerKingBot, затем используйте меню в любом личном чате.

Открытие ссылки предлагает пользователю добавить бота в свое меню вложений. Если бот уже был добавлен, меню вложений откроется в текущем чате и перенаправит к боту там (если ссылка открыта из 1-на-1 чата). Если в ссылке был указан непустой параметр startattach, он будет передан в Mini App в поле start_param и в GET параметре tgWebAppStartParam.

Поддерживаются также следующие форматы ссылок:

https://t.me/username?attach=botusername
https://t.me/username?attach=botusername&startattach=command
https://t.me/+1234567890?attach=botusername
https://t.me/+1234567890?attach=botusername&startattach=command

Эти ссылки открывают Mini App в меню вложений в чате с конкретным пользователем. Если бот еще не был добавлен в меню вложений, пользователю будет предложено это сделать. Если в ссылке был указан непустой параметр startattach, он будет передан в Mini App в поле start_param и в GET параметре tgWebAppStartParam.

Bot API 6.1+ поддерживает новый формат ссылок:

https://t.me/botusername?startattach&choose=users+bots
https://t.me/botusername?startattach=command&choose=groups+channels

Открытие такой ссылки предлагает пользователю выбрать конкретный чат и открывает меню вложений в этом чате. Если бот еще не был добавлен в меню вложений, пользователю будет предложено это сделать. Вы можете указать, какие типы чатов пользователь сможет выбрать. Это может быть один или несколько из следующих типов: users, bots, groups, channels, разделенные знаком +. Если в ссылке был указан непустой параметр startattach, он будет передан в Mini App в поле start_param и в GET параметре tgWebAppStartParam.

Дополнительные данные в User-Agent

Когда Мини-приложение работает на Android, к строке User-Agent добавляется дополнительная информация, чтобы предоставить больше контекста о среде приложения. Эта информация включает версию приложения, модель устройства, версию Android, версию SDK и класс производительности устройства, отформатированные следующим образом:

Telegram-Android/{app_version} ({manufacturer} {model}; Android {android_version}; SDK {sdk_version}; {performance_class})

где:

{app_version} — это версия приложения Telegram (например, 11.3.3),
{manufacturer} {model} представляет собой производителя и модель устройства (например, Google sdk_gphone64_arm64),
{android_version} — это версия операционной системы Android, работающая на устройстве (например, 14),
{sdk_version} указывает на версию Android SDK (например, 34),
{performance_class} определяет класс производительности устройства как LOW, AVERAGE или HIGH, указывая на производственные возможности устройства.

Пример
Mozilla/5.0 (Linux; Android 14; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.5672.136 Mobile Safari/537.36 Telegram-Android/11.3.3 (Google sdk_gphone64_arm64; Android 14; SDK 34; LOW)

Мы рекомендуем использовать эту информацию для оптимизации вашего Мини-приложения на основе возможностей устройства. Например, вы можете настроить анимации и визуальные эффекты в играх на устройствах с низкой производительностью, чтобы обеспечить плавный опыт для всех пользователей, независимо от характеристик устройства.

Тестирование мини-приложений

Использование ботов в тестовой среде

Чтобы войти в тестовую среду, используйте один из следующих способов:

iOS: нажмите 10 раз на иконку Настройки > Учетные записи > Войти в другую учетную запись > Тест.
Telegram Desktop: откройте ☰ Настройки > Shift + Alt + щелчок правой кнопкой мыши на ‘Добавить учетную запись’ и выберите ‘Тестовый сервер’.
macOS: нажмите на иконку Настройки 10 раз, чтобы открыть меню отладки, ⌘ + щелчок на ‘Добавить учетную запись’ и войдите с помощью номера телефона.

Тестовая среда полностью отделена от основной среды, поэтому вам нужно будет создать новую учетную запись пользователя и нового бота с помощью @BotFather.

После получения токена вашего бота вы можете отправлять запросы к Bot API в следующем формате:

https://api.telegram.org/bot<token>/test/METHOD_NAME

Примечание: При работе с тестовой средой вы можете использовать HTTP-ссылки без TLS для тестирования вашего Мини-приложения.

Режим отладки для мини-приложений

Используйте эти инструменты для поиска проблем, специфичных для вашего мини-приложения:

iOS

В Telegram нажмите 10 раз на значок Настройки и включите Разрешить инспекцию Web View.
Подключите телефон к компьютеру с помощью USB-кабеля.
Откройте Safari на вашем Mac, затем в строке меню перейдите в Разработка > [Имя вашего устройства].
Запустите ваше мини-приложение на устройстве iOS – оно появится в меню Разработка под вашим устройством.

Android

Включите USB-отладку на вашем устройстве.
В настройках Telegram прокрутите вниз, нажмите и удерживайте номер версии два раза.
Выберите Включить отладку WebView в настройках отладки.
Подключите телефон к компьютеру и откройте chrome://inspect/#devices в Chrome – вы увидите ваше мини-приложение там, когда запустите его на телефоне.

Telegram Desktop на Windows и Linux

Скачайте и запустите Бета-версию Telegram Desktop на Windows или Linux (пока не поддерживается в Telegram Desktop для macOS).
Перейдите в Настройки > Дополнительно > Экспериментальные настройки > Включить инспекцию webview.
Щелкните правой кнопкой мыши в WebView и выберите Инспектировать.

Telegram для macOS

Скачайте и запустите Бета-версию Telegram для macOS.
Быстро нажмите 5 раз на значок Настройки, чтобы открыть меню отладки и включить “Отладка мини-приложений”.
Щелкните правой кнопкой мыши в мини-приложении и выберите Инспектировать элемент.

Мини-приложения Telegram

Проектирование мини-приложений

Цветовые схемы

Руководство по дизайну

Реализация мини-приложений

Мини-приложения на кнопках клавиатуры

Мини-приложения с инлайн-кнопками

Запуск мини-приложений из кнопки меню

Запуск основного Мини-приложения

Мини-приложения в режиме инлайн

Прямые ссылки на Мини Приложения

Запуск мини-приложений из меню вложений

Инициализация мини-приложений

ThemeParams

StoryShareParams

StoryWidgetLink

ScanQrPopupParams

PopupParams

PopupButton

EmojiStatusParams

DownloadFileParams

SafeAreaInset

ContentSafeAreaInset

BackButton

BottomButton

SettingsButton

HapticFeedback

ОблачноеХранилище

BiometricManager

BiometricRequestAccessParams

BiometricAuthenticateParams

Акселерометр

AccelerometerStartParams

DeviceOrientation

DeviceOrientationStartParams

Гироскоп

GyroscopeStartParams

LocationManager

LocationData

WebAppInitData

WebAppUser

WebAppChat

Проверка данных, полученных через Mini App

Проверка данных для использования третьими сторонами

События, доступные для Мини-приложений

Добавление ботов в меню вложений

Дополнительные данные в User-Agent

Тестирование мини-приложений

Использование ботов в тестовой среде

Режим отладки для мини-приложений