# 🤖 SaleBot AI Widget — Виджет чат-бота для сайта

Встраиваемый JavaScript виджет для общения с ИИ-помощником прямо на вашем сайте.

## 📋 Возможности

- ✅ Плавающая кнопка в правом/левом углу
- ✅ Окно чата с историей сообщений
- ✅ Индикатор набора текста
- ✅ Адаптивный дизайн (мобильные + десктоп)
- ✅ Кэширование ответов
- ✅ Поддержка сессий пользователей
- ✅ Настройка цветов и текста
- ✅ Callback функции для событий

## 🚀 Быстрая установка

### 1. Базовая установка

```html
<!-- Вставьте перед закрывающим тегом </body> -->
<script src="https://salebot.dnrrus.ru/static/widget.js"></script>
<script>
    SaleBotWidget.init({
        projectId: 'ВАШ_PROJECT_UUID'
    });
</script>
```

### 2. Расширенная настройка

```html
<script src="https://salebot.dnrrus.ru/static/widget.js"></script>
<script>
    SaleBotWidget.init({
        // Обязательные
        projectId: '8e670e50-2945-4733-aaa1-f23b44483df2',
        baseUrl: 'https://salebot.dnrrus.ru',
        
        // Опциональные
        userId: 'user_123',              // ID пользователя для аналитики
        title: 'Помощник',               // Заголовок окна
        color: '#4a90d9',                // Цвет виджета
        position: 'right',               // 'right' или 'left'
        width: '380px',                  // Ширина окна
        height: '550px',                 // Высота окна
        welcomeMessage: 'Здравствуйте! Чем могу помочь?',
        placeholder: 'Введите ваш вопрос...'
    });
</script>
```

## ⚙️ Параметры конфигурации

| Параметр | Тип | По умолчанию | Описание |
|----------|-----|--------------|----------|
| `projectId` | string | **обязательно** | UUID проекта из SaleBot AI |
| `baseUrl` | string | `https://salebot.dnrrus.ru` | URL вашего сервера |
| `userId` | string | `null` | ID пользователя для аналитики |
| `title` | string | `'Помощник'` | Заголовок окна чата |
| `color` | string | `'#4a90d9'` | Основной цвет виджета (hex) |
| `position` | string | `'right'` | Положение кнопки (`'right'` или `'left'`) |
| `width` | string | `'380px'` | Ширина окна чата |
| `height` | string | `'550px'` | Высота окна чата |
| `welcomeMessage` | string | `'Здравствуйте!...'` | Приветственное сообщение |
| `placeholder` | string | `'Введите сообщение...'` | Текст в поле ввода |
| `showStatus` | boolean | `true` | Показывать статус внизу |
| `onMessage` | function | `null` | Callback при отправке сообщения |
| `onReceive` | function | `null` | Callback при получении ответа |

## 🎨 Примеры настройки

### Синий виджет слева

```javascript
SaleBotWidget.init({
    projectId: 'ВАШ_UUID',
    color: '#2196f3',
    position: 'left',
    title: 'Онлайн-помощник'
});
```

### Зелёный виджет для магазина

```javascript
SaleBotWidget.init({
    projectId: 'ВАШ_UUID',
    color: '#4caf50',
    title: 'Помощник покупателя',
    welcomeMessage: '👋 Привет! Помочь с выбором товара?',
    placeholder: 'Какой товар вас интересует?'
});
```

### С отслеживанием событий

```javascript
SaleBotWidget.init({
    projectId: 'ВАШ_UUID',
    userId: getCurrentUserId(),  // Ваша функция
    onMessage: function(text) {
        console.log('Пользователь отправил:', text);
        // Отправить в аналитику
        ym(XXXXXX, 'reachGoal', 'chat_message');
    },
    onReceive: function(answer) {
        console.log('Бот ответил:', answer);
        // Отправить в аналитику
        ym(XXXXXX, 'reachGoal', 'chat_response');
    }
});
```

## 🔧 API методы

После инициализации доступны методы управления:

```javascript
// Открыть чат
SaleBotWidget.open();

// Закрыть чат
SaleBotWidget.close();

// Переключить видимость
SaleBotWidget.toggle();

// Отправить сообщение программно
SaleBotWidget.sendMessage('Как оформить заказ?');
```

## 📱 Мобильная адаптация

Виджет автоматически адаптируется под мобильные устройства:
- На экранах < 480px окно занимает почти весь экран
- Кнопка остаётся доступной в углу
- Поддержка touch-жестов

## 🎯 Как получить Project UUID

1. Откройте веб-интерфейс SaleBot AI
2. Создайте проект или откройте существующий
3. В настройках проекта скопируйте UUID (выглядит как `8e670e50-2945-4733-aaa1-f23b44483df2`)

## 🔐 Требования к проекту

Проект должен иметь:
- ✅ Загруженную базу знаний (документы)
- ✅ Настроенный LLM провайдер
- ✅ System Prompt (опционально)

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

### Виджет не отображается

1. Проверьте консоль браузера (F12) на ошибки
2. Убедитесь, что `projectId` указан верно
3. Проверьте доступность сервера (`baseUrl`)

### Ошибка "Project not found"

- Проект не найден или не активен
- Проверьте UUID в настройках проекта

### Ошибка "Network response was not ok"

- Сервер недоступен
- Проверьте `baseUrl` (должен быть `https://` для продакшена)
- Проверьте CORS настройки на сервере

### Виджет перекрывает контент

Измените положение:
```javascript
SaleBotWidget.init({
    projectId: 'ВАШ_UUID',
    position: 'left'  // Переместить влево
});
```

Или настройте отступы в CSS вашего сайта:
```css
#salebot-widget {
    bottom: 100px;  // Поднять выше
    right: 100px;   // Сдвинуть от края
}
```

## 📊 Аналитика

Используйте callback функции для отслеживания в Яндекс.Метрике, Google Analytics:

```javascript
SaleBotWidget.init({
    projectId: 'ВАШ_UUID',
    onMessage: function(text) {
        // Яндекс.Метрика
        ym(XXXXXX, 'reachGoal', 'chat_message_sent');
        
        // Google Analytics
        gtag('event', 'chat_message', {
            'event_category': 'engagement',
            'event_label': text.substring(0, 50)
        });
    },
    onReceive: function(answer) {
        ym(XXXXXX, 'reachGoal', 'chat_response_received');
    }
});
```

## 🔒 Безопасность

- Виджет использует только публичные API endpoints
- Не передаёт персональные данные без явного указания `userId`
- Сообщения кэшируются на 5 минут для ускорения повторных запросов
- HTTPS рекомендуется для продакшена

## 📝 Примеры использования

### Интернет-магазин

```javascript
SaleBotWidget.init({
    projectId: 'shop-uuid',
    title: 'Помощник покупателя',
    color: '#ff6b6b',
    welcomeMessage: '👋 Привет! Помочь с выбором или оформлением заказа?',
    placeholder: 'Какой товар ищете?',
    userId: getCustomerId(),
    onMessage: function(text) {
        trackEvent('shop_chat', 'message', text);
    }
});
```

### Сайт услуг

```javascript
SaleBotWidget.init({
    projectId: 'service-uuid',
    title: 'Консультант',
    color: '#4ecdc4',
    welcomeMessage: 'Здравствуйте! Задайте вопрос об наших услугах.',
    placeholder: 'Ваш вопрос...',
    position: 'left'
});
```

### Техподдержка

```javascript
SaleBotWidget.init({
    projectId: 'support-uuid',
    title: 'Техподдержка',
    color: '#9b59b6',
    welcomeMessage: '🔧 Служба поддержки. Опишите проблему.',
    placeholder: 'Что случилось?',
    userId: getUserEmail(),
    onReceive: function(answer) {
        logSupportInteraction(answer);
    }
});
```

## 🎨 Кастомизация через CSS

Переопределите стили виджета:

```css
/* Изменить размер кнопки */
#salebot-widget .sb-widget-btn {
    width: 70px;
    height: 70px;
}

/* Изменить шрифт сообщений */
#salebot-widget .sb-message {
    font-size: 15px;
    font-family: 'Your Font', sans-serif;
}

/* Изменить тень окна */
#salebot-widget .sb-chat-window {
    box-shadow: 0 10px 40px rgba(0,0,0,0.2);
}
```

## 📦 Обновление виджета

При обновлении сервера виджет обновляется автоматически (статический файл).

Для принудительного обновления у клиентов:
```html
<script src="https://salebot.dnrrus.ru/static/widget.js?v=2"></script>
```

## 🆘 Поддержка

Возникли проблемы? Создайте тикет в техподдержку через веб-интерфейс.

---

**Версия виджета:** 1.0  
**Последнее обновление:** 2026-06-19