Що насправді таке Telegram Mini App - і коли я б її збирала

Telegram Mini App - це не бот з гарнішими кнопками. Це справжній вебзастосунок - HTML, CSS, JavaScript - який Telegram відкриває панеллю всередині чату. Користувач не виходить із месенджера, не йде в app store і часто не вводить пароль. Це і є продукт: задача закривається там, де вже йде розмова.

Досі кажуть «Telegram Web App» - так називалось раніше. Те саме: HTTPS-сторінка плюс WebApp SDK плюс бот, який її відкриває. Якщо вставити маркетинг-сайт у цей webview - це не Mini App. Це стиснутий сайт із шапкою Telegram. Ця стаття - як я б реально ставилась до цієї поверхні.

1. Mini App, бот, сайт і застосунок зі store

Ці чотири поверхні закривають різні задачі. Якщо їх змішати - отримаєте бота, який удає магазин, або Mini App, яка хоче вийти в Google.

• Бот: інтерфейс чату. Добре для команд, сповіщень, разової оплати, «надішли цей PDF». Погано для каталогів, календарів і багатокрокових форм.
• Сайт: публічний URL, SEO, посилання, якими діляться, десктоп. Двері для тих, хто ще не у вашому Telegram.
• Застосунок зі store: встановлення, push, офлайн, податок Apple/Google. Пасує, коли потрібні права ОС. Не пасує, коли задача - «записатись за 40 секунд».
• Mini App: повний інтерфейс усередині Telegram, ідентичність із чату, оплата через Stars або інвойси, оновлення без модерації store. Продукт живе там, де клієнт уже з вами переписується.

2. Як це насправді зібрано

Три частини, не одна. Пропустіть будь-яку - отримаєте демо, не продукт.

• Бот. Він тримає кнопку меню, KeyboardButton web_app, inline-кнопку або пряме посилання (t.me/bot/app). Без бота панель нікому відкривати.
• HTTPS-вебзастосунок. Telegram вантажить ваш URL у webview. Next.js на Vercel (чи будь-який HTTPS-хост) підходить. HTTP і localhost-трюки - лише для розробки.
• WebApp SDK (`window.Telegram.WebApp`). Тема, viewport, MainButton, BackButton, haptic, CloudStorage, інвойс, об’єкт користувача. Без нього ви вгадуєте CSS в темряві.

3. Ідентичність: initData - це не екран входу

Коли Telegram відкриває сторінку, він додає підписаний `initData`: id користувача, ім’я, мова, необов’язковий query, хеш. Це і є сесія. Користувач уже довів, що володіє акаунтом, бо він усередині застосунку. Не прикручуйте «увійти з email», якщо не треба прив’язати наявний кабінет.

Ніколи не довіряйте `initData` у браузері. Будь-хто відкриє DevTools і підробить об’єкт користувача. Сервер має перевірити HMAC-хеш токеном бота, що `auth_date` свіжий, і тоді видати свою session cookie або JWT. Без цього кроку у вас немає автентифікації. У вас бутафорія.

4. UX, який не виглядає як сайт у шухляді

У Telegram уже є своя оболонка: ручка, safe area, тема світла/темна. Ідіть проти цього - застосунок чужий. Візьміть як є - здається нативним.

• MainButton - головна дія: оплатити, записатись, надіслати. CSS-кнопка знизу сяде під індикатор home і виглядатиме як клон.
• BackButton для вкладених екранів. Свайп униз у Telegram закриває Mini App - не крадіть цей жест під «попередній крок».
• Читайте `themeParams` і `colorScheme`. Зашита біла сторінка в темному Telegram виглядає як баг.
• Viewport - це не `100vh`. Беріть `viewportStableHeight` і expand, коли потрібна повна панель. Тестуйте iOS і Android - вони не згодні.

5. Коли я б реально зібрала Mini App

Я б збирала Mini App, коли клієнт уже в Telegram - або буде, бо так цей бізнес говорить - і задача потребує справжнього інтерфейсу, а не ланцюжка повідомлень.

• Запис із календарем, не «відповісти датою». Магазини з фільтрами. Кабінети курсів. Калькулятори, що стають заявкою. Картки лояльності. Внутрішні інструменти для команди, яка вже живе в групі.
• Оплата, яка не повинна виходити з чату: Telegram Stars, інвойси або ваш наявний чекаут - відкритий із Mini App, підтверджений назад у боті.

6. Коли я б відмовилась

Mini App не замінює сайт. Вона не виходить у пошуку. Погано бути єдиними дверима, якщо половина покупців приходить із Google. Це також погане місце звалювати десктопну CRM.

• SEO, блог, публічний каталог, «про нас», вакансії - це сайт. Звідти дайте посилання на Mini App, якщо задача далі йде в чаті.
• Важка графіка, величезні таблиці, адмінка з кількома вікнами. Панель - поверхня під телефон. Справжню адмінку зробіть у вебі.
• Якщо єдина вимога - «чули, що Mini Apps у тренді», а аудиторії в Telegram немає - почніть із сайту і бота, який робить одну задачу.

7. Стек, з якого я б почала у 2026

Та сама дисципліна, що для MVP: один код, який потім може стати сайтом, нудна база, бот, який лише відчиняє двері й підтверджує оплату.

• Next.js + TypeScript + Tailwind для інтерфейсу. Один застосунок: роути Mini App і, якщо треба, публічний маркетинг-сайт.
• PostgreSQL як основне сховище. Користувачі за Telegram id. Redis - якщо потрібні rate limit або короткі чернетки.
• Невеликий бот (grammY або Telegraf) для Menu Button, інвойсів і повідомлень після оплати. Не ховайте бізнес-логіку лише в боті, якщо Mini App теж її потребує - спільний модуль.
• Перевіряйте initData на сервері на кожен привілейований запит. У webview не зберігайте секретів.

Mini App - це двері, не бренд

Ставтесь як до продуктової поверхні з контрактом: відкриватись швидко, виглядати як Telegram, доводити користувача на сервері, закрити одну задачу, надіслати квитанцію назад у чат. Якщо потрібні охоплення, SEO і історія для незнайомців - це все ще сайт. Якщо потрібна розмова плюс справжній інтерфейс - це Mini App. Друге я б зібрала, коли аудиторія вже в месенджері. Не зібрала б, бо стара назва «Web App» звучала дешевше за збірку в App Store.