@developer.notchatbot/webchat
Version:
A beautiful React chatbot widget with single-file bundle
295 lines (253 loc) • 11.3 kB
Markdown
# 🔷 WebChat Widget
A beautiful, embeddable chatbot widget built with **React**, **TypeScript**, **Vite**, **pnpm** and **Tailwind CSS** that can be easily integrated into any website with **just one file**.
## ✨ Features
- **📦 Single File Bundle**: Everything in one file - no separate CSS needed!
- **🔷 TypeScript**: Full type safety with strict typing and excellent IntelliSense
- **⚛️ React 18**: Component-based architecture for maintainability
- **🎨 Tailwind CSS**: Utility-first styling with prefixed classes (`ncb-`)
- **⚡ Vite**: Lightning-fast development and optimized builds
- **📦 pnpm**: Efficient package management and faster installs
- **🔧 Easy Integration**: Add to any website with just one script tag
- **🎨 Modern Design**: Beautiful, responsive UI that works on all devices
- **🛠️ Customizable**: Configure colors, text, and behavior to match your brand
- **✨ Smooth Animations**: Typing indicators and smooth transitions
- **📱 Mobile Responsive**: Optimized for mobile and desktop
- **🔌 API Ready**: Built-in support for chat API integration
- **🚫 Zero Conflicts**: Prefixed CSS classes prevent style conflicts
- **🛡️ Type Safe**: Catch errors at compile time with TypeScript
## 📦 Quick Start
### 1. Add the widget to your website
```html
<div id="webchat-component"></div>
<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
<script>
WebChat.initialize({
title: "Customer Support",
placeholder: "Ask us anything...",
primaryColor: "#667eea"
});
</script>
```
### 2. That's it! 🎉
The chatbot button will appear in the bottom-right corner of your page. CSS is automatically injected!
## ⚙️ Configuration Options
```typescript
interface WebChatConfig {
title?: string; // Chat window title
placeholder?: string; // Input placeholder text
primaryColor?: string; // Primary theme color
apiKey?: string; // Your chatbot UID (required for API)
position?: 'bottom-right' | 'bottom-left'; // Widget position
initialMessage?: string; // Custom initial bot message
closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
closeButtonText?: string; // Text for close button (when type is 'text')
closeButtonCustomIcon?: string; // Custom icon SVG or URL (when type is 'custom')
marginBottom?: number; // Distance from bottom edge in pixels (default: 16)
marginSide?: number; // Distance from left/right edge in pixels (default: 16)
mobile?: WebChatPositionConfig; // Mobile-specific position settings
desktop?: WebChatPositionConfig; // Desktop-specific position settings
}
interface WebChatPositionConfig {
position?: 'bottom-right' | 'bottom-left';
marginBottom?: number;
marginSide?: number;
}
WebChat.initialize({
title: "Chat Assistant",
placeholder: "Type your message...",
primaryColor: "#007bff",
apiKey: "your-chatbot-uid", // Chatbot UID from admin panel
position: "bottom-right",
initialMessage: "¡Hola! 👋 Soy tu asistente virtual. ¿En qué puedo ayudarte hoy?",
closeButtonIcon: "default", // or "text" or "custom"
marginBottom: 20, // Distance from bottom edge (default: 16px)
marginSide: 20, // Distance from side edge (default: 16px)
// Device-specific overrides
mobile: {
position: "bottom-left",
marginBottom: 80,
marginSide: 15
},
desktop: {
position: "bottom-right",
marginBottom: 30,
marginSide: 30
}
});
```
# 💬 EmbedChat - Chat Embebido
EmbedChat allows you to integrate a complete chat system directly into any element of your web page, with full control over size, position, and style.
## 📦 Installation and Basic Usage
### Direct HTML
```html
<!-- Element to embed the chat -->
<div id="my-chat-embed"></div>
<!-- Load the script -->
<script src="path/to/webchat.js"></script>
<script>
EmbedChat.initialize({
elementId: "my-chat-embed",
apiKey: "your-api-key",
title: "Chat Assistant",
width: 400,
height: 500
});
</script>
```
### JavaScript/TypeScript
```javascript
import { EmbedChatAPI } from './webchat';
const chatInstance = EmbedChatAPI.initialize({
elementId: "my-chat-embed",
apiKey: "your-api-key",
title: "Chat Assistant",
width: 400,
height: 500
});
```
## ⚙️ Complete Configuration
### Required Properties
```javascript
EmbedChatAPI.initialize({
// REQUIRED
elementId: "my-chat-embed", // ID of the HTML element to embed the chat
apiKey: "your-api-key", // API key of the service
})
```
### Propiedades de Contenido
```javascript
EmbedChatAPI.initialize({
// Textos y contenido
title: "Chat Assistant", // Title shown in the header
placeholder: "Type your message...", // Text placeholder of the input
initialMessage: "Hello! 👋 I'm your chat assistant. How can I help you today?", // First message from the bot
footerText: "Powered by NotChatBot", // Text of the footer (optional)
avatar: "https://example.com/avatar.jpg", // URL of the bot's avatar
})
```
### Size Properties
```javascript
EmbedChatAPI.initialize({
// Main dimensions
width: 400, // Width: number (px) or string ("100%", "50vw")
height: 500, // Height: number (px) or string ("100%", "80vh")
// Size limits
maxWidth: 600, // Maximum width
maxHeight: "90vh", // Maximum height (accepts CSS units)
minWidth: 280, // Minimum width (default: 280px)
minHeight: 300, // Minimum height (default: 300px)
})
```
### Appearance Properties
```javascript
EmbedChatAPI.initialize({
// Colores
primaryColor: "#3b82f6", // Primary color (header, buttons, etc.)
textColor: "#333333", // Color of the text of the messages
bubbleUserColor: "#3b82f6", // Color of the background of the user's messages
chatBackground: "#ffffff", // Color of the chat background
footerColor: "#f3f4f6", // Color of the footer background
// Borders
borderRadius: 12, // Border radius: number (px) or string
border: "2px solid #3b82f6", // Custom border (CSS border)
boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
chatTransparent: false, // If true, the chat background is transparent
})
```
### Section Control Properties
```javascript
EmbedChatAPI.initialize({
showHeader: true, // Show/hide header (default: true)
showFooter: true, // Show/hide footer (default: true if footerText is provided)
})
```
### Input Configuration
```javascript
EmbedChatAPI.initialize({
input: {
backgroundColor: "#ffffff", // Color of the input area background
inputBorder: "2px solid #e5e7eb", // Border of the input field
inputBorderRadius: "8px", // Border radius of the input
iconColor: "#3b82f6" // Color of the send icon
}
})
```
### Custom CSS
```javascript
EmbedChatAPI.initialize({
customCSS: `
#notchatbot-embed-chat {
/* Your custom styles here */
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
}
`
})
```
### Size Control
```javascript
EmbedChatAPI.initialize({
elementId: "mi-chat",
// Main sizes
width: 400, // Number (px) or string ("100%", "50vw")
height: 500, // Number (px) or string ("100%", "80vh")
// Size limits
maxWidth: 600, // Maximum size
maxHeight: "90vh", // Can use CSS units
minWidth: 280, // Minimum size
minHeight: 300,
// More
width: "100%", // Occupies the entire width of the container
height: "50vh", // 50% of the window height
maxWidth: "500px", // Maximum 500px
})
```
### Visual Customization
```javascript
EmbedChatAPI.initialize({
elementId: "mi-chat",
// Borders and effects
borderRadius: 12, // Border radius in px
border: "2px solid #3b82f6", // Custom border
boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
// Section control
showHeader: true, // Show/hide header (default: true)
showFooter: true, // Show/hide footer (default: true if footerText is provided)
// 🆕 Custom CSS
customCSS: `
#notchatbot-embed-chat {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
border-radius: 20px !important;
}
`
})
```
## 📋 Complete Property Reference
### EmbedChatConfig Configuration Table
| Property | Type | Required | Default | Description |
|-----------|------|-----------|---------|-------------|
| `elementId` | `string` | ✅ | - | ID of the HTML element where the chat will be mounted |
| `apiKey` | `string` | ✅ | - | API key for the chat service |
| `title` | `string` | ❌ | `"Chat"` | Title shown in the header of the chat |
| `placeholder` | `string` | ❌ | `"Type your message..."` | Text placeholder of the input field |
| `primaryColor` | `string` | ❌ | `"#3b82f6"` | Primary color (header, buttons, links) |
| `avatar` | `string` | ❌ | - | URL of the bot's avatar (optional) |
| `initialMessage` | `string` | ❌ | - | First message shown by the bot |
| `footerText` | `string` | ❌ | - | Text of the footer (if provided, it is shown) |
| `width` | `string \| number` | ❌ | `"100%"` | Width of the chat (px or CSS units) |
| `height` | `string \| number` | ❌ | `400` | Height of the chat (px or CSS units) |
| `maxWidth` | `string \| number` | ❌ | `"100%"` | Maximum width of the chat |
| `maxHeight` | `string \| number` | ❌ | `"100vh"` | Maximum height of the chat |
| `minWidth` | `string \| number` | ❌ | `280` | Minimum width of the chat |
| `minHeight` | `string \| number` | ❌ | `300` | Minimum height of the chat |
| `showHeader` | `boolean` | ❌ | `true` | Show/hide the header |
| `showFooter` | `boolean` | ❌ | `true` | Show/hide the footer (if footerText is provided) |
| `borderRadius` | `string \| number` | ❌ | `12` | Border radius of the container |
| `border` | `string` | ❌ | `"1px solid #e5e7eb"` | Border of the container (CSS border) |
| `boxShadow` | `string` | ❌ | `"0 10px 25px..."` | Shadow of the container |
| `chatTransparent` | `boolean` | ❌ | `false` | If true, the chat background is transparent |
| `chatBackground` | `string` | ❌ | `"#ffffff"` | Color of the chat background |
| `textColor` | `string` | ❌ | - | Color of the text of the messages |
| `bubbleUserColor` | `string` | ❌ | - | Color of the background of the user's messages |
| `footerColor` | `string` | ❌ | - | Color of the footer background |
| `input` | `EmbedChatInputConfig` | ❌ | - | Specific configuration of the input |
| `customCSS` | `string` | ❌ | - | Custom CSS for the chat |