telegram-gifts-sdk

White-label SDK for integrating the Quetlink AI gift recommendation service into any Telegram Mini App. Catalog, AI survey, favorites, product cards — everything works out of the box.

Installation

npm install telegram-gifts-sdk
# or
pnpm add telegram-gifts-sdk
# or
yarn add telegram-gifts-sdk

Peer Dependencies

• react >= 18.0.0
• react-dom >= 18.0.0

No other dependencies required. No static files to copy. Everything is self-contained.

Quick Start (2 lines)

import { QuetlinkGiftsApp } from "telegram-gifts-sdk";
import "telegram-gifts-sdk/dist/index.css";

export default function GiftsPage() {
  return <QuetlinkGiftsApp botUsername="YourBotUsername" />;
}

That's it. The SDK renders a full-featured gift recommendation experience: product catalog, AI-powered survey, results, favorites, and product detail pages — all managed internally.

Integration Example

A typical Telegram Mini App with a bottom navigation bar:

"use client";

import { useState } from "react";
import { QuetlinkGiftsApp } from "telegram-gifts-sdk";
import "telegram-gifts-sdk/dist/index.css";

type Tab = "home" | "gifts";

export default function App() {
  const [tab, setTab] = useState<Tab>("home");

  return (
    <div className="app">
      <div className={`content${tab === "gifts" ? " content--sdk" : ""}`}>
        {tab === "home" && <HomeScreen />}
        {tab === "gifts" && <QuetlinkGiftsApp botUsername="YourBotUsername" />}
      </div>

      <nav className="bottom-nav">
        <button onClick={() => setTab("home")}>Home</button>
        <button onClick={() => setTab("gifts")}>Gifts</button>
      </nav>
    </div>
  );
}

Handling Bottom Navigation Overlap

If your app has a fixed bottom navigation bar, set the --ql-bottom-safe-area CSS variable on the SDK's parent container so buttons and inputs inside the SDK are not clipped:

.content--sdk {
  padding-bottom: 0;
  --ql-bottom-safe-area: 64px; /* height of your bottom nav */
}

Props

QuetlinkGiftsApp

The main all-in-one component. Includes catalog, AI survey, favorites, and product detail views with built-in navigation.

| Prop | Type | Default | Description | | --- | --- | --- | --- | | botUsername | string | "QLinkLinkBot" | Bot username (without @), used as source_id in API requests | | catalogUrl | string | Quetlink API | Custom catalog endpoint URL | | recommendationsUrl | string | Quetlink API | Custom recommendations endpoint URL | | initialView | "catalog" \| "assistant" \| "favorites" | "catalog" | Which view to show on first render |

Advanced: Individual Components

For full control over layout and navigation, you can use the components separately inside a QuetlinkProvider:

import {
  QuetlinkProvider,
  GiftCatalog,
  GiftAssistant,
  GiftFavorites,
  GiftProductDetail,
} from "telegram-gifts-sdk";
import "telegram-gifts-sdk/dist/index.css";

Wrap your tree with QuetlinkProvider and render components manually. This is only needed if you want custom navigation between views.

Features

• Works in any React project — no framework dependency (Next.js, Vite, CRA, etc.)
• Self-contained: no static files, fonts, or icons to copy
• All assets (SVGs, images) are embedded in the bundle
• Telegram WebApp API integration (haptic feedback, back button, expand, etc.)
• Graceful fallback outside Telegram (works in any browser for development)
• Persistent favorites via localStorage
• Session state preserved across page refreshes via sessionStorage
• Responsive design optimized for mobile screens
• TypeScript types included

License

MIT