Integrate Claimr widget into a Telegram mini app

You can run the Claimr widget inside a Telegram Mini App. In Telegram mode, the widget reads the Mini App context and signs the user in with their Telegram account automatically, so they never see a login screen. In this tutorial, you will:

Configure the campaign to sign users in with Telegram.
Load Telegram’s Mini App script and the Claimr widget in Telegram mode.
Set up the Mini App window so the widget is comfortable to use.

The code examples use React. For other frameworks, follow the matching framework guide and apply the same Telegram settings.

Prerequisites

A Telegram bot with a Mini App configured through @BotFather.
A web app that you serve as the Mini App, with the Claimr widget set up as described in Integrate Claimr into a React app.

Configure the campaign

In the Claimr admin panel, open your campaign, click Settings, then select Sign-in options. In Select sign-in services, make sure Telegram is selected. This lets users take part in the campaign with the Telegram identity the Mini App provides.

Set up the Mini App

Load Telegram's Mini App script

Add Telegram’s script to the <head> of your app’s HTML page, before your own scripts:

index.html

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

This script creates window.Telegram.WebApp. The Claimr widget reads the user’s Telegram identity from it, so without it the widget cannot sign the user in.

Load the widget in Telegram mode

Add platform: 'telegram' to the loader configuration in your Claimr provider:

loadClaimr({
  organization: import.meta.env.VITE_CLAIMR_ORGANIZATION,
  campaign: import.meta.env.VITE_CLAIMR_CAMPAIGN,
  container: CLAIMR_CONTAINER_ID,
  autoresize: true,
  platform: 'telegram',
});

If you embed the script tag directly instead of using the loader, add data-platform="telegram" to it.

Configure the Mini App window

When your app starts, expand the Mini App to full height and stop accidental closing:

src/App.tsx

import { useEffect } from 'react';

export function App() {
  useEffect(() => {
    const webApp = window.Telegram?.WebApp;
    webApp?.expand();
    webApp?.enableClosingConfirmation();
    webApp?.disableVerticalSwipes();
  }, []);

  return <QuestsPage />;
}

expand() maximizes the Mini App window.
enableClosingConfirmation() asks the user to confirm before closing the Mini App.
disableVerticalSwipes() stops vertical swipes from closing the Mini App while the user scrolls the widget.

With TypeScript, install @types/telegram-web-app to get types for window.Telegram.

Test inside Telegram

Open the Mini App from your bot in the Telegram app. Outside Telegram, window.Telegram.WebApp has no user data, so the widget cannot sign anyone in automatically.

How it works

A user opens your Mini App in Telegram.
Your app loads the Claimr widget with platform: 'telegram'.
The widget reads the Mini App context from window.Telegram.WebApp and signs the user in with their Telegram account.
The widget shows the campaign’s quests and tasks for that user.
If a task needs another account, such as Discord, email, or a wallet, the widget asks the user to link it.
Task completions are saved to the user’s Claimr profile, linked to their Telegram identity.

Inside Telegram, the widget can also use Mini App features for some tasks, such as sharing a story, sharing a message, or adding the app to the home screen. These need no extra code in your app.

API Guide

Webhooks Guide

SDK Guide

Framework Integration

Guides

Integrate Claimr widget into a Telegram mini app

Prerequisites

Configure the campaign

Set up the Mini App

How it works

​Prerequisites

​Configure the campaign

​Set up the Mini App

​How it works

Prerequisites

Configure the campaign

Set up the Mini App

How it works