# A Telegram Mini App catalog: API design, filters and subscriptions

> A Mini App catalog rests on three parts: an API with filters and pagination, user verification by initData and a subscription worker that matches new items against saved criteria and sends notifications through the bot. One database and one API serve both the website and the Mini App.

Date: 2026-10-30 · Source: https://oneswitch.ru/en/blog/katalog-v-telegram-mini-app-arhitektura/

A catalog inside Telegram is convenient because users never leave the messenger: they search, save a search and get notifications about new items. Here is the architecture behind such a catalog, using rentals and flights as examples.

## Three parts of the system

1. **The catalog API:** returns items by filters.
2. **Authorization:** identifies the user from the signed Mini App data.
3. **A subscription worker:** matches new items against saved criteria and sends notifications.

The data lives in one database, so the catalog on the site and in the Mini App is always the same and updates show up immediately.

## The catalog API

A minimal set of methods:

| Method | Purpose |
|---|---|
| `GET /api/items` | A list with filters, sorting and pagination |
| `GET /api/items/{id}` | An item card: photos, description, map, contact |
| `GET /api/places` | Suggestions for entering a district, city or destination |
| `POST /api/subscriptions` | Save search criteria and enable notifications |
| `GET /api/subscriptions` | A user's subscriptions |
| `DELETE /api/subscriptions/{id}` | Turn a subscription off |

Tips:
- **Cursor pagination** instead of page numbers: the list does not “jump” when new items appear.
- **Filters as query parameters:** district, type, price range, sorting. Validate the values on the server.
- **Database indexes** on filter and sort fields. Without them a catalog with thousands of rows will slow down.
- **Thumbnails instead of originals.** Photos in a list must be light; originals load in the card.
- **Caching** for frequent requests: popular filters can be cached for minutes.

## Authorization

Any request that works with a user (subscriptions, favorites) must carry the signed Mini App data, which the server validates. A detailed walkthrough with code: [how to validate initData in Python](/blog/proverka-initdata-telegram-mini-app-python/). Public catalog methods can work without authorization.

## Subscriptions by criteria

A user saves a search: district, type, price range. It is convenient to store the criteria as JSON next to the user identifier:

```sql
CREATE TABLE subscriptions (
    id          bigserial PRIMARY KEY,
    user_id     bigint NOT NULL,
    criteria    jsonb  NOT NULL,   -- {"district": "Son Tra", "type": "studio", "price_max": 10000000}
    active      boolean NOT NULL DEFAULT true,
    last_notified_item bigint NOT NULL DEFAULT 0
);
```

A worker runs on a schedule or on the “new item appeared” event. For each new item it finds matching subscriptions, sends a message and remembers the last notified item so it does not send repeats.

Principles:
- **Do not duplicate notifications.** Store what has already been sent to each user.
- **Group them.** If many items appeared, send one digest instead of ten messages.
- **Give an easy exit.** Every notification should have a button to turn the subscription off.
- **Respect Telegram limits** and handle delivery errors: the user may have blocked the bot.

## A notification that opens the app

The message is sent by the bot, and a button with `web_app` opens the new item's card in the Mini App. How to send such a button is described in the article about [bot buttons and menus in n8n](/blog/telegram-bot-n8n-knopki-menu-mini-app/).

## What to show and how to update

- **Fresh data matters.** In our rental catalog for Da Nang the database refreshes automatically every 15 seconds, and new listings reach the catalog and the group without manual work.
- **Show the date added** and a “today” badge for new items.
- **Keep the interface state:** remember the chosen filters so the user returns to the same search.

## What we built

The Mini Apps in the [Da Nang House](/raboty/danang-house/) (a housing catalog with subscriptions) and [HotTrip](/raboty/hottrip/) (hot flights with a price radar) projects follow this scheme. If you need a catalog in Telegram for your niche, see [Telegram bots and Mini Apps](/uslugi/telegram-boty-i-mini-app/) and [Web applications](/uslugi/veb-prilozheniya/).

## FAQ

### Do I need a separate website if I have a Mini App?

Preferably yes: the site is for Google and Yandex search, while the Mini App retains users and sends notifications. The data is shared.

### How many items can such a catalog handle?

Thousands of items are served without problems with proper indexes, pagination and thumbnails. Our rental catalog has more than three thousand.

### How do I keep the catalog updated automatically?

Data sources connect to the database on a schedule or via webhooks, and new records immediately appear in the API and in the subscription worker.

### Can I do subscriptions in the bot only, without a Mini App?

You can, but a Mini App is more convenient for choosing criteria and managing subscriptions. The bot remains the notification channel.