Магазин в Telegram (встроенный Mini App)

Превратите своего Telegram-бота в полноценный встроенный магазин. Создайте отполированный многостраничный каталог товаров — с фотографиями, видео, тематически оформленными страницами, AI-ассистентом для каждого товара и лёгким приёмом заказов — который открывается внутри Telegram в тот момент, когда клиент нажимает кнопку меню вашего бота. Без магазина приложений, без отдельного сайта, без управления оформлением заказов. Одно касание — и клиент уже просматривает ваш каталог.

Доступно бесплатно на любом тарифе, включая пробный. Создаётся в визуальном конструкторе с перетаскиванием в разделе Integrations → Telegram bot → Configure mini app: 12 типов блоков, 6 тем оформления, AI-чат по каждому товару, CTA-кнопки заказа, которые передают диалог живому оператору в Inbox.

Что можно построить

Несколько типичных форматов, в которых магазин используется на практике:

• Бутиковый магазин — hero-баннер + сетка товаров + чат по каждому товару («Это есть в размере M?») + форма запроса заказа. Заказы попадают в ваш Inbox; член команды отвечает оттуда.
• Меню ресторана — многостраничное (Закуски / Основные блюда / Напитки) + фотогалерея + блок Cart Review + поле адреса доставки на оформлении.
• Каталог курсов или услуг — карточки товаров для каждого курса с видеоблоком-вступлением, отзывами и CTA «Записаться на звонок», возвращающим в бот.
• Сайт-брошюра — hero + страница «О нас» + галерея + контактная карточка + FAQ — вообще без товаров. Магазин превращается в отполированную мобильную брошюру, живущую внутри вашего бота.
• Лендинг для сбора лидов — одна страница, один hero, одна форма, один CTA. Самая лёгкая возможная «Telegram-воронка».

Начните с одной страницы и вырастите её в многостраничный каталог, когда будете готовы.

Почему это важно

• Клиенты не покидают Telegram. Не нужно устанавливать приложение, запоминать домен или проходить через корзину, которую можно бросить. Магазин открывается в Telegram WebView и наследует тему оформления, язык и аутентификацию пользователя.
• Одно касание из чата. Кнопка меню рядом с полем ввода автоматически связывается с вашим магазином при подключении бота. Надпись автоматически переключается на “Shop” в момент публикации товара — настройка через BotFather не нужна.
• AI-чат, встроенный в товар. Чат по каждому товару ограничен документами, которые вы прикрепили к этому товару — ассистент уверенно ответит «какая у этого платья политика возврата?», не утекая фактов из других товаров.
• Передача заказа живому оператору. Лёгкие формы заказа (режим inquiry или cart) попадают в ваш Inbox как структурированный handoff, при этом Telegram-DM клиента остаётся открытым для последующей переписки.
• Бесплатно на любом тарифе. На пробном тарифе действуют лимиты: 5 страниц / 25 блоков на страницу / 100 документов товаров; на любом платном тарифе лимиты сняты. Стоимость считается на организацию — добавление второго Telegram-бота не меняет цену тарифа.

Кратко

• Многостраничный, drag-and-drop. Конечные пользователи нажимают на «гамбургер» (слева вверху), чтобы переключать страницы. Если опубликована одна страница, она грузится на весь экран.
• 12 типов блоков — Hero, Product card, Product grid, Carousel, Gallery, FAQ, Testimonial, CTA back-to-bot, Contact, Video, Rich text, Cart review.
• 6 тем оформления (Telegram по умолчанию + 5 дополнительных) с поблочной переопределением стилей.
• Жизненный цикл Draft → Publish с откатом к последнему опубликованному снимку в один клик.
• Тумблер вкл/выкл на каждую интеграцию — выключите, и кнопка меню бота возвращается к стандартному списку команд / в Telegram; публичный URL отдаёт 410 Gone, чтобы устаревшие закладки не утекали контент.
• Шелл с поддержкой локалей (английский, испанский, бразильский португальский, французский, русский) — автоматически следует за языком Telegram конечного пользователя или фиксируется на одной локали.
• Встроенный Help Center — закреплённая поверхность с FAQ для разовых вопросов, всегда доступна в одно касание. См. ниже.
• Никаких платежей, складского учёта или доставки — это отполированный каталог и поверхность для захвата лидов, а не полный e-commerce-стек. В связке с живым оператором в Inbox вы получаете полный цикл продажи.

Как клиенты его находят

Когда кто-то открывает вашего Telegram-бота, он видит кнопку меню рядом с полем ввода. Касание открывает ваш магазин на весь экран внутри Telegram. Надпись на кнопке:

• “Shop” — устанавливается автоматически, если в опубликованном магазине есть хотя бы одна product card или product grid
• “Open” — устанавливается автоматически в остальных случаях
• Что вы напишете сами — если вы зададите пользовательскую надпись в конструкторе (любая строка из 1–32 символов сохраняется при каждой публикации, пока вы её не очистите)

URL магазина имеет вид https://storefront.cuneiform.chat/{your-org-slug} (с добавлением ?i={integration_id}, только если у вашей организации больше одного Telegram-бота). Скопируйте этот URL с карточки интеграции для QR-кодов, рекламы или для регистрации в BotFather прямой ссылки t.me/<bot>/<app> (см. инструкцию по BotFather на карточке бота).

Предварительные требования

• Подключённая интеграция Telegram. Магазин работает поверх неё — отдельной интеграции для подключения нет.
• (Опционально) Изображения товаров, тексты товаров, FAQ-записи и документы из базы знаний для подключения к AI-чату по товарам.

Быстрый старт (5 минут)

Самый короткий путь от «я подключил бота» до «мой первый клиент уже просматривает каталог»:

1. Зайдите в Integrations → ваш Telegram-бот → Configure mini app. Конструктор открывается в состоянии Draft.
2. Нажмите ”+ Add page” в левой колонке. Назовите страницу (например, «Главная»).
3. Добавьте Hero-блок — заголовок, подзаголовок, фоновое изображение 16:9 (перетащите фото, кадратор откроется автоматически).
4. Добавьте Product card — название, цена, изображение 1:1, краткое описание. Включите AI chat и прикрепите документ (PDF со спецификацией, ваша политика доставки — что угодно из вашей KB).
5. Добавьте Order CTA на этот товар — выберите режим inquiry, выберите поля формы (name всегда обязателен).
6. Нажмите Publish. Надпись на кнопке меню бота автоматически переключится на “Shop”, так как у вас появился товар.
7. Откройте бота в Telegram. Нажмите “Shop”. Нажмите на товар. Нажмите “Ask a question”. Нажмите “Order this”. Отправьте. Вы увидите handoff в вашем Inbox в течение нескольких секунд.

Это минимальный жизнеспособный магазин. Добавляйте больше страниц, товаров, тем, видео и Help Center по мере роста.

Конструктор

Конструктор живёт в Integrations → [ваш Telegram-бот] → Configure mini app (также доступен через меню из трёх точек на карточке бота). Это компоновка из трёх панелей:

Зафиксированная сверху панель инструментов содержит: бейдж статуса (Draft / Published), меню ⋯ (Discard changes / Revert to published), Save as draft и Publish.

Draft и Published

• Save as draft — ваши правки сохранены, но клиенты по-прежнему видят последнюю опубликованную версию.
• Publish — ваш черновик становится живым; автоматически сохраняется замороженный «опубликованный снимок», чтобы вы могли откатиться позже.
• Discard changes — отбрасывает несохранённые локальные правки и перезагружает последнюю сохранённую версию (без вызова сервера).
• Revert to published — копирует опубликованный снимок обратно в рабочий черновик и заново публикует его. Отключено для организаций, которые ещё ни разу не публиковали.

Если вы нажмёте Save as draft, находясь в состоянии Published, появится диалог подтверждения «снять с публикации» (с подсказкой, как вернуть всё обратно).

12 типов блоков

Любой из них можно бросить на страницу магазина:

Каждый блок также поддерживает переопределение стилей на уровне блока — цвет фона, цвет текста, размер шрифта — поверх темы страницы. Используйте их с умом; тема по умолчанию отвечает за внешний вид.

Темы

Выберите тему для каждой страницы. Тема управляет фоном, цветом текста, акцентным цветом и шрифтом.

Там, где вы не выбираете тему, применяется Telegram-тема по умолчанию — ваш магазин всегда выглядит родным для Telegram-приложения клиента.

Настройки на каждую интеграцию

У каждой Telegram-интеграции независимые настройки, привязанные к этому конкретному боту. Добавление второго Telegram-бота в ту же организацию даёт ему собственные независимые тумблеры. Все три настройки живут в левой колонке конструктора в разделе Mini app settings.

Тумблер вкл/выкл магазина

• По умолчанию: включён.
• Выключение делает сразу две вещи:
  1. Кнопка меню бота сбрасывается на стандартный список команд / в Telegram — магазин больше недоступен из UI бота.
  2. Если у клиента в закладках сохранён URL магазина и он откроет его напрямую, шелл покажет сообщение «в настоящее время недоступен» (сервер возвращает 410 Gone, чтобы устаревшие кеши не могли утекать контент через выключенный тумблер).
• Тумблер один раз подтверждается диалогом перед отключением.
• Включение обратно восстанавливает кнопку меню бота (автонадпись или ваше переопределение — что задано).

Переопределение надписи на кнопке меню

• По умолчанию: автовывод при каждой публикации — “Shop”, если в магазине есть хотя бы один product-блок, иначе “Open”.
• Установите пользовательскую надпись (1–32 симв.), чтобы зафиксировать текст кнопки — с этого момента автовывод пропускается, даже после изменения контента или повторной публикации.
• Очистите поле (пустая строка), чтобы вернуться к автовыводу.
• Используйте пользовательскую надпись, если ваша аудитория не говорит по-английски — стандартный автоматический ярлык только на английском.

Язык интерфейса магазина

Шелл по умолчанию использует собственный язык Telegram клиента для своего интерфейса. Если вы наполнили магазин только на одном языке, вы можете зафиксировать язык интерфейса шелла: выберите en, es, pt (бразильский), fr или ru. Если оставить поле пустым, сохраняется автоопределение.

Это влияет только на интерфейс шелла (выдвижной ящик, системные кнопки, заголовок Help Center) — всё, что вы вписали в заголовок hero, название товара или rich-text-блок, отображается как есть.

AI-чат по каждому товару

Любую product card можно превратить в товар с чатом. Каждая product card содержит в конструкторе ряд из двух кнопок для управления документами, которые питают её чат:

• Attach docs — открывает пикер, позволяющий выбрать любую папку из вашей базы знаний. Документы, уже прикреплённые к этому товару, показаны как недоступные, чтобы избежать двойного прикрепления. Нужен новый файл? Используйте действие Upload new прямо в пикере — файл попадает в вашу KB и автоматически выбирается.
• Linked docs (N) — открывает менеджер со списком всего, что сейчас прикреплено. Оттуда можно отвязать документ от этого товара (документ остаётся в вашей KB и на любых других товарах, к которым он привязан) или перейти в Knowledge Base для его редактирования. Менеджер также показывает полоску «Также привязан к: …», когда тот же документ питает другие товары.

Когда клиент нажимает на товар, открывается чат внутри листа. Чат ограничен только привязанными документами одного этого товара — ассистент не утекает ответов из файлов других товаров. Разговоры стримятся в реальном времени (SSE) и хранятся в отдельной коллекции на каждую интеграцию.

Несколько вещей, которые стоит знать:

• Один документ может питать несколько товаров. Поделите один PDF «Доставка и возвраты» между всеми товарами вместо того, чтобы загружать его пять раз.
• Отвязка делается на уровне товара. Удаление документа из одной product card оставляет его нетронутым в KB и на любых других товарах, которые к нему привязаны. Чтобы удалить документ везде, удалите его со страницы Knowledge — все ссылки на него от товаров чистятся автоматически.
• Документы по умолчанию попадают в папку “Showcase Products”, когда вы используете встроенную загрузку из пикера, но вы свободны организовывать их где угодно в KB.

Применяются тарифные лимиты на общее количество документов товаров, которые можно прикрепить (см. Тарифные лимиты).

Запросы заказов и корзина (опционально)

Вы можете прикрепить Order CTA к любой product card или product grid. Это чисто структурированная передача сообщения — никаких платежей, складского учёта или фулфилмента.

Два режима

• Режим inquiry — клиент нажимает “Order this” → открывается форма с предзаполненным товаром → он отправляет → один handoff попадает в ваш Inbox.
• Режим cart — клиент нажимает “Add to cart” → товар добавляется в локальную корзину (живёт только в его браузере, привязана к вашей интеграции) → он пересматривает её на странице корзины (блок Cart review) и оформляет → один многострочный handoff попадает в ваш Inbox.

Поля формы

Выберите любое подмножество из name, phone, email, notes, delivery_address. name всегда обязателен независимо от того, что вы выбрали.

Что происходит после отправки

1. В вашем Inbox создаётся новый диалог с отформатированной сводкой заказа в качестве первого сообщения.
2. Создаётся handoff — живому члену команды подаётся сигнал взять диалог. Позиции заказа и контактная информация прикрепляются как структурированные метаданные.
3. Система моментально отправляет локализованное сообщение «получили ваш заказ» обратно в Telegram-DM клиента, что удерживает 24-часовое окно ответа Telegram открытым, чтобы ответы вашей команды из Inbox чисто маршрутизировались обратно клиенту.
4. Детальный вид в Inbox отображает выделенную панель запроса заказа с позициями, ценами, контактной информацией и заметками, аккуратно разложенными.

Защита от спама и дубликатов

• Каждый клиент может отправить максимум 10 заказов в минуту; каждый тенант — максимум 100 в минуту.
• Двойные касания в течение 60 секунд по точно такому же заказу дедуплицируются; два разных заказа в течение 60 секунд проходят оба.

Встроенный Help Center

Каждый магазин поставляется с небольшим Help Center — закреплённой страницей поддержки в конце меню страниц, всегда в одно касание для клиентов, которым нужен FAQ или которые хотят задать вопрос боту. Наполняется из отдельной панели (Integrations → карточка бота → Help Center), вмещает до ~50 записей с перетаскиванием для изменения порядка. Два режима записи: curated (markdown-ответ отображается inline, нулевая стоимость LLM) и agent (нажатие отправляет заранее написанный вопрос в чат бота). Вы также можете показать подмножество этих записей inline на странице магазина через FAQ-блок — полезно, чтобы поставить несколько ключевых ответов рядом с product cards.

Большинству клиентов никогда не нужно его открывать — товары, галерея и Order CTA отвечают на вопросы по покупательскому потоку прямо в магазине.

Изображения

Когда вы загружаете изображение в конструкторе:

• Допустимые форматы: PNG, JPEG, WebP.
• Максимальный размер загрузки: 2 МБ (оригинал — то, что хранится и отдаётся, существенно меньше).
• Встроенный кадратор открывается автоматически с заблокированным правильным соотношением сторон для слота (16:9 для фонов hero, 1:1 для аватаров товаров / галереи / отзывов).
• Автосжатие: вывод кадратора сжимается в WebP в вашем браузере перед загрузкой (hero ≤500 КБ, товары/галерея ≤350 КБ, аватар ≤100 КБ).
• Подсказка о рекомендуемых размерах показывается над каждой пустой зоной перетаскивания.
• URL изображений автоматически обновляются каждые 15 минут через защищённые presigned URL — клиенты никогда не видят сырые пути к вашему хранилищу.

Лимит 2 МБ распространяется на оригинал, который вы загружаете, а не на то, что видят клиенты. Бросьте сюда фото с 12-мегапиксельной камеры или каталоговый снимок печатного разрешения как есть — кадратор в браузере справится с уменьшением масштаба без видимой потери качества.

Тарифные лимиты

Доступно на любом тарифе, включая бесплатный пробный. Конструктор применяет лимиты.

Заметки:

• product grid или carousel считается за 1 блок по отношению к лимиту блоков на страницу, независимо от количества элементов или слайдов внутри.
• Когда вы упираетесь в лимит, конструктор показывает модальное окно с предложением апгрейда.
• Цена считается на организацию, а не на бота. Добавление второго (или пятого) Telegram-бота в вашу организацию не меняет цену тарифа. Каждый бот получает свой магазин внутри того же тарифа; лимиты делятся между всеми вашими ботами под одной организацией.

Права доступа

Все действия записи в конструкторе (сохранение, публикация, загрузка изображений, загрузка документов товаров, откат) требуют права Integration manage для Telegram. На практике это означает, что роли Owner и Admin могут наполнять магазин; роль Member доступна только для просмотра.

На сегодня нет роли «только для магазина» — и Owner, и Admin также видят раздел Billing. Если вы привлекаете подрядчика для построения магазина, ваши варианты:

• Добавить его как Admin (с оговоркой, что он также увидит Billing).
• Использовать сессию с демонстрацией экрана, где вы остаётесь залогинены, а фрилансер управляет.
• Попросить его подготовить ассеты/тексты офлайн (документ со всем текстом + изображения), и вы вставите их сами как Owner.

Гранулярная роль «Integration Editor» — в дорожной карте.

Производительность и свежесть

• Серверный кеш — публичный ответ магазина кешируется на 5 минут на интеграцию.
• Сброс кеша при публикации — в момент, когда вы нажимаете Publish (или Revert), кеш сбрасывается, поэтому клиенты увидят ваши изменения при следующем запросе страницы.
• Поддержка ETag — шелл использует HTTP If-None-Match и получает быстрый 304 Not Modified, если ничего не изменилось, экономя мобильный трафик.
• URL изображений валидны 15 минут; шелл автоматически перезапрашивает их до истечения.

Чего магазин НЕ делает

• Никаких платежей. Order CTA — это передача запроса, а не оформление через Stripe / WhatsApp Pay / Telegram Stars.
• Никакого складского учёта. Бейджи наличия — это свободно заполняемые метки, которые вы редактируете вручную.
• Никаких расчётов доставки и валидации адреса. Адрес доставки собирается как свободный текст.
• Никаких клиентских учётных записей. Клиенты идентифицируются по Telegram user ID; нет потоков логина или регистрации.
• Никаких форм, кроме Order Inquiry / Cart Checkout. Блок Contact — это статическое отображение; rich-text-блок не рендерит формы.
• Сценарии Help Center «спросить бота» и оформление заказа отклоняют запуски из групп / каналов вежливой ошибкой.

Сквозной поток клиента

1. Клиент открывает вашего бота в Telegram и нажимает на кнопку меню — с надписью “Shop” (автовывод из product-блоков) или той, что вы задали как пользовательскую.
2. Магазин загружается внутри Telegram. Клиент видит вашу первую страницу.
3. Он листает галерею, смотрит видео, нажимает на товар.
4. Товар открывается в листе. Он нажимает “Ask a question” → открывается AI-чат, ограниченный документами этого товара. Он получает ответ.
5. Он нажимает “Order this” → всплывает форма → он заполняет name + phone → отправляет.
6. Он моментально получает сообщение «получили ваш заказ, мы свяжемся» в свой Telegram-DM.
7. Ваша команда получает новый handoff в Inbox с деталями заказа. Любой ответ, отправленный вашей командой из Inbox, попадает в DM клиента в реальном времени.

Устранение неполадок

Кнопка меню не открывает магазин

1. Убедитесь, что тумблер вкл/выкл магазина включён (конструктор → левая колонка → Mini app settings).
2. Отключите и заново подключите интеграцию Telegram — кнопка меню чата устанавливается на этапе подключения, и устаревший бот может не иметь её.
3. Если вы задавали пользовательскую кнопку меню через BotFather, это перекрывает автонастройку платформы — очистите её через /setmenubutton BotFather.

Клиенты видят «в настоящее время недоступен» при прямом открытии URL

Тумблер вкл/выкл магазина выключен — включите его обратно из левой колонки конструктора.

Изменения, которые я только что сохранил, не отображаются у клиентов

Ваши изменения всё ещё в Draft. Нажмите Publish на панели инструментов конструктора — серверный кеш сбрасывается немедленно. Если вы уже опубликовали, а клиенты по-прежнему видят устаревший контент, попросите их потянуть страницу вниз для обновления внутри магазина (Telegram кеширует WebView).

Чат по товару отвечает из документов другого товара

Перепроверьте менеджер Linked docs на product card — чат питают только документы, явно привязанные там. Если документ не появляется, прикрепите его через пикер Attach docs.

Пользовательская надпись на кнопке меню не применилась

У поля ввода надписи свои собственные кнопки Save / Reset (в отличие от тумблера вкл/выкл, который автосохраняется). Нажмите Save после ввода — частичные нажатия клавиш никогда не доходят до Telegram.

Отключение

Магазин — часть интеграции Telegram, поэтому он исчезает при отключении бота:

• Integrations → карточка Telegram → меню из трёх точек → Delete

Страницы магазина, блоки и записи help, которые вы создали, удаляются вместе с интеграцией. Чтобы оставить бота подключённым, но снять с публикации только магазин, переключите тумблер вкл/выкл магазина в положение «выкл».

Связанное

• Telegram — родительская интеграция; магазин работает поверх неё
• Saba on Telegram — операторский Saba-бот (другая функция, тоже на основе Telegram)
• Telegram Business — AI-ответы на личном аккаунте Premium-пользователя (другая функция)