Каталог в Telegram Mini App: архитектура API, фильтры и подписки

Каталог внутри Telegram удобен тем, что пользователь не покидает мессенджер: ищет, сохраняет поиск и получает уведомления о новинках. Разберём архитектуру, на которой работает такой каталог, на примере аренды жилья и билетов.

Три части системы

1. API каталога: отдаёт объекты по фильтрам.
2. Авторизация: определяет пользователя по подписанным данным Mini App.
3. Воркер подписок: сопоставляет новые объекты с сохранёнными критериями и отправляет уведомления.

Данные лежат в одной базе, поэтому каталог на сайте и в Mini App всегда одинаковый, а обновления видны сразу.

API каталога

Минимальный набор методов:

Советы:

• Пагинация по курсору, а не по номеру страницы: список не «прыгает», когда появляются новые объекты.
• Фильтры в параметрах запроса: район, тип, диапазон цены, сортировка. Валидируйте значения на сервере.
• Индексы в базе по полям фильтров и сортировки. Без них каталог с тысячами записей начнёт тормозить.
• Миниатюры вместо оригиналов. Фото в списке должны быть лёгкими, оригиналы грузятся в карточке.
• Кэш для частых запросов: популярные фильтры можно хранить на минуты.

Авторизация

Любой запрос, который работает с пользователем (подписки, избранное), должен нести подписанные данные Mini App, которые сервер проверяет. Подробный разбор с кодом: как проверить initData в Python. Публичные методы каталога могут работать без авторизации.

Подписки по критериям

Пользователь сохраняет поиск: район, тип, диапазон цены. Критерии удобно хранить как JSON рядом с идентификатором пользователя:

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
);

Воркер запускается по расписанию или по событию «появился новый объект». Для каждого нового объекта он находит подходящие подписки, отправляет сообщение и запоминает последний уведомлённый объект, чтобы не слать повторы.

Принципы:

• Не дублируйте уведомления. Храните, что уже отправлено каждому пользователю.
• Группируйте. Если появилось много объектов, отправьте один дайджест, а не десять сообщений.
• Давайте простой выход. В каждом уведомлении должна быть кнопка отключения подписки.
• Соблюдайте лимиты Telegram и обрабатывайте ошибки доставки: пользователь мог заблокировать бота.

Уведомление с переходом в приложение

Сообщение отправляется ботом, а кнопка с web_app открывает карточку нового объекта в Mini App. Как отправить такую кнопку, описано в статье про кнопки и меню бота на n8n.

Что показывать и как обновлять

• Свежесть данных важна. В нашем каталоге аренды в Дананге база обновляется автоматически каждые 15 секунд, а новые объявления попадают в каталог и группу без ручной работы.
• Показывайте дату добавления и отметку «сегодня» для новых объектов.
• Сохраняйте состояние интерфейса: выбранные фильтры лучше запоминать, чтобы пользователь возвращался к тому же поиску.

Что получилось у нас

По этой схеме построены Mini App в проектах Da Nang House (каталог жилья с подписками) и HotTrip (горящие билеты с радаром цен). Если нужен каталог в Telegram под вашу нишу, смотрите услугу «Telegram-боты и Mini App» и «Веб-приложения».