All guides

Mini App Integration Guide

Integrate rewarded video with HTML, Next.js (TypeScript) or React.

01Register and find your integration code

Open Publishers → My Mini Apps and register your app with its direct Telegram Mini App link, bot username and numeric bot ID. Never provide a bot token. A direct link cannot register the same Mini App twice. The bot identity is checked against Telegram.

After approval, open your Mini App detail page to copy its App Code, rewarded Block ID and framework-specific HTML, Next.js (TypeScript) or React snippet. Load Telegram's Web App script and the TELEMONIX SDK, initialize TelemonixAds with appCode and blockId, and call show() from a voluntary watch-ad button.

<script src="https://telegram.org/js/telegram-web-app.js"></script>
<script src="https://telemonix.com/sdk/telemonix-ads.js"></script>
<script>
  const ad = TelemonixAds.init({
    appCode: "YOUR_APP_CODE",
    blockId: "YOUR_BLOCK_ID",
  });
  async function showAd() {
    const result = await ad.show();
    if (result.completed) {
      // The user watched the full ad: give your in-app reward here.
    } else if (result.noAds) {
      // No ad available right now.
    }
  }
</script>

02Completion and earnings

Give an in-app reward only when result.completed is true. A click, early close or partial watch is not completed playback. The platform separately verifies completed delivery before crediting publisher earnings; a browser callback alone is not proof of a payment.

Valid settled Mini App earnings automatically contribute to your withdrawable publisher balance. Mini App reports remain separate from channel reports. Preview and Lab activity do not create real earnings.

03Test and troubleshoot

Open your app inside Telegram through its registered bot to test. A normal browser or launch through a different bot cannot authorize ad playback. INVALID_LAUNCH means the registered Telegram launch could not be verified.

If TelemonixAds is undefined, wait for the SDK script to load before calling it; Next.js ad buttons must run in a client component. If result.noAds is true, no ad is available now: show a neutral unavailable state and allow another voluntary attempt later. Read result.error for other failures; do not give a reward for an error.

04Declined apps

Read the numbered Mini App Policy and the decline reason, fix the issue and use Re-apply on the existing app with the same bot ID. Re-application goes through review again; it is not automatic approval.