E‑com / Mini App (Telegram, VK, MAX)

0. Полный путь: создание, настройка, правки

Создание: кабинет → «Новый агент» → шаблон «E‑com / …» (Telegram, VK или MAX). Мастер: имя → подключение канала (Telegram: токен и webhook; VK: Callback API; MAX: на шаге 2 создаётся endpoint вебхука и секрет) → шаг 3: бренд витрины, ссылка на таблицу каталога, SMTP для заказов.

После создания все правки — в кабинете агента: вкладка «Агент · E‑com» (токен VK/TG, текст про MAX), блок «Бренд витрины» (URL витрины, JSON темы), вкладка «Интеграции» (таблица, почта, при необходимости оплата мерчанта). Вкладка «Инструкция» дублирует пошаговые подсказки по каналам.

Редактирование каталога: обновите Google/Яндекс Таблицу — агент подхватит данные в промпт после кэша (~1 мин для публичного каталога API). Редактирование бренда и ключей — сохранение в том же блоке «Бренд витрины» / «Интеграции».

1. Общая схема

Создайте агента из шаблона E‑com (Telegram, VK или MAX с вебхуком). В кабинете подключите таблицу каталога и SMTP для писем о заказах — без этого сценарий неполный.

Витрина (страница магазина) хостится на домене сервиса; для Telegram после сохранения токена вызывается setChatMenuButton — кнопка «Магазин» в меню чата. Для VK и MAX тот же HTTPS‑URL нужно указать вручную в настройках VK Mini App или в своём клиенте MAX (см. блок «Бренд витрины» в кабинете).

2. Таблица каталога и сопоставление колонок

Минимальный набор колонок: название, раздел (категория), наличие, описание, цена, ссылка на изображение товара.

Желательно: артикул (SKU), валюта, старая цена или скидка, единица измерения (шт., кг и т.д.).

В настройках интеграции с таблицей укажите публичную ссылку и строку сопоставления «колонка → роль» (одна строка на поле), как описано в инструкции «Таблицы (Google и Яндекс)». Агент не ходит в API таблицы за каждым сообщением — данные попадают в системный промпт в согласованном виде.

Готовый пример каталога в Google Таблице (публичный просмотр): https://docs.google.com/spreadsheets/d/1OU76pjhEXoZ6DZWGgpNXa3lTxJGA_1-3NAZiOO2ZYrw/edit?gid=0#gid=0 — можно ориентироваться на заголовки и строки или сделать копию через «Файл → Создать копию».

3. Почта заказов (SMTP)

Во вкладке «Интеграции» настройте исходящую почту (Яндекс, Gmail, Mail.ru или свой SMTP с паролем приложения при необходимости). Подробнее про хосты, пароли приложений и шаблон письма о заказе — в инструкции «Почта (IMAP/SMTP)» и ниже в этом разделе.

Адрес «куда слать уведомления о заказах» задаётся в настройках почты (получатель исходящих служебных писем / BCC при необходимости) и в системных инструкциях агента: явно пропишите, что при оформлении заказа нужно сформировать письмо на ящик магазина с составом корзины, контактом клиента и суммой.

Текст темы и тела письма не генерируется отдельным шаблонизатором платформы — их описывает инструкция ассистента. Проверьте тестовым заказом из чата, что письмо доходит и не попадает в спам (SPF/DKIM у домена — на стороне вашего почтового провайдера).

4. Telegram Mini App

Подключите интеграцию Telegram: токен бота из @BotFather (https://t.me/BotFather) и регистрация webhook — как для обычного бота. После сохранения токена сервис вызывает setChatMenuButton: кнопка «Магазин» ведёт на готовую витрину (тот же URL, что в кабинете в поле URL витрины / ecom_storefront_url). В @BotFather в разделе домена для Web App укажите хост этой витрины (HTTPS). Документация Web Apps: https://core.telegram.org/bots/webapps

Диалог с агентом идёт через бота; сценарий заказа во встроенной витрине или в своём фронте должен приводить к тому, чтобы ассистент мог оформить заказ в чате и зафиксировать ответ для тарификации (15 ₽ за заказ).

5. VK Mini App

Подключите интеграцию ВКонтакте по инструкции «VK в сервисе» в документации кабинета. Callback API сообщества обрабатывает сообщения в чате; платформа не регистрирует VK Mini App за вас.

Скопируйте URL витрины из блока «Бренд витрины» и укажите его как стартовый URL / WebView в кабинете VK Mini Apps. Официальные шаги: https://dev.vk.com/ru/mini-apps/getting-started . Callback API: https://dev.vk.com/ru/api/callback-api/overview

6. Входящий вебхук (MAX max.ru и внешние каналы)

Для шаблона с вебхуком создайте интеграцию типа «Вебхук»: в кабинете будет URL приёма и секрет. Запросы только по HTTPS. Документация экосистемы MAX для разработчиков: https://dev.max.ru/docs

Заголовок: X-Integration-Secret: <секрет из настроек интеграции>. Тело JSON, Content-Type application/json.

Обязательное поле: message (строка, до 8000 символов) — текст пользователя или сформированное описание заказа для ассистента. Необязательные поля: conversation_url, external_user_id, sender_label, channel — для контекста и журналов.

Пример тела: {"message": "Заказ: 2× Футболка M, сумма 1998 ₽, доставка Москва", "external_user_id": "user-42", "channel": "max"}. Ответ сервера — JSON с результатом обработки (ответ ассистента и служебные поля по факту API). Витрину с каталогом откройте по тому же публичному URL, что в кабинете, или встройте в WebView своего клиента MAX.

7. Тариф и проверка

15 ₽ за заказ: учитывайте это при тестах — каждое успешное оформление заказа с ответом ассистента тарифицируется отдельно от обычного поминутного/помодельного списания за переписку.

Проверка: сохраните таблицу и SMTP, отправьте тестовый запрос к агенту с вопросом по товару из каталога и пройдите сценарий заказа; для вебхука — вызовите URL с корректным секретом и полем message.

8. Бренд витрины, тема Telegram/VK и публичный JSON

В кабинете агента (вкладка «Интеграции») для шаблонов E‑com доступен блок «Бренд витрины»: название, слоган, URL логотипа (только https), пять цветов витрины (шрифт, фон, кнопки разделов, «Заказать», «В корзину») и пресет раскладки (сетка / список / витрина). Эти данные попадают в системный промпт как блок «Бренд витрины», чтобы ответы ассистента совпадали по тону с витриной, и доступны без авторизации в виде JSON.

Публичный HTTPS URL страницы витрины совпадает с тем, что использует Telegram для кнопки меню (если включена авто‑синхронизация); для VK и MAX его нужно копировать из кабинета вручную. В ответе API агента поле ecom_storefront_url дублирует этот адрес. Если фронт витрины на другом домене, чем Laravel API, задайте на сервере переменные ECOM_MINIAPP_PUBLIC_BASE и при необходимости ECOM_MINIAPP_PATH (см. backend/.env.example) — иначе базой подставится APP_URL.

Отдельно в том же кабинете можно сохранить ключи ЮKassa или Robokassa (только ввод в форму, без правки кода на стороне платформы): они не проводят оплату из чата автоматически, а попадают в контекст ассистента и в краткое резюме в публичном JSON (merchant_payments) для вашего Mini App или бэкенда — см. инструкцию «Оплата мерчанта (ЮKassa / Robokassa)».

Публичные endpoints: GET /api/public/ecom/{публичный_ключ}/theme — тема и merchant_payments; GET /api/public/ecom/{публичный_ключ}/catalog — товары из таблицы по column_mapping (кэш ~45 с); POST /api/public/ecom/{публичный_ключ}/orders — оформление заказа с витрины (тело: customer_name, customer_contact, delivery_address, comment?, items[{ product_ref, qty }]); product_ref в формате idx-0 или sku-… как в витрине; письмо владельцу через настроенный SMTP (лимит запросов). Публичный ключ выдаётся при создании агента E‑com; при паузе агента ответ 404. CORS для api/* настроен широко — Mini App на другом origin может запросить данные по fetch.

В Telegram: иконка и описание бота, домен для Web App — в @BotFather; кнопка меню «Магазин» синхронизируется сервисом на URL витрины. Документация Web Apps: https://core.telegram.org/bots/webapps

Во ВКонтакте и MAX: подставьте URL витрины в настройки приложения вручную; оформление сообщества — в кабинете VK (https://dev.vk.com); экосистема MAX — https://dev.max.ru/docs

9. Отличие от конструкторов «магазин из коробки»

Сервисы вроде no-code конструкторов Telegram-магазинов часто дают готовую витрину, оплату и промо в одном интерфейсе. У MrSmit упор на гибком ассистенте и каталоге из таблицы; платформа даёт готовую страницу витрины и публичные API темы/каталога, а глубокую кастомизацию UX и приём оплаты вы можете дописать у себя, опираясь на JSON и документацию провайдеров оплаты.