@headwai/chat-bubble 3.0.5 → 6.0.0
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.dev.md +283 -31
- package/README.md +144 -125
- package/dist-widget/chat-bubble.js +85 -85
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -16,40 +16,42 @@ Add the Headwai Chat Bubble to the respective .html file.
|
|
|
16
16
|
```html
|
|
17
17
|
<!DOCTYPE html>
|
|
18
18
|
<html>
|
|
19
|
-
<head>
|
|
19
|
+
<head>
|
|
20
20
|
<title>Customer Website</title>
|
|
21
21
|
<!-- Configure via global variables -->
|
|
22
22
|
<script>
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
};
|
|
23
|
+
// Runtime configuration override
|
|
24
|
+
window.HEADWAI_CHAT_BUBBLE_CONFIG = {
|
|
25
|
+
apiUrl: 'https://company.localchat.at', // required
|
|
26
|
+
modelId: 'customer-support-model-id', // required
|
|
27
|
+
maxMessages: 0, // optional - 0 means unlimited
|
|
28
|
+
placeholderText: 'Ask your question here!', // optional - default: 'Enter your questions here'
|
|
29
|
+
faviconPath: 'https://cdn.company.at/icons/favicon.svg', // optional - default: '/icons/favicon.svg'
|
|
30
|
+
initialMessage: 'Hey! My name is Supporty, how can I help you?', // optional - default: 'Hey, how can I help you?'
|
|
31
|
+
chatTitle: 'Customer Support', // optional - default: 'Headwai Chat Bubble'
|
|
32
|
+
userMessageBackgroundColor: '#007bff', // optional - default: '#007bff'
|
|
33
|
+
aiMessageBackgroundColor: '#f1f3f4', // optional - default: '#f1f3f4'
|
|
34
|
+
userMessageTextColor: '#000000', // optional - default: '#000000'
|
|
35
|
+
aiMessageTextColor: '#000000', // optional - default: '#000000'
|
|
36
|
+
faviconBackgroundColor: '#667eea', // optional - default: '#667eea'
|
|
37
|
+
fontFamily: '"Inter", system-ui, sans-serif', // optional - default: 'inherit'
|
|
38
|
+
fontSize: '16px', // optional - default: 'inherit'
|
|
39
|
+
};
|
|
41
40
|
</script>
|
|
42
|
-
</head>
|
|
43
|
-
<body>
|
|
41
|
+
</head>
|
|
42
|
+
<body>
|
|
44
43
|
<!-- Your existing content -->
|
|
45
|
-
|
|
44
|
+
|
|
46
45
|
<!-- Chat Bubble Integration - Auto-initializes! -->
|
|
47
46
|
<div id="chat-bubble-container"></div>
|
|
48
|
-
|
|
47
|
+
|
|
49
48
|
<!-- Include from jsDelivr CDN -->
|
|
50
|
-
<link
|
|
49
|
+
<link
|
|
50
|
+
rel="stylesheet"
|
|
51
|
+
href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css"
|
|
52
|
+
/>
|
|
51
53
|
<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
|
|
52
|
-
</body>
|
|
54
|
+
</body>
|
|
53
55
|
</html>
|
|
54
56
|
```
|
|
55
57
|
|
|
@@ -58,61 +60,69 @@ Get the desired version of the JavaScript and CSS in your `<body>`.
|
|
|
58
60
|
|
|
59
61
|
```html
|
|
60
62
|
<!-- Latest version -->
|
|
61
|
-
<link
|
|
63
|
+
<link
|
|
64
|
+
rel="stylesheet"
|
|
65
|
+
href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css"
|
|
66
|
+
/>
|
|
62
67
|
<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
|
|
63
68
|
|
|
64
69
|
<!-- Specific version -->
|
|
65
|
-
<link
|
|
70
|
+
<link
|
|
71
|
+
rel="stylesheet"
|
|
72
|
+
href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.css"
|
|
73
|
+
/>
|
|
66
74
|
<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.js"></script>
|
|
67
75
|
```
|
|
68
76
|
|
|
69
77
|
Place the Headwai Chat Bubble into the `<body>` tag. It will apear on the right corner of your website.
|
|
70
78
|
|
|
71
|
-
|
|
72
79
|
#### Multiple Headwai Chat Bubbles
|
|
73
80
|
|
|
74
81
|
For multiple instances use data attributes of the `<div>` tag for configuration instead.
|
|
75
82
|
|
|
76
83
|
```html
|
|
77
84
|
<!-- Chat bubble with specific configuration -->
|
|
78
|
-
<div
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
85
|
+
<div
|
|
86
|
+
data-chat-bubble
|
|
87
|
+
data-chat-bubble-api-url="https://company.localchat.at"
|
|
88
|
+
data-chat-bubble-model-id="customer-support-model-id"
|
|
89
|
+
data-chat-bubble-max-messages="0"
|
|
90
|
+
data-chat-bubble-placeholder-text="Ask your question here!"
|
|
91
|
+
data-chat-bubble-favicon-path="https://cdn.company.at/icons/favicon.svg"
|
|
92
|
+
data-chat-bubble-initial-message="Hey! My name is Supporty, how can I help you?"
|
|
93
|
+
data-chat-bubble-chat-title="Customer Support"
|
|
94
|
+
data-chat-bubble-user-message-background-color="#007bff"
|
|
95
|
+
data-chat-bubble-ai-message-background-color="#f1f3f4"
|
|
96
|
+
data-chat-bubble-user-message-text-color="#000000"
|
|
97
|
+
data-chat-bubble-ai-message-text-color="#000000"
|
|
98
|
+
data-chat-bubble-favicon-background-color="#667eea"
|
|
99
|
+
data-chat-bubble-font-family='"Inter", system-ui, sans-serif'
|
|
100
|
+
data-chat-bubble-font-size="16px"
|
|
101
|
+
></div>
|
|
95
102
|
|
|
96
103
|
<!-- Another chat bubble with different config -->
|
|
97
|
-
<div
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
<link
|
|
104
|
+
<div
|
|
105
|
+
data-chat-bubble
|
|
106
|
+
data-chat-bubble-api-url="https://company.localchat.at"
|
|
107
|
+
data-chat-bubble-model-id="FAQ-model-id"
|
|
108
|
+
data-chat-bubble-max-messages="10"
|
|
109
|
+
data-chat-bubble-placeholder-text="Ask about our FAQ..."
|
|
110
|
+
data-chat-bubble-favicon-path="https://cdn.company.at/icons/faq-icon.svg"
|
|
111
|
+
data-chat-bubble-initial-message="Hello! I can help you with frequently asked questions."
|
|
112
|
+
data-chat-bubble-chat-title="FAQ Assistant"
|
|
113
|
+
data-chat-bubble-user-message-background-color="#28a745"
|
|
114
|
+
data-chat-bubble-ai-message-background-color="#e9ecef"
|
|
115
|
+
data-chat-bubble-user-message-text-color="#ffffff"
|
|
116
|
+
data-chat-bubble-ai-message-text-color="#495057"
|
|
117
|
+
data-chat-bubble-favicon-background-color="#28a745"
|
|
118
|
+
data-chat-bubble-font-family='"Roboto", sans-serif'
|
|
119
|
+
data-chat-bubble-font-size="14px"
|
|
120
|
+
></div>
|
|
121
|
+
|
|
122
|
+
<link
|
|
123
|
+
rel="stylesheet"
|
|
124
|
+
href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css"
|
|
125
|
+
/>
|
|
116
126
|
<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
|
|
117
127
|
```
|
|
118
128
|
|
|
@@ -123,159 +133,167 @@ The Headwai Chat Bubble can be configured using either the global `window.DEEP_C
|
|
|
123
133
|
### Required Configuration
|
|
124
134
|
|
|
125
135
|
#### `apiUrl`
|
|
136
|
+
|
|
126
137
|
**Type:** `string` | **Required:** ✅
|
|
127
138
|
The base URL of your LocalChat API endpoint where the chat bubble will send messages. This is the same URL you access your LocalCaht instance in the Webbrowser.
|
|
128
|
-
```javascript
|
|
129
|
-
apiUrl: 'https://company.localchat.at'
|
|
130
|
-
```
|
|
131
139
|
|
|
132
|
-
#### `apiKey`
|
|
133
|
-
**Type:** `string` | **Required:** ✅
|
|
134
|
-
The API Key of a dedicated Headwai Chat Bubble user in LocalChat.
|
|
135
140
|
```javascript
|
|
136
|
-
|
|
141
|
+
apiUrl: 'https://company.localchat.at';
|
|
137
142
|
```
|
|
138
143
|
|
|
139
|
-
**How to get your API Key:**
|
|
140
|
-
|
|
141
|
-
1. **Access Settings**: Login to LocalChat with the dedicated Headwai Chat Bubble user (All conversations will be stored at this user's chats list) and click on the user menu, then select `Settings`.
|
|
142
|
-
|
|
143
|
-
<img src="docs/images/settings.png" alt="LocalChat User Menu" width="50%" />
|
|
144
|
-
|
|
145
|
-
2. **Navigate to Account**: In the Settings sidebar, click on `Account` to access your account settings.
|
|
146
|
-
|
|
147
|
-
<img src="docs/images/api-keys.png" alt="LocalChat Settings Account" width="50%" />
|
|
148
|
-
|
|
149
|
-
3. **Get your API credentials**: In the API keys section, you have two options:
|
|
150
|
-
- **JWT Token**: Copy the existing JWT Token (expires after 7 days)
|
|
151
|
-
- **API Key**: Generate an API Key via `Generate API Key` button. Click the copy button next to the API Key field, or click the refresh button to generate a new permanent API Key
|
|
152
|
-
|
|
153
|
-
**⚠️ Security Note:** When using permanent API Keys, ensure they are stored securely (e.g., environment variables, secure configuration) and never expose them directly in client-side code. If using JWT Tokens, implement an automatic refresh mechanism since they expire after 7 days - consider using a server-side proxy to handle token renewal and keep tokens secure.
|
|
154
|
-
|
|
155
|
-
|
|
156
144
|
#### `modelId`
|
|
145
|
+
|
|
157
146
|
**Type:** `string` | **Required:** ✅
|
|
158
147
|
The identifier of the AI model to use for generating responses. This should match a model configured in your LocalChat instance.
|
|
148
|
+
|
|
159
149
|
```javascript
|
|
160
|
-
modelId: 'customer-support-model-id'
|
|
150
|
+
modelId: 'customer-support-model-id';
|
|
161
151
|
```
|
|
162
152
|
|
|
163
153
|
1. **Navigate to Model**: Login to LocalChat with the dedicated Headwai Chat Bubble user (Or any other user that is allowed to see the desired model) and click on the `Workspace` menu, then select `Models`. Search for the name of the desired model (Or create one). Click onto the edit-`Pen`.
|
|
164
154
|
|
|
165
155
|
<img src="docs/images/model-edit.png" alt="LocalChat User Menu" width="50%" />
|
|
166
156
|
|
|
167
|
-
1. **Copy Model Id**: Now the model is displayed with its `name` and right underneath the `model-id`. Copy the `model-id`.
|
|
157
|
+
1. **Copy Model Id**: Now the model is displayed with its `name` and right underneath the `model-id`. Copy the `model-id`.
|
|
168
158
|
|
|
169
159
|
<img src="docs/images/model-id.png" alt="LocalChat User Menu" width="50%" />
|
|
170
160
|
|
|
171
161
|
### Optional Configuration
|
|
172
162
|
|
|
173
163
|
#### `maxMessages`
|
|
164
|
+
|
|
174
165
|
**Type:** `number` | **Default:** `0` (unlimited)
|
|
175
166
|
Limits the number of messages stored in the conversation history in one singel conversation. Set to `0` for unlimited messages, or specify a positive number to limit history.
|
|
167
|
+
|
|
176
168
|
```javascript
|
|
177
|
-
maxMessages: 10 // Keep and use only last 10 messages
|
|
169
|
+
maxMessages: 10; // Keep and use only last 10 messages
|
|
178
170
|
```
|
|
179
171
|
|
|
180
172
|
#### `placeholderText`
|
|
173
|
+
|
|
181
174
|
**Type:** `string` | **Default:** `'Type your message...'`
|
|
182
175
|
The placeholder text displayed in the message input field when it's empty.
|
|
176
|
+
|
|
183
177
|
```javascript
|
|
184
|
-
placeholderText: 'Ask your question here!'
|
|
178
|
+
placeholderText: 'Ask your question here!';
|
|
185
179
|
```
|
|
186
180
|
|
|
187
181
|
#### `faviconPath`
|
|
182
|
+
|
|
188
183
|
**Type:** `string` | **Default:** `'/icons/favicon.svg'`
|
|
189
184
|
Path or URL to the icon displayed on the chat bubble toggle button. Can be a relative path or absolute URL.
|
|
185
|
+
|
|
190
186
|
```javascript
|
|
191
|
-
faviconPath: 'https://cdn.company.at/icons/favicon.svg'
|
|
187
|
+
faviconPath: 'https://cdn.company.at/icons/favicon.svg';
|
|
192
188
|
```
|
|
193
189
|
|
|
194
190
|
#### `initialMessage`
|
|
191
|
+
|
|
195
192
|
**Type:** `string` | **Default:** `undefined`
|
|
196
193
|
An optional welcome message that appears when the chat is first opened. If not set, no initial message is displayed.
|
|
194
|
+
|
|
197
195
|
```javascript
|
|
198
|
-
initialMessage: 'Hey! My name is Supporty, how can I help you?'
|
|
196
|
+
initialMessage: 'Hey! My name is Supporty, how can I help you?';
|
|
199
197
|
```
|
|
200
198
|
|
|
201
199
|
#### `chatTitle`
|
|
200
|
+
|
|
202
201
|
**Type:** `string` | **Default:** `'Headwai Chat Bubble'`
|
|
203
202
|
The title displayed in the chat window header at the top of the chat interface.
|
|
203
|
+
|
|
204
204
|
```javascript
|
|
205
|
-
chatTitle: 'Customer Support'
|
|
205
|
+
chatTitle: 'Customer Support';
|
|
206
206
|
```
|
|
207
207
|
|
|
208
208
|
### Styling Configuration
|
|
209
209
|
|
|
210
210
|
#### `userMessageBackgroundColor`
|
|
211
|
+
|
|
211
212
|
**Type:** `string` | **Default:** `'#007bff'`
|
|
212
213
|
Background color for messages sent by the user. Accepts any valid CSS color value.
|
|
214
|
+
|
|
213
215
|
```javascript
|
|
214
|
-
userMessageBackgroundColor: '#007bff'
|
|
216
|
+
userMessageBackgroundColor: '#007bff';
|
|
215
217
|
```
|
|
216
218
|
|
|
217
219
|
#### `aiMessageBackgroundColor`
|
|
220
|
+
|
|
218
221
|
**Type:** `string` | **Default:** `'#f1f3f4'`
|
|
219
222
|
Background color for messages sent by the Headwai Chat Bubble. Accepts any valid CSS color value.
|
|
223
|
+
|
|
220
224
|
```javascript
|
|
221
|
-
aiMessageBackgroundColor: '#f1f3f4'
|
|
225
|
+
aiMessageBackgroundColor: '#f1f3f4';
|
|
222
226
|
```
|
|
223
227
|
|
|
224
228
|
#### `userMessageTextColor`
|
|
229
|
+
|
|
225
230
|
**Type:** `string` | **Default:** `'#000000'`
|
|
226
231
|
Text color for user messages. Accepts any valid CSS color value.
|
|
232
|
+
|
|
227
233
|
```javascript
|
|
228
|
-
userMessageTextColor: '#ffffff'
|
|
234
|
+
userMessageTextColor: '#ffffff';
|
|
229
235
|
```
|
|
230
236
|
|
|
231
237
|
#### `aiMessageTextColor`
|
|
238
|
+
|
|
232
239
|
**Type:** `string` | **Default:** `'#000000'`
|
|
233
240
|
Text color for Headwai Chat Bubble messages. Accepts any valid CSS color value.
|
|
241
|
+
|
|
234
242
|
```javascript
|
|
235
|
-
aiMessageTextColor: '#333333'
|
|
243
|
+
aiMessageTextColor: '#333333';
|
|
236
244
|
```
|
|
237
245
|
|
|
238
246
|
#### `faviconBackgroundColor`
|
|
247
|
+
|
|
239
248
|
**Type:** `string` | **Default:** `'#667eea'`
|
|
240
249
|
Base color used for the assistant icon gradient. This color influences the overall appearance of the Headwai Chat Bubble's avatar.
|
|
250
|
+
|
|
241
251
|
```javascript
|
|
242
|
-
faviconBackgroundColor: '#667eea'
|
|
252
|
+
faviconBackgroundColor: '#667eea';
|
|
243
253
|
```
|
|
244
254
|
|
|
245
255
|
#### `fontFamily`
|
|
256
|
+
|
|
246
257
|
**Type:** `string` | **Default:** `'inherit'`
|
|
247
258
|
Font family used for all text in the chat interface, including messages and the input field. Accepts any valid CSS font-family value.
|
|
259
|
+
|
|
248
260
|
```javascript
|
|
249
|
-
fontFamily: '"Inter", system-ui, sans-serif'
|
|
250
|
-
fontFamily: '"Roboto", "Helvetica Neue", Arial, sans-serif'
|
|
251
|
-
fontFamily: 'system-ui, -apple-system, sans-serif'
|
|
261
|
+
fontFamily: '"Inter", system-ui, sans-serif';
|
|
262
|
+
fontFamily: '"Roboto", "Helvetica Neue", Arial, sans-serif';
|
|
263
|
+
fontFamily: 'system-ui, -apple-system, sans-serif';
|
|
252
264
|
```
|
|
253
265
|
|
|
254
266
|
**Note:** When using Google Fonts or other web fonts, make sure to include the appropriate `<link>` tag in your HTML `<head>` section:
|
|
267
|
+
|
|
255
268
|
```html
|
|
256
269
|
<head>
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
270
|
+
<!-- For Google Fonts -->
|
|
271
|
+
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
272
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
|
273
|
+
<link
|
|
274
|
+
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap"
|
|
275
|
+
rel="stylesheet"
|
|
276
|
+
/>
|
|
277
|
+
|
|
278
|
+
<!-- Your chat bubble configuration -->
|
|
279
|
+
<script>
|
|
280
|
+
window.HEADWAI_CHAT_BUBBLE_CONFIG = {
|
|
281
|
+
// ... other config
|
|
282
|
+
fontFamily: '"Inter", system-ui, sans-serif',
|
|
283
|
+
};
|
|
284
|
+
</script>
|
|
269
285
|
</head>
|
|
270
286
|
```
|
|
271
287
|
|
|
272
288
|
#### `fontSize`
|
|
289
|
+
|
|
273
290
|
**Type:** `string` | **Default:** `'inherit'`
|
|
274
291
|
Font size used for all text in the chat interface. Accepts any valid CSS font-size value.
|
|
292
|
+
|
|
275
293
|
```javascript
|
|
276
|
-
fontSize: '16px'
|
|
277
|
-
fontSize: '1rem'
|
|
278
|
-
fontSize: '14px'
|
|
294
|
+
fontSize: '16px';
|
|
295
|
+
fontSize: '1rem';
|
|
296
|
+
fontSize: '14px';
|
|
279
297
|
```
|
|
280
298
|
|
|
281
299
|
### Data Attribute Format
|
|
@@ -292,12 +310,13 @@ When using data attributes for multiple chat bubbles, convert camelCase property
|
|
|
292
310
|
### Common Issues
|
|
293
311
|
|
|
294
312
|
**CORS Errors**: Ensure your API endpoint allows requests from your domain
|
|
295
|
-
**Authentication Failures**: Verify your API key is correct and has proper permissions
|
|
296
313
|
**CDN Version Delays**: Sometimes the `@latest` tag on jsDelivr CDN takes time to propagate to all edge servers and may not deliver the newest version immediately. If you need the latest features or fixes, specify the exact version number instead of using `@latest`:
|
|
297
|
-
```html
|
|
298
|
-
<!-- Instead of @latest -->
|
|
299
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.css">
|
|
300
|
-
<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.js"></script>
|
|
301
|
-
```
|
|
302
|
-
|
|
303
314
|
|
|
315
|
+
```html
|
|
316
|
+
<!-- Instead of @latest -->
|
|
317
|
+
<link
|
|
318
|
+
rel="stylesheet"
|
|
319
|
+
href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.css"
|
|
320
|
+
/>
|
|
321
|
+
<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.js"></script>
|
|
322
|
+
```
|