11 - Telegram Mini App Integration¶

Dokument: Telegram TWA-Integration Stand: 28.02.2026 Scope: TelegramProvider, Bot-Webhook, Plattform-Anpassungen Status: Audit-ready

1. Übersicht¶

Die ChainBETs-App läuft als Telegram Mini App (TWA) innerhalb des Telegram WebViews. Die gleiche Next.js-App wird verwendet - mit plattformspezifischen Anpassungen für Auth, UI und Navigation.

Architektur¶

Telegram App
  └─ WebView (TWA)
       └─ ChainBETs Next.js App
            ├─ Telegram SDK (telegram-web-app.js)
            ├─ TelegramProvider (Context)
            └─ Web3Auth (Redirect-Mode auf Mobile)

2. Telegram SDK Integration¶

2.1 SDK-Einbindung¶

Datei: app/layout.tsx

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

Das SDK wird global im Root Layout geladen und stellt window.Telegram.WebApp bereit.

2.2 TelegramProvider¶

Datei: app/providers/TelegramProvider.tsx

Erkennung:

const isTelegram = !!window.Telegram?.WebApp?.initData;
// initData ist nur vorhanden wenn in Telegram WebView

Context-Werte: | Wert | Typ | Beschreibung | |---|---|---| | isTelegram | boolean | In Telegram WebView | | isTelegramMobile | boolean | Android/iOS (OAuth-Einschränkungen) | | telegramUser | TelegramUser | Telegram-Benutzerdaten | | startParam | string | Affiliate-Ref aus /start-Kommando |

TelegramUser:

{ id: number, firstName: string, lastName?: string, username?: string, languageCode?: string }

2.3 Plattform-Erkennung¶

Platform-String	Typ	Besonderheiten
`android`, `android_x`	Mobile	Popups blockiert, Redirect-Auth
`ios`	Mobile	Popups blockiert, Redirect-Auth
`tdesktop`	Desktop	Popups funktionieren
`macos`	Desktop	Popups funktionieren
`web`, `weba`	Browser	Telegram Web App

2.4 Initialisierung¶

Bei Telegram-Erkennung:

tgWebApp.expand();   // Viewport auf volle Höhe
tgWebApp.ready();    // Telegram informieren: App bereit

3. Authentifizierung in Telegram¶

Methode	Mobile	Desktop
Google OAuth	Redirect	Redirect
Apple OAuth	Redirect	Redirect
E-Mail (Passwordless)	Redirect	Redirect
Web3Auth Modal	Nicht verfügbar	Nicht verfügbar

Grund für Redirect: Telegram Mobile blockiert Popups. Daher wird uxMode: "redirect" verwendet.

3.2 Web3Auth Konfiguration (Telegram Mobile)¶

{
  web3AuthNetwork: SAPPHIRE_DEVNET,
  uxMode: "redirect",
  redirectUrl: currentPageUrl, // z.B. https://app.chainbets.win/en/play
  sessionTime: 604800 // 7 Tage
}

3.3 Redirect-Flow¶

1. User klickt Login
2. Web3Auth redirect zu OAuth Provider
3. Provider authentifiziert
4. Redirect zurück zur App
5. visibilitychange Event → Session prüfen
6. loadUserData() + completeLogin()

3.4 Visibility-Change-Handler¶

Spezialbehandlung für mobile Redirects:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible" && !isConnected) {
    // Session aus SharedStorage prüfen
    // Bei Erfolg: Login abschließen
  }
});

4. Affiliate-Tracking¶

4.1 Flow¶

1. User teilt Telegram-Link: t.me/ChainBETsBot?start=refCode
2. User klickt Link → Telegram öffnet Bot
3. Bot zeigt Willkommensnachricht
4. User klickt "Jetzt spielen" → Mini App öffnet mit startapp=refCode
5. TelegramProvider extrahiert startParam
6. startParam wird als "chainbets_ref" in localStorage gespeichert
7. Bei Login: ref wird an /api/player/init gesendet
8. Backend bindet Affiliate (Erst-Login)

4.2 Bot-Webhook¶

Endpoint: POST /api/telegram/webhook Datei: pages/api/telegram/webhook.ts

Konfiguration: | Parameter | Beschreibung | |---|---| | BOT_TOKEN | WATCHDOG_TELEGRAM_BOT_TOKEN | | BOT_USERNAME | NEXT_PUBLIC_TELEGRAM_BOT_USERNAME (Default: ChainBETsBot) | | WEBHOOK_SECRET | Optional, Header-Validierung |

Sicherheit:

Header: x-telegram-bot-api-secret-token
Vergleich mit TELEGRAM_WEBHOOK_SECRET

/start-Kommando-Handler:

// Nachricht:
"Willkommen bei ChainBETs, {firstName}!
Die fairste Blockchain-Lotterie auf Arbitrum.
100% transparent, blockchain-verifizierte Ergebnisse."

// Inline Keyboard:
{ text: "🎰 Jetzt spielen", web_app: { url: miniAppUrl + "?startapp=" + refCode } }

Response: Immer 200 OK (Telegram-Anforderung)

5. UI-Anpassungen für Telegram¶

5.1 CSP-Header¶

Content-Security-Policy: frame-ancestors 'self' https://web.telegram.org https://*.telegram.org

5.2 Device-Erkennung¶

Im DeviceProvider:

// Telegram Mobile → isMobile = true
// Telegram Desktop → isDesktop = false, isTelegram = true

5.3 Layout-Unterschiede¶

Feature	Web	Telegram
Navigation	Full Navbar	Vereinfacht
Viewport	Standard	`tgWebApp.expand()`
Back-Button	Browser	Telegram native
PWA-Banner	Ja	Nein
Login-Modal	Web3Auth Modal	Direkte Buttons (Google/Apple/Email)

6. Umgebungsvariablen¶

Variable	Beschreibung
`WATCHDOG_TELEGRAM_BOT_TOKEN`	Bot API Token
`NEXT_PUBLIC_TELEGRAM_BOT_USERNAME`	Bot Username (für Mini App URL)
`TELEGRAM_WEBHOOK_SECRET`	Webhook-Signaturgeheimnis

Weiterführende Dokumente: - 02 - Authentifizierung - 04 - State Management - 15 - Konfiguration