@developer.notchatbot/webchat 1.0.9 β 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +172 -612
- package/dist/types.d.ts +21 -0
- package/dist/webchat-bundle.min.js +2641 -2573
- package/dist/webchat-bundle.min.umd.cjs +31 -31
- package/package.json +1 -3
package/README.md
CHANGED
|
@@ -88,647 +88,207 @@ WebChat.initialize({
|
|
|
88
88
|
}
|
|
89
89
|
});
|
|
90
90
|
```
|
|
91
|
+
# π¬ EmbedChat - Chat Embebido
|
|
91
92
|
|
|
92
|
-
|
|
93
|
+
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.
|
|
93
94
|
|
|
94
|
-
|
|
95
|
-
```javascript
|
|
96
|
-
WebChat.initialize({
|
|
97
|
-
primaryColor: "#ff6b6b", // Custom brand color
|
|
98
|
-
// ... other options
|
|
99
|
-
});
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### API Integration
|
|
103
|
-
|
|
104
|
-
The WebChat widget automatically detects the environment and uses the appropriate API endpoints:
|
|
105
|
-
|
|
106
|
-
- **Development** (localhost): `http://localhost:3001/api/webchat`
|
|
107
|
-
- **Production** (any other domain): `https://next.notchatbot.com/api/webchat`
|
|
108
|
-
|
|
109
|
-
```javascript
|
|
110
|
-
WebChat.initialize({
|
|
111
|
-
apiKey: "your-chatbot-uid", // Chatbot UID from your Next.js admin panel
|
|
112
|
-
// Endpoints are automatically configured based on environment
|
|
113
|
-
// No need to specify apiEndpoint manually
|
|
114
|
-
});
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
#### Manual Endpoint Override (Advanced)
|
|
118
|
-
If you need to override the automatic endpoint detection:
|
|
95
|
+
## π¦ Installation and Basic Usage
|
|
119
96
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
console.log('Chat endpoint:', getChatEndpoint());
|
|
125
|
-
console.log('Conversation endpoint:', getConversationEndpoint());
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
### π¬ Initial Message Customization
|
|
129
|
-
Customize the first message your users see when they open the chat:
|
|
130
|
-
|
|
131
|
-
```javascript
|
|
132
|
-
WebChat.initialize({
|
|
133
|
-
title: "MiTienda Support",
|
|
134
|
-
// Custom welcome message with your brand's personality
|
|
135
|
-
initialMessage: "Β‘Hola! π Soy el asistente de MiTienda.\n\nΒΏBuscas algΓΊn producto especΓfico? Β‘Estoy aquΓ para ayudarte!\n\nPuedes preguntarme sobre:\nβ’ Productos disponibles\nβ’ Precios y ofertas\nβ’ EnvΓos y devoluciones\nβ’ Soporte tΓ©cnico\n\nΒΏEn quΓ© puedo ayudarte hoy? π",
|
|
136
|
-
apiKey: "your-api-key"
|
|
137
|
-
});
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### β Close Button Customization
|
|
141
|
-
Customize the appearance of the close button in the chat header:
|
|
97
|
+
### Direct HTML
|
|
98
|
+
```html
|
|
99
|
+
<!-- Element to embed the chat -->
|
|
100
|
+
<div id="my-chat-embed"></div>
|
|
142
101
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
102
|
+
<!-- Load the script -->
|
|
103
|
+
<script src="path/to/webchat.js"></script>
|
|
104
|
+
<script>
|
|
105
|
+
EmbedChat.initialize({
|
|
106
|
+
elementId: "my-chat-embed",
|
|
107
|
+
apiKey: "your-api-key",
|
|
108
|
+
title: "Chat Assistant",
|
|
109
|
+
width: 400,
|
|
110
|
+
height: 500
|
|
111
|
+
});
|
|
112
|
+
</script>
|
|
148
113
|
```
|
|
149
114
|
|
|
150
|
-
|
|
115
|
+
### JavaScript/TypeScript
|
|
151
116
|
```javascript
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
117
|
+
import { EmbedChatAPI } from './webchat';
|
|
118
|
+
|
|
119
|
+
const chatInstance = EmbedChatAPI.initialize({
|
|
120
|
+
elementId: "my-chat-embed",
|
|
121
|
+
apiKey: "your-api-key",
|
|
122
|
+
title: "Chat Assistant",
|
|
123
|
+
width: 400,
|
|
124
|
+
height: 500
|
|
155
125
|
});
|
|
156
126
|
```
|
|
157
127
|
|
|
158
|
-
|
|
159
|
-
```javascript
|
|
160
|
-
WebChat.initialize({
|
|
161
|
-
closeButtonIcon: "custom",
|
|
162
|
-
closeButtonCustomIcon: '<svg viewBox="0 0 24 24" fill="currentColor"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>'
|
|
163
|
-
});
|
|
164
|
-
```
|
|
128
|
+
## βοΈ Complete Configuration
|
|
165
129
|
|
|
166
|
-
|
|
130
|
+
### Required Properties
|
|
167
131
|
```javascript
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
132
|
+
EmbedChatAPI.initialize({
|
|
133
|
+
// REQUIRED
|
|
134
|
+
elementId: "my-chat-embed", // ID of the HTML element to embed the chat
|
|
135
|
+
apiKey: "your-api-key", // API key of the service
|
|
136
|
+
})
|
|
172
137
|
```
|
|
173
138
|
|
|
174
|
-
###
|
|
175
|
-
Control where the chat widget appears on the screen and how much space it has from the edges:
|
|
176
|
-
|
|
177
|
-
#### Bottom Right Position (Default)
|
|
139
|
+
### Propiedades de Contenido
|
|
178
140
|
```javascript
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
141
|
+
EmbedChatAPI.initialize({
|
|
142
|
+
// Textos y contenido
|
|
143
|
+
title: "Chat Assistant", // Title shown in the header
|
|
144
|
+
placeholder: "Type your message...", // Text placeholder of the input
|
|
145
|
+
initialMessage: "Hello! π I'm your chat assistant. How can I help you today?", // First message from the bot
|
|
146
|
+
footerText: "Powered by NotChatBot", // Text of the footer (optional)
|
|
147
|
+
avatar: "https://example.com/avatar.jpg", // URL of the bot's avatar
|
|
148
|
+
})
|
|
185
149
|
```
|
|
186
150
|
|
|
187
|
-
|
|
151
|
+
### Size Properties
|
|
188
152
|
```javascript
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
153
|
+
EmbedChatAPI.initialize({
|
|
154
|
+
// Main dimensions
|
|
155
|
+
width: 400, // Width: number (px) or string ("100%", "50vw")
|
|
156
|
+
height: 500, // Height: number (px) or string ("100%", "80vh")
|
|
157
|
+
|
|
158
|
+
// Size limits
|
|
159
|
+
maxWidth: 600, // Maximum width
|
|
160
|
+
maxHeight: "90vh", // Maximum height (accepts CSS units)
|
|
161
|
+
minWidth: 280, // Minimum width (default: 280px)
|
|
162
|
+
minHeight: 300, // Minimum height (default: 300px)
|
|
163
|
+
})
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### Appearance Properties
|
|
200
167
|
```javascript
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
168
|
+
EmbedChatAPI.initialize({
|
|
169
|
+
// Colores
|
|
170
|
+
primaryColor: "#3b82f6", // Primary color (header, buttons, etc.)
|
|
171
|
+
textColor: "#333333", // Color of the text of the messages
|
|
172
|
+
bubbleUserColor: "#3b82f6", // Color of the background of the user's messages
|
|
173
|
+
chatBackground: "#ffffff", // Color of the chat background
|
|
174
|
+
footerColor: "#f3f4f6", // Color of the footer background
|
|
175
|
+
|
|
176
|
+
// Borders
|
|
177
|
+
borderRadius: 12, // Border radius: number (px) or string
|
|
178
|
+
border: "2px solid #3b82f6", // Custom border (CSS border)
|
|
179
|
+
boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
|
|
180
|
+
|
|
181
|
+
chatTransparent: false, // If true, the chat background is transparent
|
|
182
|
+
})
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Section Control Properties
|
|
210
186
|
```javascript
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
apiKey: "your-api-key"
|
|
216
|
-
});
|
|
187
|
+
EmbedChatAPI.initialize({
|
|
188
|
+
showHeader: true, // Show/hide header (default: true)
|
|
189
|
+
showFooter: true, // Show/hide footer (default: true if footerText is provided)
|
|
190
|
+
})
|
|
217
191
|
```
|
|
218
192
|
|
|
219
|
-
|
|
193
|
+
### Input Configuration
|
|
220
194
|
```javascript
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
195
|
+
EmbedChatAPI.initialize({
|
|
196
|
+
input: {
|
|
197
|
+
backgroundColor: "#ffffff", // Color of the input area background
|
|
198
|
+
inputBorder: "2px solid #e5e7eb", // Border of the input field
|
|
199
|
+
inputBorderRadius: "8px", // Border radius of the input
|
|
200
|
+
iconColor: "#3b82f6" // Color of the send icon
|
|
201
|
+
}
|
|
202
|
+
})
|
|
227
203
|
```
|
|
228
204
|
|
|
229
|
-
###
|
|
230
|
-
The WebChat widget is optimized to minimize API costs:
|
|
231
|
-
|
|
232
|
-
- **Lazy Loading**: Conversation history is only fetched when the chat is opened, not on page load
|
|
233
|
-
- **Smart Caching**: Once loaded, conversation history is cached to avoid duplicate fetches
|
|
234
|
-
- **Conditional Fetching**: Only fetches when a conversation actually exists
|
|
235
|
-
|
|
236
|
-
This ensures users can visit your e-commerce site without triggering unnecessary API calls.
|
|
237
|
-
|
|
238
|
-
### π±π» Device-Specific Configurations
|
|
239
|
-
Configure different positions and margins for mobile and desktop devices:
|
|
240
|
-
|
|
241
|
-
#### Complete Device-Specific Setup
|
|
205
|
+
### Custom CSS
|
|
242
206
|
```javascript
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
position: "bottom-right",
|
|
249
|
-
marginBottom: 20,
|
|
250
|
-
marginSide: 20,
|
|
251
|
-
|
|
252
|
-
// Desktop-specific settings
|
|
253
|
-
desktop: {
|
|
254
|
-
position: "bottom-right",
|
|
255
|
-
marginBottom: 30, // More space on desktop
|
|
256
|
-
marginSide: 40 // More space from edge
|
|
257
|
-
},
|
|
258
|
-
|
|
259
|
-
// Mobile-specific settings
|
|
260
|
-
mobile: {
|
|
261
|
-
position: "bottom-left", // Different position on mobile
|
|
262
|
-
marginBottom: 80, // Avoid mobile navigation bars
|
|
263
|
-
marginSide: 15 // Less space on smaller screens
|
|
207
|
+
EmbedChatAPI.initialize({
|
|
208
|
+
customCSS: `
|
|
209
|
+
#notchatbot-embed-chat {
|
|
210
|
+
/* Your custom styles here */
|
|
211
|
+
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
|
|
264
212
|
}
|
|
265
|
-
|
|
213
|
+
`
|
|
214
|
+
})
|
|
266
215
|
```
|
|
267
216
|
|
|
268
|
-
|
|
217
|
+
### Size Control
|
|
269
218
|
```javascript
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
})
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
|
|
219
|
+
EmbedChatAPI.initialize({
|
|
220
|
+
elementId: "mi-chat",
|
|
221
|
+
|
|
222
|
+
// Main sizes
|
|
223
|
+
width: 400, // Number (px) or string ("100%", "50vw")
|
|
224
|
+
height: 500, // Number (px) or string ("100%", "80vh")
|
|
225
|
+
|
|
226
|
+
// Size limits
|
|
227
|
+
maxWidth: 600, // Maximum size
|
|
228
|
+
maxHeight: "90vh", // Can use CSS units
|
|
229
|
+
minWidth: 280, // Minimum size
|
|
230
|
+
minHeight: 300,
|
|
231
|
+
|
|
232
|
+
// More
|
|
233
|
+
width: "100%", // Occupies the entire width of the container
|
|
234
|
+
height: "50vh", // 50% of the window height
|
|
235
|
+
maxWidth: "500px", // Maximum 500px
|
|
236
|
+
})
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Visual Customization
|
|
291
240
|
```javascript
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
241
|
+
EmbedChatAPI.initialize({
|
|
242
|
+
elementId: "mi-chat",
|
|
243
|
+
|
|
244
|
+
// Borders and effects
|
|
245
|
+
borderRadius: 12, // Border radius in px
|
|
246
|
+
border: "2px solid #3b82f6", // Custom border
|
|
247
|
+
boxShadow: "0 10px 30px rgba(0,0,0,0.2)", // Custom shadow
|
|
248
|
+
|
|
249
|
+
// Section control
|
|
250
|
+
showHeader: true, // Show/hide header (default: true)
|
|
251
|
+
showFooter: true, // Show/hide footer (default: true if footerText is provided)
|
|
252
|
+
|
|
253
|
+
// π Custom CSS
|
|
254
|
+
customCSS: `
|
|
255
|
+
#notchatbot-embed-chat {
|
|
256
|
+
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
|
|
257
|
+
border-radius: 20px !important;
|
|
307
258
|
}
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
-
|
|
319
|
-
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
β βββ ChatWindow.tsx # Chat window container
|
|
345
|
-
β βββ ChatHeader.tsx # Window header with close button
|
|
346
|
-
β βββ MessageList.tsx # Scrollable message list
|
|
347
|
-
β βββ Message.tsx # Individual message bubble
|
|
348
|
-
β βββ MessageInput.tsx # Input field with send button
|
|
349
|
-
β βββ TypingIndicator.tsx # Animated typing dots
|
|
350
|
-
βββ types.ts # TypeScript interfaces and types
|
|
351
|
-
βββ index.tsx # Main entry point (exports WebChat API)
|
|
352
|
-
βββ vite-env.d.ts # Type declarations for Vite
|
|
353
|
-
βββ styles.css # Tailwind CSS directives
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
#### 2. **Adding New Features**
|
|
357
|
-
|
|
358
|
-
**Step 1: Update Types** (if needed)
|
|
359
|
-
```typescript
|
|
360
|
-
// src/types.ts
|
|
361
|
-
export interface NewFeatureProps {
|
|
362
|
-
enabled: boolean;
|
|
363
|
-
config?: SomeConfig;
|
|
364
|
-
}
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
**Step 2: Create/Modify Components**
|
|
368
|
-
```typescript
|
|
369
|
-
// src/components/NewFeature.tsx
|
|
370
|
-
import React from 'react';
|
|
371
|
-
import type { NewFeatureProps } from '../types';
|
|
372
|
-
|
|
373
|
-
const NewFeature: React.FC<NewFeatureProps> = ({ enabled, config }) => {
|
|
374
|
-
// Component logic here
|
|
375
|
-
return (
|
|
376
|
-
<div className="nbc-new-feature">
|
|
377
|
-
{/* Use nbc- prefix for all CSS classes */}
|
|
378
|
-
</div>
|
|
379
|
-
);
|
|
380
|
-
};
|
|
381
|
-
|
|
382
|
-
export default NewFeature;
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
**Step 3: Add to Main Component**
|
|
386
|
-
```typescript
|
|
387
|
-
// src/components/ChatBot.tsx
|
|
388
|
-
import NewFeature from './NewFeature';
|
|
389
|
-
|
|
390
|
-
// Use the new component in ChatBot
|
|
391
|
-
```
|
|
392
|
-
|
|
393
|
-
#### 3. **Styling Guidelines**
|
|
394
|
-
|
|
395
|
-
- **Always use `nbc-` prefix** for CSS classes to avoid conflicts
|
|
396
|
-
- **Use Tailwind utilities** whenever possible
|
|
397
|
-
- **Follow the existing pattern** for consistent styling
|
|
398
|
-
|
|
399
|
-
```tsx
|
|
400
|
-
// β
Good - uses nbc- prefix
|
|
401
|
-
<div className="nbc-bg-blue-500 nbc-text-white nbc-p-4">
|
|
402
|
-
|
|
403
|
-
// β Bad - no prefix, will conflict with host site
|
|
404
|
-
<div className="bg-blue-500 text-white p-4">
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
#### 4. **TypeScript Best Practices**
|
|
408
|
-
|
|
409
|
-
- **Define interfaces** for all component props
|
|
410
|
-
- **Use strict typing** for functions and variables
|
|
411
|
-
- **Leverage IntelliSense** for better development experience
|
|
412
|
-
|
|
413
|
-
```typescript
|
|
414
|
-
// β
Good - strict typing
|
|
415
|
-
const handleMessage = (message: string): void => {
|
|
416
|
-
// Function implementation
|
|
417
|
-
};
|
|
418
|
-
|
|
419
|
-
// β Bad - no typing
|
|
420
|
-
const handleMessage = (message) => {
|
|
421
|
-
// Function implementation
|
|
422
|
-
};
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
### ποΈ Building & Compilation
|
|
426
|
-
|
|
427
|
-
#### Development Build
|
|
428
|
-
```bash
|
|
429
|
-
# Start development server with hot reload
|
|
430
|
-
pnpm dev
|
|
431
|
-
|
|
432
|
-
# Access at: http://localhost:3000
|
|
433
|
-
# Changes are reflected immediately
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
#### Production Build
|
|
437
|
-
```bash
|
|
438
|
-
# Build for production (TypeScript compilation + bundling)
|
|
439
|
-
pnpm build
|
|
440
|
-
|
|
441
|
-
# Output: dist/webchat-bundle.min.umd.cjs (single file)
|
|
442
|
-
# Size: ~159KB (50KB gzipped)
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
#### Build Process Explanation
|
|
446
|
-
1. **TypeScript Compilation** (`tsc`) - Type checking and compilation
|
|
447
|
-
2. **Vite Bundling** - Bundles React, CSS, and all dependencies
|
|
448
|
-
3. **CSS Injection** - Inlines CSS into JavaScript for single-file output
|
|
449
|
-
4. **Minification** - Optimizes and compresses the output
|
|
450
|
-
|
|
451
|
-
### π§ͺ Testing the Compiled Version
|
|
452
|
-
|
|
453
|
-
#### Option 1: Preview Server
|
|
454
|
-
```bash
|
|
455
|
-
# Build and start preview server
|
|
456
|
-
pnpm build
|
|
457
|
-
pnpm preview
|
|
458
|
-
|
|
459
|
-
# Access at: http://localhost:4173
|
|
460
|
-
# Tests the actual production build
|
|
461
|
-
```
|
|
462
|
-
|
|
463
|
-
#### Option 2: Local Testing
|
|
464
|
-
```bash
|
|
465
|
-
# After building, test locally
|
|
466
|
-
pnpm build
|
|
467
|
-
|
|
468
|
-
# Open example/production.html in browser
|
|
469
|
-
# Or serve with any static file server
|
|
470
|
-
python3 -m http.server 8000
|
|
471
|
-
# Then visit: http://localhost:8000/example/production.html
|
|
472
|
-
```
|
|
473
|
-
|
|
474
|
-
#### Option 3: Integration Testing
|
|
475
|
-
Create a test HTML file:
|
|
476
|
-
```html
|
|
477
|
-
<!DOCTYPE html>
|
|
478
|
-
<html>
|
|
479
|
-
<head>
|
|
480
|
-
<title>Widget Test</title>
|
|
481
|
-
</head>
|
|
482
|
-
<body>
|
|
483
|
-
<h1>Testing WebChat Widget</h1>
|
|
484
|
-
<div id="chat-test"></div>
|
|
485
|
-
|
|
486
|
-
<!-- Load your built widget -->
|
|
487
|
-
<script src="./dist/webchat-bundle.min.umd.cjs"></script>
|
|
488
|
-
<script>
|
|
489
|
-
// Test the widget
|
|
490
|
-
WebChat.initialize({
|
|
491
|
-
elementId: "chat-test",
|
|
492
|
-
title: "Test Chat",
|
|
493
|
-
placeholder: "Test message...",
|
|
494
|
-
primaryColor: "#007bff"
|
|
495
|
-
});
|
|
496
|
-
</script>
|
|
497
|
-
</body>
|
|
498
|
-
</html>
|
|
499
|
-
```
|
|
500
|
-
|
|
501
|
-
### π¦ Publishing to npm
|
|
502
|
-
|
|
503
|
-
#### 1. Prepare for Publishing
|
|
504
|
-
```bash
|
|
505
|
-
# 1. Update version in package.json
|
|
506
|
-
npm version patch # or minor, major
|
|
507
|
-
|
|
508
|
-
# 2. Build the production version
|
|
509
|
-
pnpm build
|
|
510
|
-
|
|
511
|
-
# 3. Test the build
|
|
512
|
-
pnpm preview
|
|
513
|
-
```
|
|
514
|
-
|
|
515
|
-
#### 2. Configure package.json for npm
|
|
516
|
-
```json
|
|
517
|
-
{
|
|
518
|
-
"name": "@yourorg/webchat-widget",
|
|
519
|
-
"version": "1.0.0",
|
|
520
|
-
"description": "Embeddable React TypeScript chatbot widget",
|
|
521
|
-
"main": "dist/webchat-bundle.min.umd.cjs",
|
|
522
|
-
"types": "dist/types/index.d.ts",
|
|
523
|
-
"files": [
|
|
524
|
-
"dist",
|
|
525
|
-
"README.md"
|
|
526
|
-
],
|
|
527
|
-
"keywords": ["chatbot", "widget", "react", "typescript", "embeddable"],
|
|
528
|
-
"repository": {
|
|
529
|
-
"type": "git",
|
|
530
|
-
"url": "https://github.com/yourorg/webchat-widget.git"
|
|
531
|
-
},
|
|
532
|
-
"publishConfig": {
|
|
533
|
-
"access": "public"
|
|
534
|
-
}
|
|
535
|
-
}
|
|
536
|
-
```
|
|
537
|
-
|
|
538
|
-
#### 3. Publish to npm
|
|
539
|
-
```bash
|
|
540
|
-
# 1. Login to npm (if not already)
|
|
541
|
-
npm login
|
|
542
|
-
|
|
543
|
-
# 2. Publish the package
|
|
544
|
-
npm publish
|
|
545
|
-
|
|
546
|
-
# 3. Verify publication
|
|
547
|
-
npm view @yourorg/webchat-widget
|
|
548
|
-
```
|
|
549
|
-
|
|
550
|
-
#### 4. Using Published Package
|
|
551
|
-
```html
|
|
552
|
-
<!-- From npm CDN -->
|
|
553
|
-
<script src="https://unpkg.com/@yourorg/webchat-widget/dist/webchat-bundle.min.umd.cjs"></script>
|
|
554
|
-
|
|
555
|
-
<!-- Or install via npm -->
|
|
556
|
-
npm install @yourorg/webchat-widget
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
### π Hosting on unpkg
|
|
560
|
-
|
|
561
|
-
#### Automatic unpkg Hosting
|
|
562
|
-
Once published to npm, your package is automatically available on unpkg:
|
|
563
|
-
|
|
564
|
-
```html
|
|
565
|
-
<!-- Latest version -->
|
|
566
|
-
<script src="https://unpkg.com/@yourorg/webchat-widget"></script>
|
|
567
|
-
|
|
568
|
-
<!-- Specific version -->
|
|
569
|
-
<script src="https://unpkg.com/@yourorg/webchat-widget@1.0.0"></script>
|
|
570
|
-
|
|
571
|
-
<!-- Direct file access -->
|
|
572
|
-
<script src="https://unpkg.com/@yourorg/webchat-widget/dist/webchat-bundle.min.umd.cjs"></script>
|
|
573
|
-
```
|
|
574
|
-
|
|
575
|
-
#### unpkg URLs Explained
|
|
576
|
-
- `https://unpkg.com/package-name` - Latest version, main file
|
|
577
|
-
- `https://unpkg.com/package-name@version` - Specific version
|
|
578
|
-
- `https://unpkg.com/package-name/file-path` - Direct file access
|
|
579
|
-
- `https://unpkg.com/package-name@version/file-path` - Version + file
|
|
580
|
-
|
|
581
|
-
#### Real-world Integration Example
|
|
582
|
-
```html
|
|
583
|
-
<!DOCTYPE html>
|
|
584
|
-
<html lang="en">
|
|
585
|
-
<head>
|
|
586
|
-
<meta charset="UTF-8">
|
|
587
|
-
<title>My Website with Chat</title>
|
|
588
|
-
</head>
|
|
589
|
-
<body>
|
|
590
|
-
<h1>Welcome to My Website</h1>
|
|
591
|
-
<p>Content goes here...</p>
|
|
592
|
-
|
|
593
|
-
<!-- Chat widget integration -->
|
|
594
|
-
<div id="customer-chat"></div>
|
|
595
|
-
|
|
596
|
-
<!-- Load from unpkg -->
|
|
597
|
-
<script src="https://unpkg.com/@yourorg/webchat-widget@latest"></script>
|
|
598
|
-
<script>
|
|
599
|
-
WebChat.initialize({
|
|
600
|
-
elementId: "customer-chat",
|
|
601
|
-
title: "Customer Support",
|
|
602
|
-
placeholder: "How can we help you?",
|
|
603
|
-
primaryColor: "#007bff",
|
|
604
|
-
apiEndpoint: "https://your-api.com/chat",
|
|
605
|
-
apiKey: "your-api-key"
|
|
606
|
-
});
|
|
607
|
-
</script>
|
|
608
|
-
</body>
|
|
609
|
-
</html>
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
### π Deployment Workflow Summary
|
|
613
|
-
|
|
614
|
-
```bash
|
|
615
|
-
# Complete workflow from development to deployment
|
|
616
|
-
git checkout -b feature/new-feature
|
|
617
|
-
# ... make changes ...
|
|
618
|
-
git commit -m "Add new feature"
|
|
619
|
-
git push origin feature/new-feature
|
|
620
|
-
# ... create PR, review, merge ...
|
|
621
|
-
|
|
622
|
-
# Deployment
|
|
623
|
-
git checkout main
|
|
624
|
-
git pull origin main
|
|
625
|
-
npm version patch
|
|
626
|
-
pnpm build
|
|
627
|
-
npm publish
|
|
628
|
-
git push --tags
|
|
629
|
-
|
|
630
|
-
# Your widget is now available at:
|
|
631
|
-
# https://unpkg.com/@yourorg/webchat-widget@latest
|
|
632
|
-
```
|
|
633
|
-
|
|
634
|
-
### π οΈ Troubleshooting
|
|
635
|
-
|
|
636
|
-
#### Common Issues
|
|
637
|
-
|
|
638
|
-
**TypeScript Errors**
|
|
639
|
-
```bash
|
|
640
|
-
# Check TypeScript errors
|
|
641
|
-
pnpm build # Will show TS errors
|
|
642
|
-
|
|
643
|
-
# Fix common issues:
|
|
644
|
-
# 1. Missing types - add to src/types.ts
|
|
645
|
-
# 2. Import errors - check file extensions (.tsx)
|
|
646
|
-
# 3. Strict mode - follow TypeScript strict rules
|
|
647
|
-
```
|
|
648
|
-
|
|
649
|
-
**Build Issues**
|
|
650
|
-
```bash
|
|
651
|
-
# Clear cache and rebuild
|
|
652
|
-
rm -rf node_modules dist
|
|
653
|
-
pnpm install
|
|
654
|
-
pnpm build
|
|
655
|
-
```
|
|
656
|
-
|
|
657
|
-
**CSS Conflicts**
|
|
658
|
-
```typescript
|
|
659
|
-
// Always use nbc- prefix in className
|
|
660
|
-
className="nbc-bg-blue-500 nbc-text-white"
|
|
661
|
-
```
|
|
662
|
-
|
|
663
|
-
**unpkg Caching**
|
|
664
|
-
```bash
|
|
665
|
-
# Force cache refresh
|
|
666
|
-
https://unpkg.com/@yourorg/webchat-widget?t=timestamp
|
|
667
|
-
```
|
|
668
|
-
|
|
669
|
-
## π οΈ Development
|
|
670
|
-
|
|
671
|
-
### Prerequisites
|
|
672
|
-
- Node.js 18+ (for modern React and TypeScript)
|
|
673
|
-
- pnpm 8+ (recommended package manager)
|
|
674
|
-
|
|
675
|
-
### Setup
|
|
676
|
-
```bash
|
|
677
|
-
# Clone the repository
|
|
678
|
-
git clone https://github.com/your-username/webchat-widget.git
|
|
679
|
-
cd webchat-widget
|
|
680
|
-
|
|
681
|
-
# Install dependencies with pnpm
|
|
682
|
-
pnpm install
|
|
683
|
-
|
|
684
|
-
# Start development server with hot reload
|
|
685
|
-
pnpm dev
|
|
686
|
-
```
|
|
687
|
-
|
|
688
|
-
### Build for Production
|
|
689
|
-
```bash
|
|
690
|
-
pnpm build
|
|
691
|
-
```
|
|
692
|
-
|
|
693
|
-
This creates a single optimized file in the `dist/` directory:
|
|
694
|
-
- `webchat-bundle.min.umd.cjs` (159KB / 50KB gzipped) - Complete TypeScript bundle with React, Tailwind CSS, and all functionality
|
|
695
|
-
|
|
696
|
-
### Preview Production Build
|
|
697
|
-
```bash
|
|
698
|
-
pnpm preview
|
|
699
|
-
```
|
|
700
|
-
|
|
701
|
-
## π Project Structure
|
|
702
|
-
|
|
703
|
-
```
|
|
704
|
-
webchat-widget/
|
|
705
|
-
βββ src/
|
|
706
|
-
β βββ components/ # React TypeScript components
|
|
707
|
-
β β βββ ChatBot.tsx # Main chatbot component
|
|
708
|
-
β β βββ ChatButton.tsx # Toggle button
|
|
709
|
-
β β βββ ChatWindow.tsx # Chat window container
|
|
710
|
-
β β βββ ChatHeader.tsx # Window header
|
|
711
|
-
β β βββ MessageList.tsx # Message list with scroll
|
|
712
|
-
β β βββ Message.tsx # Individual message
|
|
713
|
-
β β βββ MessageInput.tsx # Input field
|
|
714
|
-
β β βββ TypingIndicator.tsx # Typing animation
|
|
715
|
-
β βββ types.ts # TypeScript interfaces and types
|
|
716
|
-
β βββ index.tsx # Main entry point (auto-injects CSS)
|
|
717
|
-
β βββ vite-env.d.ts # Vite environment types
|
|
718
|
-
β βββ styles.css # Tailwind directives
|
|
719
|
-
βββ example.html # Development example
|
|
720
|
-
βββ example/
|
|
721
|
-
β βββ production.html # Production example
|
|
722
|
-
βββ dist/ # Built files
|
|
723
|
-
β βββ webchat-bundle.min.umd.cjs # Single file TypeScript bundle
|
|
724
|
-
βββ tsconfig.json # TypeScript configuration
|
|
725
|
-
βββ tsconfig.node.json # Node TypeScript configuration
|
|
726
|
-
βββ tailwind.config.js # Tailwind configuration
|
|
727
|
-
βββ postcss.config.js # PostCSS configuration
|
|
728
|
-
βββ vite.config.js # Vite configuration
|
|
729
|
-
βββ package.json # pnpm + React + TypeScript dependencies
|
|
730
|
-
```
|
|
731
|
-
|
|
732
|
-
## π License
|
|
733
|
-
|
|
734
|
-
MIT License - see the [LICENSE](LICENSE) file for details.
|
|
259
|
+
`
|
|
260
|
+
})
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
## π Complete Property Reference
|
|
264
|
+
|
|
265
|
+
### EmbedChatConfig Configuration Table
|
|
266
|
+
|
|
267
|
+
| Property | Type | Required | Default | Description |
|
|
268
|
+
|-----------|------|-----------|---------|-------------|
|
|
269
|
+
| `elementId` | `string` | β
| - | ID of the HTML element where the chat will be mounted |
|
|
270
|
+
| `apiKey` | `string` | β
| - | API key for the chat service |
|
|
271
|
+
| `title` | `string` | β | `"Chat"` | Title shown in the header of the chat |
|
|
272
|
+
| `placeholder` | `string` | β | `"Type your message..."` | Text placeholder of the input field |
|
|
273
|
+
| `primaryColor` | `string` | β | `"#3b82f6"` | Primary color (header, buttons, links) |
|
|
274
|
+
| `avatar` | `string` | β | - | URL of the bot's avatar (optional) |
|
|
275
|
+
| `initialMessage` | `string` | β | - | First message shown by the bot |
|
|
276
|
+
| `footerText` | `string` | β | - | Text of the footer (if provided, it is shown) |
|
|
277
|
+
| `width` | `string \| number` | β | `"100%"` | Width of the chat (px or CSS units) |
|
|
278
|
+
| `height` | `string \| number` | β | `400` | Height of the chat (px or CSS units) |
|
|
279
|
+
| `maxWidth` | `string \| number` | β | `"100%"` | Maximum width of the chat |
|
|
280
|
+
| `maxHeight` | `string \| number` | β | `"100vh"` | Maximum height of the chat |
|
|
281
|
+
| `minWidth` | `string \| number` | β | `280` | Minimum width of the chat |
|
|
282
|
+
| `minHeight` | `string \| number` | β | `300` | Minimum height of the chat |
|
|
283
|
+
| `showHeader` | `boolean` | β | `true` | Show/hide the header |
|
|
284
|
+
| `showFooter` | `boolean` | β | `true` | Show/hide the footer (if footerText is provided) |
|
|
285
|
+
| `borderRadius` | `string \| number` | β | `12` | Border radius of the container |
|
|
286
|
+
| `border` | `string` | β | `"1px solid #e5e7eb"` | Border of the container (CSS border) |
|
|
287
|
+
| `boxShadow` | `string` | β | `"0 10px 25px..."` | Shadow of the container |
|
|
288
|
+
| `chatTransparent` | `boolean` | β | `false` | If true, the chat background is transparent |
|
|
289
|
+
| `chatBackground` | `string` | β | `"#ffffff"` | Color of the chat background |
|
|
290
|
+
| `textColor` | `string` | β | - | Color of the text of the messages |
|
|
291
|
+
| `bubbleUserColor` | `string` | β | - | Color of the background of the user's messages |
|
|
292
|
+
| `footerColor` | `string` | β | - | Color of the footer background |
|
|
293
|
+
| `input` | `EmbedChatInputConfig` | β | - | Specific configuration of the input |
|
|
294
|
+
| `customCSS` | `string` | β | - | Custom CSS for the chat |
|