JavaScript SDK Telegram Web App: ключевые функции и методы для разработки мини-приложений

Когда вы открываете мини-приложение в Telegram, вы не просто запускаете веб-сайт - вы взаимодействуете с мощной платформой, которая дает доступ к функциям самого мессенджера. Это возможно благодаря JavaScript SDK Telegram Web App, который позволяет вашему веб-приложению говорить на языке Telegram. Без этого SDK вы бы видели просто пустую страницу. С ним - вы получаете кнопки, уведомления, данные пользователя, интеграцию с платежами и даже возможность открывать встроенные модальные окна, как будто вы внутри самого Telegram.

Что такое Telegram Web App и зачем он нужен

Telegram Web App - это веб-страница, запущенная внутри приложения Telegram. Она может быть вызвана через бота, кнопку в меню или ссылку. Это не iframe, не внешний сайт, а полноценная часть интерфейса Telegram. Пользователь не покидает мессенджер - он остается в нем, но использует вашу функциональность: покупает товар, заполняет форму, играет в игру или управляет задачами.

Всё это работает благодаря JavaScript SDK, который автоматически загружается, когда страница открывается в Telegram. Вы не скачиваете его отдельно. Он уже есть в браузере внутри Telegram. Ваша задача - подключиться к нему и использовать его методы. Без этого SDK вы не сможете получить ни имя пользователя, ни его ID, ни доступ к кнопкам, ни даже узнать, открыто ли приложение на телефоне или на ПК.

Как подключиться к Telegram Web App SDK

Подключение происходит автоматически. Когда пользователь открывает ваше мини-приложение через Telegram, браузер внутри Telegram загружает специальный скрипт - window.Telegram.WebApp. Это глобальный объект, который вы можете использовать сразу после загрузки страницы.

Простой пример:

<script>
  if (window.Telegram && window.Telegram.WebApp) {
    const webapp = window.Telegram.WebApp;
    console.log('Пользователь ID:', webapp.initDataUnsafe.user?.id);
  }
</script>

Важно: не все устройства загружают SDK одинаково. На десктопе (Windows, macOS) он может быть ограничен. На мобильных устройствах - работает стабильно. Поэтому всегда проверяйте, доступен ли объект, прежде чем использовать его методы.

Основные методы и их практическое применение

Вот ключевые функции SDK, которые реально используются в продакшене:

• WebApp.expand() - расширяет приложение до полного экрана. По умолчанию мини-приложение занимает только нижнюю часть экрана. Вызов этого метода делает его полноэкранным. Используется, когда пользователь переходит к сложному интерфейсу, например, к оформлению заказа.
• WebApp.close() - закрывает мини-приложение и возвращает пользователя в чат с ботом. Никаких «назад» или «закрыть» - просто вызов этого метода. Это стандартное поведение в Telegram.
• WebApp.ready() - сигнал SDK, что приложение готово к работе. Вы должны вызвать его вручную, как только загрузились все данные. Без этого Telegram не отображает индикатор загрузки и не разрешает кнопки. Это критично: если вы забудете вызвать ready(), пользователь будет видеть бесконечный спиннер.
• WebApp.setHeaderColor('#FF5722') - меняет цвет верхней панели. Вы можете подстроить дизайн под бренд. Цвета должны быть в HEX-формате. Нельзя использовать прозрачные или слишком темные оттенки - Telegram автоматически корректирует их для читаемости.
• WebApp.showAlert('Спасибо за покупку!') - показывает всплывающее уведомление. Это альтернатива JavaScript-алертам. В Telegram они работают плавно, без блокировки интерфейса.

Пример реального сценария: пользователь нажимает кнопку «Оплатить» в вашем мини-приложении. Вы вызываете expand(), чтобы показать форму, потом showAlert() после успешной оплаты, и в конце close(), чтобы вернуть его в чат. Всё это - без перезагрузки страницы.

Данные пользователя и безопасность

SDK предоставляет доступ к информации о пользователе через объект initDataUnsafe. В нём есть:

• id - уникальный идентификатор пользователя в Telegram
• first_name, last_name - имя и фамилия
• username - никнейм
• language_code - язык интерфейса пользователя (например, ru, en, uk)

Но тут важно: initDataUnsafe - это данные, которые пришли от Telegram. Они подписаны цифровой подписью. Если вы хотите быть уверены, что данные не подделаны, вы должны проверить подпись на своём сервере с помощью ключа бота. Это не делает SDK уязвимым - это стандартная практика. Без проверки подписи вы рискуете, что кто-то подменит ID пользователя и получит доступ к его данным.

Пример проверки: вы отправляете initData (все параметры, кроме подписи) и hash на свой бэкенд. Там вы генерируете хеш по тому же алгоритму, что и Telegram, и сравниваете. Если совпадает - данные легитимны. Если нет - отклоняете запрос. Telegram предоставляет документацию по этому алгоритму. Многие фреймворки, такие как telegraf для Node.js, делают это автоматически.

Кнопки и интерфейс

Telegram Web App позволяет добавлять до 5 кнопок внизу экрана. Это не обычные HTML-кнопки - это интегрированные элементы интерфейса Telegram. Они работают даже если приложение свернуто.

Вы управляете кнопками через WebApp.MainButton и WebApp.BackButton.

• MainButton - основная кнопка. Она появляется внизу экрана. Вы можете задать текст, цвет, включить/отключить её, и назначить обработчик клика. Например, «Оплатить», «Отправить», «Завершить».
• BackButton - кнопка возврата. Она появляется слева в шапке. По умолчанию она скрыта. Вы можете показать её, если пользователь зашёл в подменю, и скрыть, когда возвращаетесь на главный экран.

Пример:

const mainButton = WebApp.MainButton;
mainButton.setText('Оплатить');
mainButton.setColor('#26A69A');
mainButton.show();

mainButton.onClick(() => {
  // Отправляем данные на сервер
  fetch('/pay', { method: 'POST', body: JSON.stringify(data) });
  mainButton.setText('Обрабатывается...');
  mainButton.disable();
});

Если вы не вызываете show(), кнопка не появится. Если не вызываете disable() - пользователь может нажать её несколько раз и отправить дублирующие запросы. Это частая ошибка у новичков.

Платежи и интеграция с ботами

Telegram Web App поддерживает оплату через Telegram Payments. Это не PayPal, не Stripe - это встроенная система, которая работает через ботов. Вы не можете просто вставить кнопку «Оплатить картой». Вы должны настроить бота как платёжный шлюз.

Процесс:

1. Вы создаёте бота через BotFather и включаете платежи.
2. На вашем сервере вы создаёте инвойс - объект с названием, ценой, описанием и ID пользователя.
3. Вы отправляете этот инвойс через API Telegram Bot, используя метод sendInvoice.
4. Пользователь получает уведомление в чате с ботом и оплачивает через Telegram.
5. Telegram отправляет вам уведомление о платеже на вебхук, который вы указали при настройке бота.

Ваше мини-приложение может запускать этот процесс через WebApp.openInvoice(). Вы передаёте URL инвойса, и Telegram открывает окно оплаты внутри приложения. После оплаты вы получаете событие invoiceClosed, и можете обновить интерфейс.

Как тестировать Web App без телефона

Вы не можете тестировать мини-приложение на обычном браузере. Оно не работает без Telegram. Но есть обходной путь - Telegram предоставляет веб-версию с поддержкой Web App. Вы можете открыть ваше приложение через ссылку вида https://t.me/yourbot?startapp=yourapp в браузере на ПК. SDK загрузится, и вы сможете отлаживать код через DevTools.

Важно: не все функции работают на десктопе. Например, кнопки внизу экрана могут быть скрыты. Но основные методы - initData, expand(), close() - работают. Это лучший способ тестирования без Android или iOS.

Частые ошибки и как их избежать

• Не вызываете WebApp.ready() - приложение висит с спиннером. Решение: вызывайте его сразу после получения данных пользователя.
• Используете initDataUnsafe без проверки подписи - риск подмены данных. Решение: всегда проверяйте хеш на сервере.
• Скрываете кнопку, но не убираете обработчик - пользователь нажимает «назад», а приложение продолжает работать. Решение: отписывайтесь от событий при закрытии.
• Используете window.alert() - в Telegram это не работает. Решение: всегда используйте WebApp.showAlert().
• Забываете про темную тему - пользователь может использовать тёмный режим. Решение: используйте WebApp.isDarkMode и адаптируйте цвета.

Что дальше: продвинутые возможности

После освоения базы вы можете перейти к более сложным сценариям:

• Использовать WebApp.openLink() для открытия внешних ссылок внутри Telegram, а не в браузере.
• Интегрировать с WebApp.HapticFeedback для тактильных уведомлений (вибрация при нажатии).
• Создавать собственные модальные окна с помощью WebApp.showPopup().
• Получать доступ к камере или геолокации через стандартные API браузера - Telegram разрешает их в Web App.

Многие компании, включая банки в России и магазины в СНГ, уже используют Telegram Web App для продаж, регистрации и поддержки. Это не эксперимент - это рабочая инфраструктура. И JavaScript SDK - ключ, который делает это возможным.