# Про 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 конфігурація кнопки

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

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

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

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

- **Reference:** [Telegram WebApp Documentation](https://core.telegram.org/bots/webapps) — офіційна документація Telegram про WebApp
- **Explanation:** [Інлайн-клавіатура](/uk/scenariodialog/explanation/inline-keyboard.md) — налаштування інлайн-клавіатури для WebApp