WebApp «Своё приложение» (miniapp)

miniapp — это «пустой» тип WebApp в Квесче, в который вы помещаете свой HTML/JavaScript-код. Это полностью кастомное мини-приложение Telegram/MAX, написанное под конкретную задачу, размещённое на инфраструктуре Квесчи и связанное с ботом через обратный callback.

Используйте, когда готовые cat_shop, cat_cafe, calendar не подходят: нужна нестандартная форма, конфигуратор, игра, опросник со сложной логикой, конструктор пиццы, тест с веткой вопросов, дашборд.

Когда выбирать miniapp

Задача	Решение
Каталог товаров	cat_shop
Меню кафе	cat_cafe
Запись на услуги	calendar
Конфигуратор продукта (выбор материала → цвета → размера → опций)	miniapp
Игра / квиз с очками и таймером	miniapp
Сложная анкета с условной логикой полей	miniapp
Калькулятор (ипотеки, ремонта, доставки)	miniapp
Личный кабинет с историей и графиками	miniapp

---

Часть 1. Концепция

Подписчик нажимает кнопку WebApp
   ↓
Открывается ваше HTML/JS приложение
   ↓
Клиент совершает действие
   ↓
Ваш код POST/GET в https://api.quescha.com/miniapp/callback
   (с объектом quescha — обязательно!)
   ↓
Бот получает данные → переменные сценария
   ↓
Текущий блок получает ответ webapp:miniapp
   ↓
Сценарий продолжается

---

Часть 2. Создание miniapp

Шаг 1. Откройте раздел WebApp

В конструкторе → Списки / WebApp → Вкладка WebApp → Создать → выберите тип «MiniApp».

Скриншот 1. Тип «MiniApp» в списке.

Шаг 2. Разместите HTML/JS код

Поле «Код приложения» — большой textarea (до 1 000 000 символов). Сюда положите весь код вашего приложения:

• HTML-разметку;
• CSS-стили (можно подключать внешние через <link>);
• JavaScript-логику;
• использование Telegram WebApp API (window.Telegram.WebApp) или MAX (window.maxWebApp).

Квесча сохранит код и сделает его доступным по уникальной ссылке.

Скриншот 2. Размещение HTML/JS в редакторе.

Шаг 3. Токен бота (для MAX)

Мессенджер	Токен
Telegram — запуск из inline-кнопок WebApp	Необязателен
Telegram — запуск из Menu Button	Обязателен
Telegram — запуск как Mini App через ссылку	Обязателен
MAX	Обязателен

Вставьте токен бота в раздел «Токен бота для привязки к приложению».

Шаг 4. Сохраните

Кнопка «Сохранить приложение» → получите ссылку приложения. Эту ссылку можно вставить в:

• кнопку типа «Ссылка» в блоке;
• настройки бота в @BotFather → Bot Settings → Menu Button;
• настройки @BotFather → Bot Settings → Configure Mini App (запуск как Mini App).

---

Часть 3. Возврат данных в бот

Способ 1. Callback на api.quescha.com

В вашем JS-коде сделайте POST/GET на https://api.quescha.com/miniapp/callback с полями данных + обязательным объектом quescha:

var url = 'https://api.quescha.com/miniapp/callback';
var payloads = {
  name: 'Иван',             // ваши данные → переменная #{name}
  birthday: '01.01.2000',   // → переменная #{birthday}
  data1: 'Строка',          // → переменная #{data1}
  data2: [1, 2, 3, 4, 5],   // → переменная #{data2} (массив)
  quescha: quescha          // ОБЯЗАТЕЛЬНО — служебные данные сессии
};

fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payloads),
});

Что такое объект quescha

Это служебные данные, которые Квесча инжектирует в окно WebApp при открытии. Содержит идентификатор сессии клиента — без него бот не узнает, кому относятся ваши данные.

Доступен в окне как переменная quescha (или window.quescha). Просто скопируйте его в payloads.

Что приходит в бот

• Все поля payloads (кроме quescha) становятся переменными сценария: #{name}, #{birthday}, #{data1}, #{data2}.
• Массивы и объекты сохраняются как есть — обращайтесь через #{data2|1}, #{data2|last}.
• Текущий блок получает ответ webapp:miniapp — используйте в условных переходах.

Способ 2. Через вебхук

Для получения данных из бота в приложение — приложение само забирает данные у бота через «Обмен данными → Ожидание данных»:

1. В сценарии действий блока добавьте действие HTTP-запросы → «Ожидание данных» → получите URL вебхука.
2. В вашем miniapp сделайте запрос к этому URL.
3. В сценарии действий через JS код сформируйте ответ, поместите в #{_response} — вернётся приложению.

Этот способ удобен, если приложение не отправляет данные в бот, а читает из бота.

---

Часть 4. Обработка webapp:miniapp в сценарии

В первом блоке после нажатия кнопки miniapp поставьте условие перехода или сценарий действий по ответу webapp:miniapp:

Блок «Возврат из miniapp»
  Условие перехода: '[Answer]' = 'webapp:miniapp' → переход на «Обработка»

Если miniapp запускается из меню Telegram или через прямую ссылку Mini App — клиент может быть в любом блоке. На каждом блоке-вопросе настройте проверку [Answer] = webapp:miniapp → переход на блок обработки.

Скриншот 3. Универсальная обработка возврата.

---

Часть 5. Типовые сценарии

Сценарий 1. Конфигуратор пиццы

miniapp:
  - Интерфейс выбора: тесто, размер, начинки, соус
  - При нажатии «Заказать» → POST на /miniapp/callback:
      {
        dough: "тонкое",
        size: 32,
        toppings: ["сыр", "пепперони"],
        sauce: "томатный",
        total: 850,
        quescha: quescha
      }

Бот:
  Блок «Возврат из конфигуратора»
    Условие: [Answer] = webapp:miniapp
    Сценарий действий «До»:
      - Действие «Платежи» → ссылка на оплату 850 ₽
    Сообщение: «Ваша пицца: #{dough} #{size}см, #{toppings}
                Сумма: #{total} ₽»
    Кнопка «Оплатить» → #{pay_link}

Сценарий 2. Калькулятор стоимости ремонта

miniapp:
  - Поля: площадь, тип ремонта, материалы
  - Расчёт цены на лету
  - При «Оставить заявку» → POST:
      { sq: 50, type: "капитальный", materials: "премиум", price: 1500000, quescha: quescha }

Бот:
  - Сохранение в список «Заявки»
  - Уведомление менеджеру
  - Сообщение клиенту: «Стоимость: #{price} ₽. Менеджер свяжется.»

Сценарий 3. Игра «Колесо фортуны»

miniapp:
  - Анимация колеса
  - При остановке → POST:
      { prize: "промокод-20", spin_id: "abc123", quescha: quescha }

Бот:
  - Проверка через [список](spiski.md) "История розыгрышей" по spin_id
  - Если уже играл → «Извини, по одному выигрышу в день»
  - Если первый раз → выдать промокод #{prize}, записать в список

Сценарий 4. Личный кабинет

miniapp (через вебхук):
  - Клиент открывает кабинет → приложение запрашивает данные через вебхук
  - Бот в сценарии действий формирует JSON:
      { name: "Иван", orders: [...], balance: 12500 }
  - Помещает в #{_response} → возвращается приложению
  - Приложение рендерит интерфейс
  
  Клиент может также отправить действия обратно через callback.

Сценарий 5. Опрос со сложной логикой

Сложный quiz с условными переходами между вопросами, таймером, медиа. Все ответы собираются в массив и одним пакетом отправляются в бот.

---

Часть 6. Архитектура

Принцип 1. Объект quescha — обязателен

Без него Квесча не сможет связать данные с клиентом. Никогда не теряйте его при сборке payloads.

Принцип 2. Имена полей — это имена переменных

Поле total в payloads = переменная #{total} в сценарии. Используйте осмысленные имена и не конфликтуйте с системными (media_type, payment_result и т.д.).

Принцип 3. Отправка — один раз за сессию

Не делайте множественные POST по каждому действию пользователя. Один финальный POST = одна переменная-набор данных. Бот не любит лавину callback.

Принцип 4. Тестируйте код локально

HTML/JS код большой — отлаживайте в браузере. Эмулируйте quescha объект тестовыми данными. Только когда работает — копируйте в Квесчу.

Принцип 5. Используйте Telegram/MAX SDK

В вашем коде подключите официальные скрипты:

Telegram

<script src="https://telegram.org/js/telegram-web-app.js"></script>

Это даст доступ к window.Telegram.WebApp — нативной кнопке закрытия, теме оформления, биометрии, MainButton.

МАКС

<script src="https://st.max.ru/js/max-web-app.js"></script>

Это даст доступ к window.WebApp — нативной кнопке закрытия, теме оформления, биометрии, MainButton.

Принцип 6. Стилизуйте под бота

Используйте Telegram.WebApp.themeParams или CSS-переменные мессенджера, чтобы приложение выглядело родным. Не делайте белое окно в тёмной теме Telegram.

Принцип 7. Создавайте код через нейросеть

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

---

Часть 7. Сравнение с другими WebApp

	miniapp	cat_shop	cat_cafe	calendar
Готовый UI	Нет (пишете сами)	✓	✓	✓
Кастомизация	Полная	Ограниченная	Ограниченная	Ограниченная
Время разработки	Часы-дни	Минуты	Минуты	Минуты
Подходит для	Уникальных задач	Магазина	Кафе	Записи
Возврат данных	POST callback	Автоматом	Автоматом	Автоматом
Ответ блока	webapp:miniapp	webapp:catalog	webapp:catalog	webapp:calendar
Нужен код	✓	✗	✗	✗

---

Полезные ссылки

• Telegram Mini Apps — документация
• MAX Mini Apps — документация

---

Частые ошибки

• #{name} пустая — забыли передать поле name в payloads. Проверьте структуру POST.
• Бот не получает данные — отсутствует объект quescha в payloads. Это критично.
• CORS-ошибка при POST — используйте mode: 'cors' в fetch или серверную часть для прокси.
• Приложение не открывается из кнопки — неправильная ссылка приложения или не указан токен (для MAX).
• webapp:miniapp не приходит — данные не дошли до Квесчи. Проверьте URL https://api.quescha.com/miniapp/callback (HTTPS, без www).
• Дубликат callback — приложение шлёт POST несколько раз. Добавьте флаг sent = true после первого вызова.
• Mini App запускается, но окно белое — ошибка JS в коде. Откройте через Telegram Web → DevTools → проверьте консоль.

---

Что дальше

• WebApp обзор — все типы WebApp в Квесче.
• WebApp Магазин (cat_shop) — если задача похожа на каталог.
• WebApp Кафе (cat_cafe) — общепит.
• WebApp Календарь (calendar) — запись.
• HTTP-запросы — для обмена данными через вебхук.
• JS код — постобработка данных miniapp в боте.
• Платежи — приём оплат после miniapp.