Telegram Mini App API: що вміє і як на ньому будувати

Telegram Mini App API — один із найбільш недооцінених інструментів в екосистемі Telegram. Більшість людей знає, що Міні-застосунки існують — це невеликі веб-додатки, які відкриваються прямо всередині Telegram, не виходячи з чату. Але насправді мало хто з розробників розуміє, що цей API вміє, а що — ні.

Якщо ви хочете щось побудувати поверх Telegram — інструмент для продажів, CRM-віджет, гру чи платіжний флоу — ось що варто знати ще до того, як ви напишете перший рядок коду.

Що таке Telegram Mini App API?

Telegram Mini Apps (їх ще називають TWA — Telegram Web Apps) — це веб-застосунки, які працюють всередині Telegram через вбудований браузер. Telegram Mini App API — це JavaScript-інтерфейс, що дозволяє вашому веб-додатку «спілкуватися» з Telegram: зчитувати дані користувача, керувати кнопками, обробляти платежі, контролювати інтерфейс тощо.

Уявіть це як міст. Ваш веб-додаток живе на вашому сервері. Telegram відображає його всередині чату або бота. API — це канал зв'язку між двома сторонами в реальному часі.

Доступ до нього здійснюється через глобальний об'єкт window.Telegram.WebApp, який Telegram автоматично впроваджує в контекст браузера при відкритті Міні-застосунку. Жодних npm-пакетів не потрібно — він просто є.

Що насправді дозволяє робити Telegram Mini App API

Ось чесний огляд доступних можливостей:

Автентифікація користувачів (без паролів)

Коли користувач відкриває ваш Міні-застосунок, Telegram передає рядок initData з його ID, юзернеймом, мовою та хешем, який ви можете перевірити на бекенді. Це фактично безшовна автентифікація — жодних екранів входу, жодного OAuth. Користувач уже автентифікований самим фактом присутності в Telegram.

Ви зобов'язані перевіряти хеш на стороні сервера за допомогою токена вашого бота. Ніколи не довіряйте initData, отриманому лише від клієнта.

Елементи керування UI

API надає хуки до нативних UI-елементів Telegram:

• MainButton — велика кнопка внизу екрана. Ви керуєте підписом, кольором, станом завантаження та обробником кліку.

• BackButton — відображає нативну стрілку «назад» у заголовку. Зручно для багатокрокових флоуів.

• HapticFeedback — вібрація на мобільному. Дрібниця, але суттєво впливає на UX.

• expand() — примусово відкриває Міні-застосунок у повноекранному режимі.

• close() — програмно закриває Міні-застосунок.

Платежі

Ви можете запустити нативний платіжний флоу Telegram прямо з Міні-застосунку через openInvoice(). Він інтегрується з Telegram Stars (внутрішньою валютою) та підтримуваними платіжними провайдерами. Користувач платить, не виходячи з додатку.

Сканер QR-кодів

API надає доступ до QR-сканера, який використовує камеру пристрою. Ваш застосунок може запросити сканування і отримати декодований рядок. Підходить для онбордингових флоуів, валідації квитків або — як це реалізовано в CRMChat — захоплення потенційних клієнтів на конференціях через сканування їхніх Telegram QR-кодів.

Хмарне сховище

Ви отримуєте легке сховище типу «ключ-значення» (до 1024 елементів), яке зберігається для кожного користувача окремо в межах бота. Це не замінник бази даних — але зручно для збереження налаштувань або невеликого стану без побудови бекендного шару сесій.

Біометрична автентифікація

Новіші версії API підтримують запит автентифікації через відбиток пальця або Face ID. Ще впроваджується на різних платформах, але варто знати, що така можливість є.

Що API НЕ дозволяє робити

Саме тут багато розробників стикаються з несподіванками. Знайте обмеження ще до проєктування архітектури.

• Читати повідомлення. Міні-застосунки не мають доступу до історії чатів, контактів або будь-якого вмісту повідомлень. Це жорстка стіна.

• Надсилати повідомлення від імені користувача. Ви можете відправити повідомлення через свого бота (за дозволом користувача), але сам Міні-застосунок не може писати в чати.

• Отримувати списки учасників груп. Для цього потрібен окремий бот або зовсім інший підхід на основі парсингу.

• Запускати фонові процеси. Міні-застосунки виконуються лише поки відкриті. Жодної фонової синхронізації, жодної push-логіки з боку веб-застосунку (для цього використовуйте бота).

• Отримувати доступ до файлової системи або камери напряму (крім QR-сканера). Діють стандартні правила пісочниці браузера.

Як Міні-застосунки та боти працюють разом

Міні-застосунки не замінюють ботів — вони їх розширюють. Типова архітектура виглядає так:

1. Ваш Telegram-бот надсилає повідомлення з кнопкою, яка відкриває URL Міні-застосунку.

2. Користувач натискає на неї. Telegram відкриває ваш веб-застосунок у своєму браузері.

3. Ваш застосунок зчитує initData, верифікує його на сервері та автентифікує користувача.

4. Користувач виконує дію (заповнює форму, робить покупку, налаштовує щось).

5. Ваш застосунок викликає sendData() або звертається до вашого API — бот обробляє результат і надсилає наступне повідомлення.

Бот відповідає за повідомлення. Міні-застосунок — за розширений UI. Кожен робить те, в чому найсильніший.

Якщо ви будуєте кастомні Telegram-воронки, які виходять за межі готових інструментів, CRMChat API дозволяє підключити взаємодії в Міні-застосунку безпосередньо до CRM-пайплайну в Telegram — пов'язуючи дії користувача з контактами, стадіями угод і послідовностями аутрічу.

Реальні кейси, які варто будувати

Без зайвої теорії — ось де Міні-застосунки справді сяють для команд продажів та аутрічу:

• Форми лідогенерації — вбудуйте кваліфікаційний опитувальник у Міні-застосунок. Коли потенційний клієнт пише вашому боту, відкрийте форму. Ви отримуєте структуровані дані; вони — зручний досвід.

• Запис на демо — вбудуйте планувальник на кшталт Calendly прямо в Telegram. Жодних редиректів, жодної втрати контексту.

• Онбордингові флоуи — багатокрокові майстри налаштування з індикаторами прогресу. Набагато краще, ніж бот, який ставить питання по одному.

• Дашборди угод — покажіть менеджеру з продажів його пайплайн прямо в Telegram без переходу до десктопної CRM. Добре поєднується з пайплайном продажів на базі Telegram.

• Платіжні флоуи — стягуйте оплату за послуги, підписки або квитки на заходи, не виходячи з чату.

Безпека: не пропускайте цей розділ

Найпоширеніша помилка при розробці Міні-застосунків — довіряти даним на стороні клієнта. Будь-хто може підмінити initData до того, як ваш застосунок його прочитає.

Завжди перевіряйте на сервері за допомогою HMAC-SHA256 з токеном вашого бота. Документація Telegram детально описує точний алгоритм. Якщо хеш не збігається — відхиляйте запит без жодних виключень.

Крім цього, ставтеся до свого Міні-застосунку як до будь-якого іншого веб-застосунку: лише HTTPS, санітизація введених даних, ніяких секретів на стороні клієнта. Telegram-контейнер не додає безпеки — він додає зручності. Відповідальність залишається на вас. Детальніше про специфіку безпеки Міні-застосунків читайте в цьому розборі.

Як почати: швидкий старт

Для першого Міні-застосунку не потрібен складний стек. Мінімальне налаштування:

1. Створіть бота через @BotFather і отримайте токен.

2. Зробіть будь-який веб-застосунок (React, Vue, чистий HTML — не важливо) і розгорніть його на HTTPS.

3. У BotFather скористайтеся /newapp або налаштуйте URL кнопки меню, що вказує на ваш застосунок.

4. Додайте скрипт Telegram Web App: <script src="https://telegram.org/js/telegram-web-app.js"></script>

5. Зверніться до window.Telegram.WebApp і починайте будувати.

Це справді все, що потрібно для робочого прототипу. API добре задокументований в офіційній документації Telegram — витратьте 30 хвилин на її читання перед стартом, і заощадите години розгубленості пізніше.

Підсумок

Telegram Mini App API — потужний інструмент, якщо використовувати його за призначенням: розширений UI, безшовна автентифікація, платежі та передача дій користувача до вашого бота. Це не замінник бекенд-логіки і не спосіб обійти модель конфіденційності Telegram.

Будуйте Міні-застосунок як фронтенд-шар, залишайте бота відповідальним за повідомлення, і з'єднуйте їх через надійний бекенд. Це архітектура, яка масштабується — і яка не підкидає неприємних сюрпризів через півроку розробки.

Якщо ваш кейс — продажі в Telegram зокрема, CRMChat вже надає інфраструктуру для CRM, послідовностей аутрічу та захоплення лідів — щоб ви могли будувати досвід у Міні-застосунку поверх готового пайплайну, не винаходячи велосипед.