# ChatSell Widgets WordPress Plugin

Easy-to-use chat and product search widgets for WordPress sites. Add AI-powered customer support and product discovery to your site.

## Features

### Chat Widget
- Real-time AI-powered customer support
- Product recommendations and search
- Customizable appearance and behavior
- Multiple positioning options (bottom-right, bottom-left, top-right, top-left)
- Sound notifications and avatar display
- WebSocket-based real-time communication
- Product variant filtering

### Product Search Widget
- Lightning-fast product search
- Floating or inline positioning
- Product variant filtering
- Customizable styling
- Keyboard shortcuts (press "/" to open)
- Responsive design
- Full-width inline mode support

## Installation

1. Download the plugin files
2. Upload to `/wp-content/plugins/chatsell-widgets/` directory
3. Activate the plugin through WordPress admin
4. Go to Settings > ChatSell Widgets to configure
5. Enter your Site ID and API URL
6. Enable and customize your widgets

## Configuration

### Required Settings
- **Site ID**: Your unique ChatSell site identifier
- **API URL**: Your ChatSell backend server URL

### Chat Widget Settings
- Title and subtitle
- Position (bottom-right, bottom-left, top-right, top-left)
- Primary color
- Show/hide avatar
- Enable/disable sound
- Welcome message
- Input placeholder
- Product variants handling
- Variant filters

### Product Search Widget Settings
- Position (top-right, top-left, bottom-right, bottom-left)
- Primary color
- Placeholder text
- Results limit (1-50)
- Product variants handling
- Variant filters
- Mount mode (floating/inline)
- Container selector (for inline mode)
- Full width option (for inline mode)

## Usage

### Shortcodes

Place widgets anywhere using shortcodes:

```php
// Basic usage
[cswidgets_chat]
[cswidgets_search]

// With custom parameters
[cswidgets_chat title="Custom Title" position="top-left"]
[cswidgets_search position="bottom-right" limit="5"]
```

### Shortcode Parameters

#### Chat Widget
- `title` - Widget title
- `subtitle` - Widget subtitle
- `position` - Position (bottom-right, bottom-left, top-right, top-left)
- `primary_color` - Primary color (hex)
- `hover_color` - Hover color (hex)
- `show_avatar` - Show avatar (1/0)
- `enable_sound` - Enable sound (1/0)
- `welcome_message` - Welcome message
- `placeholder` - Input placeholder
- `variants` - Product variants (none, all, only)
- `variant_filters` - Variant filters (key=value, comma-separated)
- `dynamic_params` - Dynamic parameters from browser storage (JSON). Shortcode values are limited to mappings already saved in the admin settings.

#### Product Search Widget
- `position` - Position (top-right, top-left, bottom-right, bottom-left)
- `primary_color` - Primary color (hex)
- `hover_color` - Hover color (hex)
- `placeholder` - Placeholder text
- `limit` - Results limit (1-50)
- `variants` - Product variants (none, all, only)
- `variant_filters` - Variant filters (key=value, comma-separated)
- `dynamic_params` - Dynamic parameters from browser storage (JSON). Shortcode values are limited to mappings already saved in the admin settings.
- `mount_mode` - Mount mode (floating, inline)
- `container_selector` - Container selector for inline mode
- `full_width` - Full width for inline mode (1/0)

## File Structure

```
chatsell-widgets/
├── chatsell-widgets.php    # Main plugin file
├── assets/
│   ├── widget.js           # Chat widget JavaScript
│   └── product-search.js   # Product search widget JavaScript
├── languages/              # Translation files
├── readme.txt             # WordPress.org plugin readme
└── README.md              # This file
```

## Dynamic Parameters

The widgets support reading parameter values dynamically from browser storage instead of using static values. This is useful for personalization and user-specific filtering.

### Configuration Format

Use JSON format to configure dynamic parameters:

```json
{
  "location": {
    "source": "localStorage",
    "name": "userLocation"
  },
  "userType": {
    "source": "cookie",
    "name": "user_type"
  },
  "sessionId": {
    "source": "sessionStorage", 
    "name": "session_id"
  }
}
```

### Supported Sources

- **localStorage**: Persistent data across browser sessions
- **sessionStorage**: Data for current browser session only  
- **cookie**: Data stored in browser cookies

### Usage Examples

1. **Admin Configuration**: Add the JSON configuration in the "Dynamic Parameters" field for each widget
2. **Shortcode Override**: Pass `dynamic_params` in shortcodes only to use a subset of mappings already saved in admin settings
3. **Automatic Resolution**: Widgets automatically read values and include them as variant filters

### Example Use Cases

- Location-based product filtering: `localStorage.getItem('userLocation')`
- User type filtering: `document.cookie` user_type value
- Session-specific data: `sessionStorage.getItem('sessionId')`

## Requirements

- WordPress 5.0 or higher
- PHP 7.4 or higher
- ChatSell account and Site ID
- ChatSell backend server running

## Plugin Check

Run WordPress Plugin Check against the installed plugin in Docker:

```bash
docker run --rm --volumes-from wordpress_app --network container:wordpress_app \
  -w /var/www/html --entrypoint php wordpress:cli \
  -d memory_limit=512M /usr/local/bin/wp \
  --skip-plugins=elementor,elementor-pro --skip-themes \
  plugin check chatsell-widgets
```

## Support

For support and documentation, visit [ChatSell.co](https://chatsell.co) or contact us through your ChatSell dashboard.

## License

GPL v2 or later
