anvil-hosting/TELEGRAM_INTEGRATION.md

Telegram Mini App Integration - Implementation Summary

Changes Made

1. index.html Modifications

Added Telegram Web App SDK (Line 35)

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

Updated Content Security Policy (Line 6)

• Added https://telegram.org to script-src directive
• Allows loading Telegram SDK from official CDN

Added User Info Display in Navbar (Lines 86-93)

Two conditional displays:

• Telegram Mode: Shows user info 👤 @username (ID: 123456)
• Web Browser Mode: Shows 🌐 웹 브라우저

2. app.js Modifications

Added Telegram State (Lines 88-92)

telegram: {
  isAvailable: false,  // Whether running in Telegram environment
  user: null,          // User information object
  initData: null       // Validation data
}

Added telegram_id to config (Line 100)

config: {
  region: null,
  plan: null,
  os: null,
  payment: null,
  telegram_id: null  // NEW: Telegram user ID
}

Added init() Method (Lines 120-140)

• Detects Telegram Web App environment
• Initializes Telegram SDK (tg.ready(), tg.expand())
• Stores user information and init data
• Logs initialization status

Updated startLaunch() Method (Lines 227-229)

• Automatically includes telegram_id when creating server
• Only adds ID if user is authenticated via Telegram

Updated resetLauncher() Method (Line 281)

• Resets telegram_id along with other config values

Features

Backward Compatibility

• ✅ Works in regular web browsers without errors
• ✅ Gracefully degrades when Telegram SDK is unavailable
• ✅ All existing functionality preserved

Telegram Integration

• ✅ Auto-detects Telegram Mini App environment
• ✅ Displays user information in navbar
• ✅ Includes telegram_id in server creation payload
• ✅ Console logging for debugging

Security

• ✅ CSP updated to allow Telegram SDK
• ✅ Optional chaining prevents errors
• ✅ initData available for backend verification

Testing Scenarios

1. Web Browser Test

Expected:

• telegram.isAvailable = false
• Shows "🌐 웹 브라우저" badge
• Server creation works without telegram_id
• No console errors

2. Telegram Mini App Test

Expected:

• telegram.isAvailable = true
• Shows "👤 @username (ID: 123456)" badge
• Server creation includes telegram_id field
• Console logs show user info

Usage

For End Users

1. Open in Telegram: Access via bot inline button
2. Open in Browser: Direct URL access

For Developers

// Access Telegram data in console
console.log(window.Telegram?.WebApp?.initDataUnsafe);

// Check if running in Telegram
Alpine.store('telegram.isAvailable');

// Get user ID
Alpine.store('telegram.user.id');

API Integration

When backend receives server creation request, config object will include:

{
  "region": "Seoul",
  "plan": "Pro",
  "os": "Debian 12",
  "payment": "yearly",
  "telegram_id": 123456789  // Only present when launched from Telegram
}

Backend can use telegram_id to:

• Link server to Telegram user
• Send notifications via bot
• Verify user identity using initData

Notes

• Theme color integration is commented out (Line 131)
• Can be enabled if desired: document.body.style.backgroundColor = tg.backgroundColor;
• initData should be validated on backend for security