Быстрый старт
Для запуска виджета в базовой конфигурации достаточно выполнить четыре шага. Это займет не более 10-15 минут.
Шаг 1: Создайте и настройте AI-провайдера
AI-провайдер — это нейросеть, которая будет генерировать ответы. Первым делом нужно подключить хотя бы одного провайдера.
- Перейдите в настройки модуля на вкладку «Провайдеры».
- Слева в блоке «Доступные провайдеры» находится список всех интегрированных в модуль сервисов. Справа, в «Настроенных провайдерах», будут отображаться те, которые вы добавите.
- Нажмите кнопку «Выбрать» напротив нужного провайдера.
- В форме ниже заполните все необходимые поля, используя данные (API-ключ, модель и т.д.), которые вы получили от вашего AI-провайдера.
- Нажмите кнопку «Тест провайдера». Отправьте тестовый запрос, чтобы убедиться, что настройки верны.
- Если тест прошел успешно (вы получили ответ от нейросети, а индикаторы стали зелеными), сохраните провайдера. Теперь он готов к работе.
Если при тестировании возникают ошибки, внимательно проверьте правильность введенных данных. Подробную информацию о кодах ошибок можно найти в документации самого AI-провайдера или обратившись в нашу службу поддержки.
На этом минимальная конфигурация готова. Дополнительно можно включить режим поддержки, управление временем работы ИИ, «Call Manager» и т.д.
Шаг 2: Добавьте навык для доступа к данным
Навыки — это инструменты, которые AI использует для доступа к информации вашего магазина. Чтобы ассистент мог отвечать на вопросы о товарах, ему нужно дать соответствующий навык.
- Перейдите на вкладку «ИИ Навыки». Слева вы увидите список доступных в модуле интеграций, а справа — те, что вы уже настроили и активировали.
- В списке «Доступные навыки» найдите «Получить товары» (getProducts) и нажмите кнопку «Выбрать».
- Откроется форма с детальными настройками. Рассмотрим их подробно.
Найстройка навыка «Получить товары»
- Отображаемое имя: Название навыка, которое будет видно в интерфейсе. Например, «Найти товары в каталоге».
- Включен: Активирует или деактивирует навык.
- Видимость в списке: Если включено, навык может отображаться в виджете как подсказка для пользователя.
- Приоритет: Число, определяющее порядок вызова навыков. Чем меньше число, тем выше приоритет.
Подключение к базе данных
Навык запрашивает прямые реквизиты для подключения к базе данных OpenCart. Это сделано для максимальной производительности: поиск выполняется быстрыми SQL-запросами, не загружая весь фреймворк магазина.
- Хост БД, Имя БД, Пользователь БД, Пароль БД: Ваши стандартные данные для подключения к MySQL.
- Префикс таблиц: Укажите префикс таблиц вашего OpenCart (например,
oc_).
Логика и глубина поиска
Эти настройки управляют тем, как именно модуль будет искать товары.
- Логика бокового поиска (AND/OR): Определяет, как обрабатываются несколько слов в запросе.
AND — найти товары, где есть все слова. OR — найти товары, где есть любое из слов.
- Поиск по атрибутам / Поиск по опциям: Включает поиск не только по названию и описанию, но и в атрибутах и опциях товаров, что значительно повышает релевантность выдачи.
- Двойной поиск: Очень мощная функция. Если первый стандартный поиск не дал результатов, модуль автоматически запускает второй, более широкий поиск. Например, он может переключить логику с «AND» на «OR» или подключить поиск по атрибутам, даже если он был выключен.
- Расширять ключевики через ИИ: Перед поиском в базе данных модуль обращается к AI-провайдеру, чтобы обогатить запрос синонимами и похожими фразами. Например, запрос «зимние ботинки» может быть расширен до «теплая обувь на зиму». Эта опция активируется только во время второго прохода (при «Двойном поиске»), чтобы не замедлять основной поиск.
- Подсказка AI для второго поиска: Позволяет задать собственный шаблон промпта для функции расширения ключевых слов, чтобы точнее управлять поведением нейросети.
Предустановленные значения параметров (Inputs)
Этот блок для тонкой настройки и использования в сложных сценариях. Он позволяет задать значения по умолчанию для параметров, которые может использовать AI.
- ID Товаров / ID Языка: Позволяет ограничить поиск конкретными товарами или языковой версией магазина.
- Ключевые слова: Предустановленный поисковый запрос.
- Начало (start) / Количество (limit): Управляют пагинацией (сколько товаров пропустить и сколько вернуть).
- Возвращаемые поля: Критически важная настройка для оптимизации. Здесь можно перечислить через запятую поля, которые навык должен вернуть (например:
product_id,name,price,url,image,attributes).
После того как вы настроили все параметры, нажмите «Сохранить навык». Теперь ваш AI-ассистент умеет искать товары, если его добить в соответствующий виджет.
Шаг 2.2 (Опционально): Добавьте навык «Информация по заказу»
Чтобы AI-ассистент мог помогать клиентам с их заказами, ему необходим соответствующий навык. Он позволяет получать статус, состав и историю заказа.
Важно: этот навык разработан с учетом безопасности. Он автоматически определяет авторизованного пользователя по его сессии и показывает данные только по его заказам. Неавторизованный пользователь получит вежливое предложение войти в свой аккаунт.
- На той же вкладке «ИИ Навыки» найдите в списке доступных «Информация по заказу» и нажмите «Выбрать».
- Основные параметры (имя, приоритет) и настройки подключения к базе данных заполняются аналогично навыку поиска товаров.
- Рассмотрим специфические настройки этого навыка.
Управление данными
Эти параметры определяют, какую именно информацию о заказе получит AI.
-
Поля по умолчанию: Ключевая настройка. Это список полей, которые будут возвращены по умолчанию. Чем точнее вы укажете список, тем меньше лишних данных будет передано в нейросеть, что экономит токены и повышает точность ответа. Пример:
order_id,status_name,total,date_added,shipping_method,order_url.
Предустановленные значения параметров (Inputs)
Этот блок позволяет гибко настраивать детализацию ответа.
- Номер заказа: Обычно это поле заполняется самим пользователем в диалоге с чат-ботом (например, "какой статус у заказа #123?").
- Поля заказа: Позволяет переопределить список полей для конкретного вызова, если это необходимо.
- Возвращать товары / итоги / историю статусов: С помощью этих галочек вы можете включать или отключать передачу в AI детальных блоков: списка товаров в заказе, финансовых итогов (скидки, доставка, общая сумма) и истории изменения статусов. Для простых запросов («Какой статус заказа?») эти опции можно отключить для экономии.
- История: количество записей: Ограничивает глубину выгружаемой истории статусов, чтобы не передавать слишком много информации.
После настройки нажмите «Сохранить навык». Теперь ассистент умеет работать с заказами клиентов.
Шаг 2.3: Настройте навык «FAQ (CSV)» — вашу базу знаний
Это самый эффективный способ научить AI отвечать на часто задаваемые вопросы. Вы создаете файл с вопросами и ответами, а модуль превращает его в умную базу знаний, доступную для ассистента.
1. Подготовка CSV-файла
Вся информация хранится в стандартном CSV-файле с разделителями-запятыми и кодировкой UTF-8. Вы можете создать его в Excel, Google Sheets или любом текстовом редакторе. Структура файла должна содержать определенные колонки:
"question","answer","id","category","links","keywords","render"
question — Текст вопроса, как его мог бы задать клиент.answer — Готовый, исчерпывающий ответ на этот вопрос.id — Уникальный идентификатор строки. Обязательное поле.category (опционально) — Категория вопроса. Используется для умной фильтрации.links (опционально) — Полезные ссылки, связанные с ответом. Можно указать несколько через запятую.keywords (опционально) — Ключевые слова и синонимы через запятую. Это критически важное поле для повышения точности поиска. Добавьте сюда все возможные формулировки, которые могут использовать клиенты.render (опционально) — Позволяет вставить готовый HTML-код, который будет отображен вместо стандартного форматирования ответа.
Пример строки в CSV-файле:
"Поддерживает ли виджет любых провайдеров ИИ?","Да, поддержка полная. В базе уже есть интеграции с YandexGPT, GigaChat, ChatGPT. Новые добавляются по запросу.",2,"Возможности ИИ","https://site.ru/page1,https://site.ru/page2","провайдеры, поддержка, YandexGPT, GigaChat, интеграции",""
2. Настройка навыка в админ-панели
После подготовки файла перейдите на вкладку «ИИ Навыки», выберите «FAQ (CSV)» и заполните поля:
- Путь к CSV-файлу: Укажите URL-адрес вашего файла (например, если он загружен в корень сайта) или абсолютный путь на сервере. Модуль умеет работать с удаленными файлами.
- Период обновления кэша (минуты): Для ускорения работы модуль не скачивает файл при каждом обращении, а создает локальную SQLite-копию. Эта настройка указывает, как часто ее обновлять. Если указать
0, кэш будет пересобираться при каждом запросе (полезно для отладки).
- Максимум записей в промпте AI: Ограничивает количество вопросов из CSV, которые отправляются нейросети для анализа. Помогает контролировать расход токенов и ускорять ответ.
- Учитывать категории: Если опция включена, AI сначала пытается определить наиболее релевантную категорию по вопросу пользователя, и только потом ищет ответ внутри этой категории. Это значительно повышает точность для больших баз знаний.
- Тест FAQ: Обязательно используйте эту кнопку. Она проверит доступность вашего CSV-файла, правильность его структуры и покажет первые несколько записей для контроля.
Чем полнее и детальнее будет ваш FAQ-файл, тем умнее и полезнее будет ваш AI-ассистент. Уделите особое внимание заполнению колонки keywords — это напрямую влияет на качество поиска.
Сохраните навык. Теперь у вашего ассистента есть полноценная база знаний.
Шаг 2.4: Настройте навык «Позвать менеджера»
Этот навык — прямой канал связи с вашей командой. Когда AI не может помочь или клиент явно просит позвать человека, активируется именно эта функция для эскалации диалога.
- На вкладке «ИИ Навыки» выберите «Позвать менеджера».
- Настройки здесь предельно просты:
- Email адреса менеджеров: Укажите через запятую email-адреса сотрудников, которые должны получать уведомления о вызове.
- Сообщение от пользователя: Это системное поле, которое будет автоматически заполнено последним сообщением клиента, чтобы менеджер сразу видел контекст обращения.
Интеграция с Telegram: Основная сила этого навыка раскрывается при подключении Telegram. Уведомление не просто придет в общий чат, а персонально упомянет (`@username`) менеджеров, которые авторизованы в боте. Это гарантирует, что запрос не останется незамеченным.
После сохранения этого навыка ваша система готова не только к автономной работе, но и к бесшовной передаче диалога живому специалисту.
Шаг 3: Настройте и свяжите всё в виджете
Виджет — это финальная конфигурация, которая объединяет AI-провайдеров, навыки и дизайн в единое целое. Вы можете создать несколько виджетов для разных сайтов или задач.
- Перейдите на главную вкладку модуля «Общие» и нажмите кнопку «Создать виджет».
- Откроется страница с множеством настроек. Давайте пройдемся по самым важным из них.
Основные настройки
- Название виджета: Простое имя для идентификации (например, «Чат для основного сайта»).
- Общий системный промпт: Это «личность» вашего AI. Здесь вы задаете его роль. Например: «Ты — дружелюбный и вежливый консультант интернет-магазина "ТехноМир". Твоя задача — помогать пользователям с выбором товаров и отвечать на вопросы по заказам.»
- Разрешенные сайты: В целях безопасности здесь нужно указать домены (по одному на строку), на которых будет разрешена работа виджета.
Настройки AI
- Провайдер ИИ: Выберите одного из AI-провайдеров, которого вы настроили на первом шаге.
- AI включен: Главный переключатель работы нейросети.
- Время работы ИИ: Позволяет настроить расписание, когда AI будет активен (например, с 9:00 до 21:00). В нерабочее время виджет может переходить в режим поддержки или скрываться.
- Режим поддержки: Позволяет полностью отключить AI, оставив только возможность общения с менеджером через Telegram.
Интеграция с Telegram
Это одна из ключевых функций модуля. Она позволяет менеджерам получать уведомления и отвечать клиентам прямо из Telegram.
- Включить ретрансляцию: Активирует интеграцию.
- Токен бота и Username бота: Данные, которые вы получаете от @BotFather при создании своего бота в Telegram.
- Получатели: Список ID менеджеров, которые будут получать уведомления. Формат важен:
telegram_id|username. ID нужен для отправки сообщения, а @username используется навыком «Позвать менеджера» для персональных упоминаний.
- Webhook: Механизм, через который Telegram мгновенно доставляет сообщения от менеджеров в виджет. Нажмите «Установить webhook», чтобы зарегистрировать ваш сайт в Telegram. Для этого у вашего сайта должен быть установлен SSL-сертификат (HTTPS).
Команды виджета (Подключение навыков)
На этой вкладке вы увидите все навыки, которые создали ранее. Поставьте галочки напротив тех, которые должен использовать именно этот виджет (например, «Найти товары», «FAQ (CSV)» и «Позвать менеджера»). Вы также можете переопределить их названия специально для этого виджета.
Дизайн и тексты
На соответствующих вкладках вы можете полностью настроить внешний вид виджета: цвета, шрифты, положение на экране, иконки, звуки, а также все текстовые надписи — от приветствия до текста на кнопках.
После того как вы заполнили все необходимые поля и подключили навыки, нажмите «Сохранить». Ваш виджет полностью настроен и готов к установке.
Шаг 4: Установка виджета на сайт
Остался последний шаг — разместить код виджета в шаблоне вашего сайта.
- Вернитесь на вкладку «Общие» и найдите в списке ваш созданный виджет. Нажмите «Редактировать».
- Прокрутите страницу вниз до раздела «Код вставки виджета».
- Вы увидите два варианта:
- Плавающий виджет: Стандартная кнопка чата, закрепленная в углу экрана.
- Встроенный виджет: Позволяет встроить окно чата непосредственно в контент страницы (например, на странице контактов).
- Скопируйте код для плавающего виджета и вставьте его в шаблон вашего сайта перед закрывающим тегом
</body>.
Поздравляем! После сохранения шаблона на вашем сайте появится иконка чат-виджета, полностью настроенного и готового к работе.