Про Telegram WebApp у сценаріях

Telegram WebApp дозволяє відкривати веб-додатки безпосередньо в Telegram, що дозволяє створювати інтерактивні інтерфейси з повним доступом до веб-технологій та можливістю взаємодії з ботом.

Контекст і проблема

У багатьох сценаріях потрібно надати користувачам складні інтерфейси:

  • Форми з багатьма полями
  • Інтерактивні каталоги товарів
  • Ігрові інтерфейси
  • Складні налаштування

Telegram WebApp вирішує цю задачу, дозволяючи створювати повноцінні веб-додатки, які інтегруються з ботом та працюють безпосередньо в Telegram.

Основні концепції

Що таке Telegram WebApp

Telegram WebApp — це веб-додаток, який відкривається безпосередньо в Telegram через спеціальну кнопку. Він має доступ до Telegram WebApp API, що дозволяє взаємодіяти з ботом та отримувати дані користувача.

Налаштування через інлайн-клавіатуру

Для відкриття WebApp потрібно:

  1. Створити кнопку в інлайн-клавіатурі
  2. Вказати ActionType: "open-web-app" в JSON конфігурації
  3. Вказати URL WebApp в ActionBody
  4. Увімкнути опцію "Інлайн-клавіатура (тільки Telegram та віджет)"

Варіанти підходів

WebApp vs звичайний сайт

Telegram WebApp:

  • ✅ Плюси: Інтеграція з ботом, доступ до Telegram API, робота безпосередньо в Telegram
  • ❌ Мінуси: Працює тільки в Telegram, обмеження розміру вікна

Звичайний сайт:

  • ✅ Плюси: Працює скрізь, більше свободи дизайну
  • ❌ Мінуси: Немає інтеграції з ботом, потрібно відкривати браузер

Чому використовуємо WebApp: Для інтерактивних інтерфейсів, які потребують інтеграції з ботом, WebApp надає найкращі можливості та користувацький досвід.

Прийняті рішення

Обов'язковий HTTPS

WebApp повинен бути доступний через HTTPS. Це вимога Telegram для безпеки користувачів.

Адаптивний дизайн

WebApp повинен мати адаптивний дизайн для різних пристроїв (desktop та mobile), оскільки Telegram працює на різних платформах.

Telegram WebApp API

Для повної інтеграції з ботом рекомендовано використовувати Telegram WebApp API, який дозволяє:

  • Відправляти дані назад у бот
  • Закривати WebApp
  • Отримувати дані користувача
  • Керувати інтерфейсом WebApp

Наслідки для користувачів і імплементації

Для інтеграторів

При використанні Telegram WebApp важливо:

  1. Налаштувати HTTPS — WebApp повинен бути доступний через HTTPS
  2. Створити адаптивний дизайн — для різних пристроїв та розмірів екрану
  3. Використати Telegram WebApp API — для інтеграції з ботом
  4. Налаштувати кнопку — використати інлайн-клавіатуру з ActionType: "open-web-app"

Типові помилки

Помилка: WebApp не відкривається
Проблема: Не вказано ActionType: "open-web-app" або не увімкнено інлайн-клавіатуру
Рішення: Перевірити JSON конфігурацію кнопки та налаштування інлайн-клавіатури

Помилка: WebApp не працює через HTTP
Проблема: Telegram вимагає HTTPS для WebApp
Рішення: Налаштувати HTTPS для WebApp

Помилка: WebApp не адаптується під мобільні пристрої
Проблема: Відсутній адаптивний дизайн
Рішення: Додати media queries та адаптивні стилі

Обмеження

  • WebApp працює тільки в Telegram (не працює в Widget)
  • Сайт повинен бути доступний через HTTPS
  • Розмір WebApp обмежений розмірами вікна Telegram
  • Деякі функції браузера можуть бути обмежені

Приклади використання

JSON конфігурація кнопки

{
  "ActionType": "open-web-app",
  "ActionBody": "https://www.example.com/webapp"
}

Використання Telegram WebApp API

// Перевірка, чи сайт відкрито в Telegram
if (window.Telegram && window.Telegram.WebApp) {
  const tg = window.Telegram.WebApp;
  
  // Відправка даних назад у бот
  tg.sendData(JSON.stringify({action: 'purchase', item: 'product123'}));
  
  // Закриття WebApp
  tg.close();
}

Пов'язані документи