Tracking Telegram Mini Apps (TMA) & WebApps

What are Telegram Mini Apps (TMA)?

Telegram Mini Apps (WebApps) allow you to run full web applications, such as stores, casinos, or games, directly inside Telegram. Unlike standard bots, TMAs require a specific tracking approach to bridge the gap between the Telegram chat and your web application.

Connecting Your TMA to GramPixel

To properly track users moving from your ads → to your bot → into your Mini App, you must pass the tracking data through the Telegram Menu Button.

1. Connect your bot to GramPixel (see "Connecting Your First Telegram Bot").
2. In Telegram, open @BotFather and select your bot.
3. Navigate to Bot Settings → Menu Button → Configure menu button.
4. Enter the URL of your web application. CRITICAL: You must use a GramPixel Tracking Link or append our tracking parameters to your URL. This allows GramPixel to pass the user's session_id into your app.

Tracking Internal Events (Purchases, Registrations)

Once the user is inside your TMA, you can track their actions using the GramPixel REST API or our JavaScript Snippet.

1. Capture the tg_user_id from the Telegram WebApp object (window.Telegram.WebApp.initDataUnsafe.user.id).
2. When a user makes a purchase or completes a registration, send a POST request to the GramPixel Custom Events API (/v1/events/ingest).
3. Include the telegram_id and the event_name (e.g., "Purchase").

GramPixel will automatically match this internal event back to the original Facebook or TikTok ad click that brought the user to your bot.