Как подключить WebApp к Telegram

На чтение 8 мин Просмотров 27 Опубликовано Обновлено

Telegram WebApp — это веб-приложение, которое открывается непосредственно внутри Telegram. В актуальной терминологии такие приложения называются Telegram Mini Apps, однако разработчики по-прежнему используют объект Telegram.WebApp, а пользователи часто ищут инструкции именно по запросу «как подключить WebApp к Telegram».

Для базового подключения понадобятся Telegram-бот, веб-страница с JavaScript и публичный адрес с HTTPS. Если приложение работает с профилями, заказами, оплатой или другими защищенными данными, также потребуется backend.

Содержание
  1. Коротко: как подключить WebApp к Telegram
  2. Что такое Telegram WebApp
  3. Как работает подключение
  4. Что понадобится для подключения
  5. Шаг 1. Создаем Telegram-бота
  6. Шаг 2. Готовим страницу WebApp
  7. Разница между initData и initDataUnsafe
  8. Шаг 3. Размещаем приложение на хостинге
  9. Шаг 4. Добавляем кнопку запуска WebApp
  10. Запуск через меню бота
  11. Шаг 5. Проверяем данные на сервере
  12. Шаг 6. Передаем данные из приложения
  13. Когда используется sendData
  14. Как проверить подключение
  15. Распространенные ошибки
  16. Часто задаваемые вопросы
  17. Можно ли подключить к Telegram готовый сайт?
  18. Можно ли создать WebApp без backend?
  19. Можно ли доверять initDataUnsafe?
  20. Можно ли автоматически получить номер телефона?
  21. Можно ли использовать React или Vue?
  22. Заключение

Коротко: как подключить WebApp к Telegram

  1. Создайте бота через BotFather.
  2. Подготовьте страницу приложения.
  3. Подключите скрипт Telegram Web App.
  4. Разместите страницу на HTTPS-адресе.
  5. Добавьте URL в кнопку типа web_app.
  6. Запустите приложение через бота.
  7. Передайте initData на backend.
  8. Проверьте подлинность полученных данных.

Разберем каждый этап подробнее.

Что такое Telegram WebApp

Telegram WebApp, или Telegram Mini App, — это обычное веб-приложение на HTML, CSS и JavaScript, адаптированное для запуска во встроенном окне Telegram.

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

Как работает подключение

Общая схема выглядит так:

  1. Пользователь открывает Telegram-бота.
  2. Бот показывает кнопку запуска.
  3. Telegram загружает веб-приложение по указанному адресу.
  4. Скрипт получает доступ к объекту Telegram.WebApp.
  5. Приложение считывает параметры запуска.
  6. Защищенные данные передаются на backend для проверки.
  7. Сервер выполняет нужное действие и возвращает результат.

Frontend отвечает за интерфейс, а backend — за проверку пользователя, работу с базой данных и выполнение защищенных операций.

Что понадобится для подключения

Компонент Назначение
Telegram-аккаунт Создание и настройка бота
Telegram-бот Запуск Mini App
Токен бота Работа с Bot API и проверка данных
HTML, CSS и JavaScript Интерфейс приложения
Публичный HTTPS-адрес Загрузка приложения внутри Telegram
Backend Проверка пользователя и серверная логика

Для простой демонстрационной страницы достаточно HTML и JavaScript. Для интернет-магазина, личного кабинета, записи на услуги или хранения информации нужен сервер.

Шаг 1. Создаем Telegram-бота

Откройте BotFather в Telegram и запустите создание нового бота. Укажите отображаемое имя, а затем задайте уникальное имя пользователя, которое заканчивается на bot.

После создания BotFather выдаст токен.

Токен нельзя размещать в HTML или клиентском JavaScript. Код страницы доступен пользователю, поэтому секретное значение могут скопировать. Храните токен только на сервере, например в переменных окружения.

В примерах используйте заглушку:

YOUR_BOT_TOKEN

Если токен оказался в открытом доступе, его необходимо отозвать и заменить.

Шаг 2. Готовим страницу WebApp

Создайте файл index.html со следующим содержимым:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, initial-scale=1.0">

    <title>Мое приложение</title>

    <script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
    <h1>Приложение запущено</h1>
    <p id="username">Загрузка данных...</p>

    <script>
        const app = window.Telegram.WebApp;

        app.ready();
        app.expand();

        const user = app.initDataUnsafe?.user;
        const username = document.getElementById("username");

        username.textContent = user
            ? `Здравствуйте, ${user.first_name}!`
            : "Здравствуйте!";
    </script>
</body>
</html>

Метатег viewport помогает корректно показывать страницу на смартфонах. Официальный скрипт создает объект window.Telegram.WebApp.

Метод ready() сообщает Telegram, что основные элементы интерфейса загружены. Метод expand() запрашивает максимальную доступную высоту окна.

Разница между initData и initDataUnsafe

initData — строка с параметрами запуска, которую нужно отправлять на backend и проверять.

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

Данные в браузере можно изменить. Поэтому защищенные действия выполняются только после серверной проверки initData.

Шаг 3. Размещаем приложение на хостинге

Telegram должен иметь возможность загрузить страницу из интернета. Адрес приложения должен использовать HTTPS.

Пример:

https://example.com/telegram-app/

Загрузите HTML, CSS и JavaScript на сервер, настройте SSL-сертификат и откройте URL в обычном браузере.

Проверьте:

  • загружается ли страница без ошибок;
  • работают ли стили и скрипты;
  • удобно ли пользоваться интерфейсом на смартфоне;
  • не выходят ли элементы за границы экрана;
  • нет ли смешанного HTTP- и HTTPS-контента.

Адрес localhost подходит для локальной разработки, но недоступен обычным пользователям. Для тестирования нужен публичный HTTPS-адрес.

Шаг 4. Добавляем кнопку запуска WebApp

Mini App можно открыть через кнопку под сообщением, пользовательскую клавиатуру, меню или профиль бота. Один из распространенных вариантов — inline-кнопка с параметром web_app.

Структура запроса к Bot API может выглядеть так:

{
  "chat_id": 123456789,
  "text": "Откройте приложение",
  "reply_markup": {
    "inline_keyboard": [
      [
        {
          "text": "Запустить",
          "web_app": {
            "url": "https://example.com/telegram-app/"
          }
        }
      ]
    ]
  }
}

Замените chat_id на идентификатор чата, а URL — на адрес своего приложения.

Важно использовать именно параметр web_app. Обычная URL-кнопка может открыть страницу как внешнюю ссылку, а не как Mini App.

Запуск через меню бота

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

Названия и расположение разделов BotFather могут меняться. Ориентируйтесь на настройки бота, Menu Button и Mini App.

Шаг 5. Проверяем данные на сервере

Клиентское приложение должно отправить значение Telegram.WebApp.initData на backend.

Сервер выполняет следующие действия:

  1. Разбирает полученную строку параметров.
  2. Отделяет значение hash.
  3. Сортирует остальные поля по имени.
  4. Формирует строку проверки.
  5. Создает секретный ключ на основе токена бота.
  6. Вычисляет подпись.
  7. Сравнивает результат с полученным hash.
  8. Проверяет время из поля auth_date.

Только после успешной проверки данные можно считать полученными от Telegram.

Токен участвует в проверке, поэтому этот процесс нельзя выполнять в браузере.

Шаг 6. Передаем данные из приложения

Для полноценного сервиса рекомендуется отправлять данные на собственный backend:

fetch("https://example.com/api/action", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        initData: Telegram.WebApp.initData,
        action: "create_order"
    })
});

Сервер проверяет initData, определяет пользователя и только затем создает заказ или выполняет другое действие.

Когда используется sendData

Метод Telegram.WebApp.sendData() позволяет отправить строку боту, но он применяется для Mini Apps, открытых через кнопку пользовательской клавиатуры.

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

Как проверить подключение

Перед публикацией пройдите чек-лист:

  • бот отвечает пользователю;
  • кнопка запуска отображается;
  • используется параметр web_app;
  • страница открывается внутри Telegram;
  • URL работает по HTTPS;
  • вызывается Telegram.WebApp.ready();
  • интерфейс адаптирован под смартфоны;
  • учтены светлая и темная темы;
  • initData передается на backend;
  • подпись проверяется на сервере;
  • токен отсутствует в клиентском коде;
  • приложение проверено на Android, iPhone и компьютере.

Распространенные ошибки

Ошибка Возможная причина Решение
Кнопка не появилась Неверная структура клавиатуры Проверьте reply_markup и web_app
Страница не открывается Проблема с адресом или сертификатом Проверьте URL и HTTPS
Открывается браузер Использована обычная ссылка Добавьте кнопку типа web_app
Telegram.WebApp не найден Не загружен официальный скрипт Проверьте тег script
Нет имени пользователя Данные не переданы в этом контексте Не делайте поле обязательным
Сервер отклоняет запрос Ошибка проверки подписи Проверьте сортировку полей и токен
Белый экран Ошибка JavaScript Проверьте консоль и журналы сервера

Часто задаваемые вопросы

Можно ли подключить к Telegram готовый сайт?

Да, если сайт доступен по HTTPS и адаптирован под небольшие экраны. Для взаимодействия с Telegram потребуется подключить JavaScript API. Обычный десктопный сайт внутри Mini App может быть неудобен.

Можно ли создать WebApp без backend?

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

Можно ли доверять initDataUnsafe?

Нет. Значение удобно для отображения интерфейса, но не для подтверждения личности пользователя. Для защищенных операций отправляйте initData на сервер и проверяйте подпись.

Можно ли автоматически получить номер телефона?

Номер телефона не следует считать автоматически доступным. Пользователь должен явно согласиться передать его через предусмотренный Telegram сценарий.

Можно ли использовать React или Vue?

Да. Mini App является веб-приложением, поэтому можно применять современные frontend-фреймворки. Для простого подключения они не обязательны.

Заключение

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

Особое внимание уделите безопасности: не храните токен в браузере, не доверяйте initDataUnsafe и проверяйте initData на backend. Перед публикацией протестируйте приложение на разных устройствах и в разных темах Telegram.

Как в Телеграм