Открыть сервис
Главная → Блог → Telegram Web Apps API

Telegram Web Apps API

Telegram Web Apps API — это интерфейс программирования приложений (API), предоставляемый мессенджером Telegram, который позволяет веб-приложениям, запускаемым внутри клиента Telegram, взаимодействовать с платформой мессенджера. Данный API служит связующим звеном между веб-интерфейсом, загруженным в специальном браузерном окне (WebView), и нативным приложением Telegram, обеспечивая обмен данными, доступ к функциям устройства и интеграцию с экосистемой мессенджера.

История и предпосылки создания

До внедрения Telegram Web Apps (TWA) разработчики были ограничены возможностями Telegram Bot API. Боты могли отправлять сообщения, кнопки и простые интерфейсы, основанные на клавиатурах, но не могли предоставлять полноценный пользовательский интерфейс с динамическим контентом, сложной анимацией или вводом данных. Для реализации интерактивных сервисов (например, интернет-магазинов, игр или форм регистрации) требовалось либо открывать внешние ссылки в браузере, либо использовать ограниченные возможности Inline-режимов.

В декабре 2020 года Telegram анонсировал функцию Telegram Web Apps, которая позволяла ботам запускать полноценные веб-страницы внутри чата. Первоначально эта функция была доступна только для ботов, работающих с платежами. В последующих обновлениях (например, в версии 7.2 и выше) возможности были расширены, и появился Telegram Web Apps API — набор методов, доступных из JavaScript-кода веб-приложения. Это позволило веб-интерфейсу не просто отображаться, но и активно взаимодействовать с клиентом Telegram: отправлять данные обратно боту, изменять интерфейс (например, кнопку «Назад»), получать информацию о пользователе и его устройстве.

Архитектура и принцип работы

Telegram Web Apps API работает на основе клиент-серверной архитектуры, где веб-приложение выступает в роли клиента, а Telegram-клиент (мобильное приложение, десктопная версия или Telegram Web) — в роли хоста.

Загрузка приложения

  1. Пользователь взаимодействует с ботом (например, нажимает на кнопку с параметром web_app).
  2. Бот отправляет запрос к API Telegram с указанием URL веб-приложения.
  3. Telegram-клиент открывает встроенное окно WebView и загружает веб-страницу по указанному URL.
  4. После загрузки страницы в глобальный объект window внедряется объект Telegram.WebApp, который и предоставляет доступ к API.

Взаимодействие

Веб-приложение может:

  • Отправлять данные боту: Вызывать метод sendData(), который передаёт строку JSON обратно в чат, где бот может её обработать.
  • Закрывать приложение: Вызывать метод close().
  • Управлять интерфейсом: Изменять цвет фона, заголовка, кнопки «Назад» и основной кнопки.
  • Получать информацию о пользователе: Через объект initDataUnsafe (содержит id, first_name, username, language_code и т.д.) и initData (подписанная строка для проверки на сервере бота).
  • Отслеживать события: Подписываться на события, такие как изменение темы (светлая/тёмная), изменение размера окна, нажатие на кнопку «Назад».

Основные объекты и методы

  • Telegram.WebApp — главный объект, точка входа.
  • initData — строка с данными инициализации, подписанная секретным ключом бота. Используется для проверки подлинности запроса на серверной стороне бота.
  • initDataUnsafe — объект с теми же данными, но без подписи. Доступен для чтения на клиенте, но не должен использоваться для критичных проверок безопасности.
  • sendData(data) — отправляет строку data обратно боту.
  • close() — закрывает веб-приложение.
  • expand() — разворачивает приложение на весь экран (если это поддерживается).
  • MainButton — объект, управляющий основной кнопкой в интерфейсе Telegram (например, «Отправить», «Купить»).
  • BackButton — объект, управляющий кнопкой «Назад».
  • themeParams — объект с цветовыми параметрами текущей темы Telegram.
  • isExpanded — флаг, указывающий, развёрнуто ли приложение на весь экран.
  • platform — строка, идентифицирующая платформу клиента (например, "android", "ios", "web").

Классификация и виды

Telegram Web Apps API можно классифицировать по функциональному назначению:

  1. API для взаимодействия с ботом:
  • sendData() — передача данных от веб-приложения боту.
  • ready() — уведомление Telegram о том, что веб-приложение готово к отображению.
  • expand() — запрос на разворачивание окна.
  1. API для управления интерфейсом:
  • MainButton — управление текстом, цветом, видимостью и состоянием активности основной кнопки.
  • BackButton — управление видимостью кнопки «Назад».
  • themeParams — получение цветов темы (bg_color, text_color, button_color и др.).
  • headerColor / backgroundColor — изменение цвета заголовка и фона окна.
  1. API для получения данных о контексте:
  • initData / initDataUnsafe — данные о пользователе и чате.
  • platform — информация о платформе.
  • viewportStableHeight / viewportHeight — размеры окна просмотра.
  1. API для обработки событий:
  • onEvent('themeChanged', callback) — изменение темы.
  • onEvent('viewportChanged', callback) — изменение размера окна.
  • onEvent('backButtonClicked', callback) — нажатие на кнопку «Назад».

Применение

Telegram Web Apps API значительно расширил возможности ботов, позволяя создавать сложные и интерактивные сервисы без необходимости установки нативного приложения.

Электронная коммерция

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

Игры

Разработчики игр могут создавать браузерные игры, которые запускаются в окне Telegram. API позволяет передавать игровые очки, сохранять прогресс и взаимодействовать с другими игроками через бота.

Финансовые сервисы

Банки и финтех-компании используют TWA для предоставления услуг: проверка баланса, переводы, оплата услуг, получение выписок. API обеспечивает безопасную передачу данных и интеграцию с платёжными системами.

Образование и продуктивность

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

Социальные сервисы

Сервисы знакомств, доски объявлений, форумы. TWA позволяет создавать сложные интерфейсы с поиском, фильтрацией и обменом сообщениями, используя бота как посредника.

Безопасность и проверка данных

Ключевым аспектом работы с Telegram Web Apps API является безопасность передачи данных. Объект initData содержит строку, подписанную HMAC-SHA256 с использованием секретного ключа бота. Это позволяет разработчику на своей серверной стороне проверить, что данные действительно были отправлены от Telegram, а не подделаны злоумышленником.

Процесс проверки:

  1. Разработчик получает от клиента строку initData.
  2. Из строки извлекается параметр hash.
  3. Из оставшихся параметров (отсортированных по алфавиту) формируется строка для проверки.
  4. Вычисляется HMAC-SHA256 от этой строки, используя секретный ключ бота.
  5. Полученный хеш сравнивается с переданным hash. Если они совпадают, данные считаются подлинными.

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

Ограничения и особенности

  • Зависимость от клиента Telegram: Веб-приложение работает только внутри клиента Telegram. При попытке открыть URL в обычном браузере оно не сможет взаимодействовать с API.
  • Размер данных: Метод sendData() имеет ограничение на размер передаваемой строки (обычно до 4096 байт). Для передачи больших объёмов данных необходимо использовать другие механизмы (например, загрузку файлов через Bot API).
  • Отсутствие прямого доступа к файловой системе: Веб-приложение не может напрямую читать файлы с устройства пользователя, но может открывать диалог выбора файла через стандартные HTML-элементы.
  • Ограниченная поддержка на десктопе: Некоторые функции (например, expand()) могут работать не так, как на мобильных устройствах.
  • Необходимость HTTPS: Все ресурсы веб-приложения (HTML, CSS, JS) должны загружаться по протоколу HTTPS.

Интересные факты

  • Telegram Web Apps API является частью более широкой стратегии Telegram по превращению мессенджера в платформу для мини-приложений, аналогичную WeChat Mini Programs.
  • Разработчики могут использовать любые фреймворки для создания веб-приложений (React, Vue, Angular, Svelte), так как API не накладывает ограничений на используемые технологии.
  • Существуют библиотеки-обёртки (например, @twa-dev/sdk), которые упрощают работу с API и предоставляют типизированные интерфейсы.
  • Telegram Web Apps API активно используется для создания криптовалютных кошельков и сервисов, работающих на блокчейне TON (The Open Network).

Источники

  • Официальная документация Telegram Bot API (раздел Web Apps).
  • Официальный блог Telegram (Telegram Blog).
  • Документация по библиотеке @twa-dev/sdk (Telegram Web Apps SDK).
  • Статьи и руководства на платформах для разработчиков (например, Habr, Medium).

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →

Похожие материалы