Telegram Mini App to aplikacja webowa otwierana w Telegramie, gdy użytkownik jest już zalogowany i znajduje się we właściwym czacie. Na tym polega jej obietnica: bez nowego konta, pobierania i resetowania hasła. Buduję ją jak każdy produkcyjny produkt webowy — Next.js i TypeScript po stronie frontendu, Node.js po stronie backendu — plus kilka reguł obowiązujących wyłącznie w Telegramie. Ostatni dostarczony przeze mnie projekt, objęty NDA, był fintechową Web App i Mini App z kartami wirtualnymi i fizycznymi, opartą na Next.js, Express i MongoDB.
Zaczyna się od bota. BotFather tworzy bota i Mini App. Użytkownik może ją otworzyć przyciskiem menu, przyciskiem klawiatury inline albo bezpośrednim linkiem t.me z parametrem startapp — w ten sposób przekazuję kod polecający lub kieruję do konkretnego ekranu. Aplikacja jest serwowana przez HTTPS ze zwykłego hostingu; podczas pracy tunel wskazuje Telegramowi localhost, więc testuję na prawdziwym telefonie, nie tylko w przeglądarce na komputerze.
Na uwierzytelnianiu nigdy nie oszczędzam. Telegram przekazuje aplikacji initData — identyfikator i nazwę użytkownika, auth_date oraz hash. initDataUnsafe dokładnie na to wskazuje: nadaje się do wyświetlenia nazwy, ale nigdy do obdarzenia zaufaniem. Backend weryfikuje surowe initData podpisem HMAC pochodzącym z tokenu bota, sprawdza aktualność auth_date i dopiero wtedy wystawia własną sesję. Token bota nigdy nie opuszcza serwera. W produkcie fintechowym ta jedna kontrola decyduje o różnicy między „zalogowano przez Telegram” a „każdy z devtools może podać się za dowolną osobę”.
Mini App powinna potem sprawiać wrażenie natywnej, a nie strony wklejonej do webview. Odczytuję themeParams i zmienne CSS Telegrama, aby motyw jasny lub ciemny odpowiadał aplikacji użytkownika. Korzystam z MainButton i BackButton zamiast rysować własne przyciski, dodaję haptyczne potwierdzenie ważnych działań i uwzględniam viewport oraz safe area, żeby nic nie chowało się pod nagłówkiem ani wskaźnikiem ekranu głównego. Mobile-first nie jest tu hasłem — większość sesji odbywa się na telefonie, obsługiwanym jednym kciukiem.
Bot i Mini App uzupełniają się. Bot wysyła powiadomienia, potwierdzenia i potwierdzenia płatności; Mini App obsługuje ekrany z formularzem, listą lub checkoutem. Webhooki trafiają do backendu Node.js, który pozostaje jedynym źródłem prawdy o płatnościach i stanie — klient pyta, ale nie decyduje. Za dobra cyfrowe w Telegramie płaci się Stars, a towary fizyczne i usługi mogą obsługiwać operatorzy płatności. Ustalam to z klientem na początku, bo ten wybór kształtuje cały przepływ.
Nie akceptuję zaufania do initDataUnsafe, wciskania desktopowej strony do webview, checkoutu działającego wyłącznie na frontendzie ani Mini App bez wersji webowej, jeśli firma potrzebuje też SEO lub wewnętrznego panelu. Jeśli chcesz uruchomić produkt w Telegramie, wyślij mi jedną czynność, którą użytkownik ma wykonać na czacie. Odpowiem schematem bota, ekranami Mini App i tym, co zostaje na serwerze.
Daj kolejnemu produktowi kogoś, kto zostanie.
Chcesz zacząć? Napisz do mnie — mogę rozpocząć od razu i zostać na dłużej. Długoterminowa współpraca, nie przekazanie projektu po dwóch tygodniach. Omówmy projekt, wymagania i najlepszy sposób realizacji.