@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.
Files changed (4) hide show
  1. package/README.dev.md +283 -31
  2. package/README.md +144 -125
  3. package/dist-widget/chat-bubble.js +85 -85
  4. package/package.json +2 -2
package/README.dev.md CHANGED
@@ -12,17 +12,19 @@ The chat bubble is based on a Svelte integration for the [deep-chat](https://www
12
12
  ### Setup
13
13
 
14
14
  1. Clone this repository:
15
+
15
16
  ```bash
16
17
  git clone <your-repo-url>
17
- cd chat-bubble
18
18
  ```
19
19
 
20
20
  2. Install dependencies:
21
+
21
22
  ```bash
22
23
  npm install
23
24
  ```
24
25
 
25
26
  3. Create a `.env` file in the root directory:
27
+
26
28
  ```bash
27
29
  cp .env.example .env
28
30
  ```
@@ -30,47 +32,52 @@ cp .env.example .env
30
32
  4. Configure your environment variables (see [Configuration](#configuration) section)
31
33
 
32
34
  5. Start the development server:
35
+
33
36
  ```bash
34
37
  npm run dev
35
38
  ```
36
39
 
37
40
  6. Open embedded Headwai Chat Bubble in Browser
41
+
38
42
  ```bash
39
43
  http://localhost:5174/
40
44
  ```
41
45
 
42
46
  7. Alternatively, build and test deployed version:
43
- [Build and Deploy](#build-and-deploy) and open `./test-widget.html` in a browser.
47
+ [Build and Deploy](#build-and-deploy) and open `./test-widget.html` in a browser.
44
48
 
45
49
  ## Configuration
46
50
 
47
- The Headwai Chat Bubble can be configured using environment variables or by changing the attributes of the instance.
51
+ The Headwai Chat Bubble can be configured using environment variables or by changing the attributes of the instance.
48
52
 
49
53
  ### Environment Variables
54
+
50
55
  Create a `.env` by copying `.env.example` file in your project root with the following variables:
51
56
 
52
57
  ### Window Object Configuration
58
+
53
59
  ```html
54
- <script>
55
- // Runtime configuration override
56
- window.HEADWAI_CHAT_BUBBLE_CONFIG = {
57
- apiUrl: 'https://customer-api.com/chat',
58
- apiKey: 'customer-api-key',
59
- modelId: 'gpt-4'
60
- };
61
- </script>
60
+ <script>
61
+ // Runtime configuration override
62
+ window.HEADWAI_CHAT_BUBBLE_CONFIG = {
63
+ apiUrl: 'https://company.localchat.at',
64
+ modelId: 'gpt-4',
65
+ };
66
+ </script>
62
67
  ```
63
68
 
64
- ### Via data attributes (Multiple chat bubbles):**
69
+ ### Via data attributes (Multiple chat bubbles):\*\*
70
+
65
71
  ```html
66
- <div data-chat-bubble
67
- data-chat-bubble-api-url="https://api1.com/chat"
68
- data-chat-bubble-api-key="key1"
69
- data-chat-bubble-user-message-background-color="#ff9500"
70
- data-chat-bubble-ai-message-background-color="#00c851"
71
- data-chat-bubble-user-message-text-color="#ffffff"
72
- data-chat-bubble-ai-message-text-color="#004225"
73
- data-chat-bubble-favicon-background-color="#ff6f00"></div>
72
+ <div
73
+ data-chat-bubble
74
+ data-chat-bubble-api-url="https://company.localchat.at"
75
+ data-chat-bubble-user-message-background-color="#ff9500"
76
+ data-chat-bubble-ai-message-background-color="#00c851"
77
+ data-chat-bubble-user-message-text-color="#ffffff"
78
+ data-chat-bubble-ai-message-text-color="#004225"
79
+ data-chat-bubble-favicon-background-color="#ff6f00"
80
+ ></div>
74
81
  ```
75
82
 
76
83
  ## Including Chat Bubble in Customer Websites
@@ -82,38 +89,43 @@ For simple integration instructions, see [README.md](README.md) which provides a
82
89
  This project builds a standalone widget that can be integrated into any website.
83
90
 
84
91
  **What gets bundled:**
92
+
85
93
  - ✅ All logic and request/response interceptors
86
94
  - ✅ Environment variable configuration
87
95
  - ✅ All chat functionality
88
96
  - ✅ UI components and styling
89
97
 
90
98
  **Build and deployment steps:**
99
+
91
100
  1. **Configure environment variables** for production:
101
+
92
102
  ```bash
93
103
  # Production .env file
94
- VITE_CHAT_BUBBLE_API_URL=https://api.customer-domain.com/chat
95
- VITE_CHAT_BUBBLE_API_KEY=prod-api-key
104
+ VITE_CHAT_BUBBLE_API_URL=https://company.localchat.at
96
105
  VITE_CHAT_BUBBLE_MODEL_ID=gpt-4
97
106
  ```
98
107
 
99
108
  2. **Bump package version**
100
- Bump up the `version` in `package.json`
109
+ Bump up the `version` in `package.json`
101
110
 
102
111
  ## Publishing to NPM and jsDelivr Access
103
112
 
104
113
  ### Publishing Steps
105
114
 
106
115
  3. **Build widget**:
116
+
107
117
  ```bash
108
118
  npm run build
109
119
  ```
110
120
 
111
121
  4. **Login to NPM** (if not already logged in):
122
+
112
123
  ```bash
113
124
  npm login
114
125
  ```
115
126
 
116
127
  5. **Publish the package**:
128
+
117
129
  ```bash
118
130
  npm publish
119
131
  ```
@@ -123,16 +135,252 @@ npm publish
123
135
  Once published to NPM, your package is automatically available on jsDelivr:
124
136
 
125
137
  **For Widget/Script Embed:**
138
+
126
139
  ```html
127
140
  <!-- Latest version -->
128
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css">
141
+ <link
142
+ rel="stylesheet"
143
+ href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css"
144
+ />
129
145
  <script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
130
146
 
131
147
  <!-- Specific version -->
132
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.css">
148
+ <link
149
+ rel="stylesheet"
150
+ href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.css"
151
+ />
133
152
  <script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.js"></script>
134
153
  ```
135
154
 
155
+ ## API Reference
156
+
157
+ ### APIs Called
158
+
159
+ The chat bubble makes requests to the following API endpoints:
160
+
161
+ #### 1. Chat Completions API
162
+
163
+ - **Endpoint**: `{apiUrl}/api/chat/completions`
164
+ - **Method**: WebSocket (streaming)
165
+ - **Purpose**: Main chat conversation endpoint for sending messages and receiving AI responses
166
+ - **Authentication**: Bearer token via `Authorization` header
167
+ - **Request Format**: OpenAI-compatible chat completions format
168
+ - **Response Format**: Server-sent events with OpenAI-compatible streaming format
169
+
170
+ #### 2. Chat Creation API
171
+
172
+ - **Endpoint**: `{apiUrl}/api/v1/chats/new`
173
+ - **Method**: POST
174
+ - **Purpose**: Create a new chat session when starting a conversation
175
+ - **Authentication**: Bearer token via `Authorization` header
176
+ - **Request Body**: Chat metadata including models, history, messages, and timestamps
177
+
178
+ #### 3. Chat Storage API
179
+
180
+ - **Endpoint**: `{apiUrl}/api/v1/chats/{chatId}`
181
+ - **Method**: POST
182
+ - **Purpose**: Store/update chat history and conversation state
183
+ - **Authentication**: Bearer token via `Authorization` header
184
+ - **Request Body**: Complete chat state including message history and metadata
185
+
186
+ #### 4. Feedback API
187
+
188
+ - **Endpoint**: `{apiUrl}/api/v1/evaluations/feedback`
189
+ - **Method**: POST
190
+ - **Purpose**: Submit user feedback (thumbs up/down) for AI responses
191
+ - **Authentication**: Bearer token via `Authorization` header
192
+ - **Request Body**: Feedback data including rating, message metadata, and chat snapshot
193
+
194
+ ### Configuration Attributes
195
+
196
+ The chat bubble can be configured using environment variables, data attributes, or runtime configuration. All attributes have fallback defaults.
197
+
198
+ #### Core API Configuration
199
+
200
+ | Attribute | Environment Variable | Data Attribute | Purpose | Default |
201
+ | --------- | --------------------------- | --------------------------- | ---------------------------------------- | ------------------- |
202
+ | `apiUrl` | `VITE_CHAT_BUBBLE_API_URL` | `data-chat-bubble-api-url` | Base URL for API endpoints | `https://localhost` |
203
+ | `modelId` | `VITE_CHAT_BUBBLE_MODEL_ID` | `data-chat-bubble-model-id` | AI model identifier to use for responses | `test-model` |
204
+
205
+ #### Message Configuration
206
+
207
+ | Attribute | Environment Variable | Data Attribute | Purpose | Default |
208
+ | ----------------- | ----------------------------------- | ----------------------------------- | ------------------------------------------------------ | --------------------------- |
209
+ | `maxMessages` | `VITE_CHAT_BUBBLE_MAX_MESSAGES` | `data-chat-bubble-max-messages` | Maximum messages to include in context (0 = unlimited) | `0` |
210
+ | `initialMessage` | `VITE_CHAT_BUBBLE_INITIAL_MESSAGE` | `data-chat-bubble-initial-message` | First message shown when chat opens | `Hey, how can I help you?` |
211
+ | `placeholderText` | `VITE_CHAT_BUBBLE_PLACEHOLDER_TEXT` | `data-chat-bubble-placeholder-text` | Input field placeholder text | `Enter your questions here` |
212
+
213
+ #### UI Styling Configuration
214
+
215
+ | Attribute | Environment Variable | Data Attribute | Purpose | Default |
216
+ | -------------------------------- | ---------------------------------------------- | ---------------------------------------------------- | ------------------------------------- | --------- |
217
+ | `userMessageBackgroundColor` | `VITE_CHAT_BUBBLE_USER_MESSAGE_BG_COLOR` | `data-chat-bubble-user-message-background-color` | Background color for user messages | `#007bff` |
218
+ | `userMessageTextColor` | `VITE_CHAT_BUBBLE_USER_MESSAGE_TEXT_COLOR` | `data-chat-bubble-user-message-text-color` | Text color for user messages | `#000000` |
219
+ | `aiMessageBackgroundColor` | `VITE_CHAT_BUBBLE_AI_MESSAGE_BG_COLOR` | `data-chat-bubble-ai-message-background-color` | Background color for AI messages | `#f1f3f4` |
220
+ | `aiMessageTextColor` | `VITE_CHAT_BUBBLE_AI_MESSAGE_TEXT_COLOR` | `data-chat-bubble-ai-message-text-color` | Text color for AI messages | `#000000` |
221
+ | `feedbackMessageBackgroundColor` | `VITE_CHAT_BUBBLE_FEEDBACK_MESSAGE_BG_COLOR` | `data-chat-bubble-feedback-message-background-color` | Background color for feedback buttons | `#ffffff` |
222
+ | `feedbackMessageTextColor` | `VITE_CHAT_BUBBLE_FEEDBACK_MESSAGE_TEXT_COLOR` | `data-chat-bubble-feedback-message-text-color` | Text color for feedback buttons | `#000000` |
223
+ | `faviconBackgroundColor` | `VITE_CHAT_BUBBLE_FAVICON_BG_COLOR` | `data-chat-bubble-favicon-background-color` | Background color for chat icon | `#667eea` |
224
+ | `fontFamily` | `VITE_CHAT_BUBBLE_FONT_FAMILY` | `data-chat-bubble-font-family` | Font family for chat interface | `inherit` |
225
+ | `fontSize` | `VITE_CHAT_BUBBLE_FONT_SIZE` | `data-chat-bubble-font-size` | Font size for chat interface | `inherit` |
226
+
227
+ #### Branding Configuration
228
+
229
+ | Attribute | Environment Variable | Data Attribute | Purpose | Default |
230
+ | ------------- | ------------------------------- | ------------------------------- | -------------------------- | --------------------- |
231
+ | `chatTitle` | `VITE_CHAT_BUBBLE_CHAT_TITLE` | `data-chat-bubble-chat-title` | Title shown in chat header | `Headwai Chat Bubble` |
232
+ | `faviconPath` | `VITE_CHAT_BUBBLE_FAVICON_PATH` | `data-chat-bubble-favicon-path` | Path to chat icon/logo | `./icons/favicon.svg` |
233
+
234
+ ### API Request Flow and Data Format
235
+
236
+ #### Chat Completions Request
237
+
238
+ ```javascript
239
+ {
240
+ "messages": [
241
+ {
242
+ "role": "user|assistant",
243
+ "content": "message text"
244
+ }
245
+ ],
246
+ "model": "model-id",
247
+ "stream": true,
248
+ "chat_id": "uuid-if-existing",
249
+ "params": {},
250
+ "tool_servers": [],
251
+ "features": {
252
+ "image_generation": false,
253
+ "code_interpreter": false,
254
+ "web_search": false,
255
+ "memory": false
256
+ },
257
+ "variables": {
258
+ "{{USER_NAME}}": "David Schneebauer | headwAI GmbH",
259
+ "{{USER_LOCATION}}": "Unknown",
260
+ "{{CURRENT_DATETIME}}": "2025-01-07 15:30:45",
261
+ // ... additional template variables
262
+ },
263
+ "background_tasks": {
264
+ "title_generation": true,
265
+ "tags_generation": false,
266
+ "follow_up_generation": false
267
+ }
268
+ }
269
+ ```
270
+
271
+ #### Chat Creation Request
272
+
273
+ ```javascript
274
+ {
275
+ "chat": {
276
+ "id": "",
277
+ "title": "New Chatbubble Chat",
278
+ "models": ["model-id"],
279
+ "params": {},
280
+ "history": {
281
+ "messages": {"message-id": {...}},
282
+ "currentId": "last-message-id"
283
+ },
284
+ "messages": [{
285
+ "id": "uuid",
286
+ "parentId": "parent-uuid",
287
+ "childrenIds": ["child-uuid"],
288
+ "role": "assistant|user",
289
+ "content": "message content",
290
+ "timestamp": 1704636645,
291
+ "models": ["model-id"]
292
+ }],
293
+ "tags": [],
294
+ "timestamp": 1704636645000
295
+ },
296
+ "folder_id": null
297
+ }
298
+ ```
299
+
300
+ #### Chat Storage Request
301
+
302
+ ```javascript
303
+ {
304
+ "chat": {
305
+ "models": ["model-id"],
306
+ "history": {
307
+ "messages": {
308
+ "message-uuid-1": {
309
+ "id": "message-uuid-1",
310
+ "parentId": null,
311
+ "childrenIds": ["message-uuid-2"],
312
+ "role": "user",
313
+ "content": "user message content",
314
+ "timestamp": 1704636645,
315
+ "models": ["model-id"]
316
+ },
317
+ "message-uuid-2": {
318
+ "id": "message-uuid-2",
319
+ "parentId": "message-uuid-1",
320
+ "childrenIds": [],
321
+ "role": "assistant",
322
+ "content": "assistant response content",
323
+ "model": "model-id",
324
+ "modelId": "model-id",
325
+ "modelIdx": 0,
326
+ "timestamp": 1704636645,
327
+ "sources": []
328
+ }
329
+ },
330
+ "currentId": "message-uuid-2"
331
+ },
332
+ "messages": [
333
+ {
334
+ "id": "message-uuid-1",
335
+ "parentId": null,
336
+ "childrenIds": ["message-uuid-2"],
337
+ "role": "user",
338
+ "content": "user message content",
339
+ "timestamp": 1704636645,
340
+ "models": ["model-id"]
341
+ },
342
+ {
343
+ "id": "message-uuid-2",
344
+ "parentId": "message-uuid-1",
345
+ "childrenIds": [],
346
+ "role": "assistant",
347
+ "content": "assistant response content",
348
+ "model": "model-id",
349
+ "modelId": "model-id",
350
+ "modelIdx": 0,
351
+ "timestamp": 1704636645,
352
+ "sources": []
353
+ }
354
+ ],
355
+ "params": {}
356
+ }
357
+ }
358
+ ```
359
+
360
+ #### Feedback Request
361
+
362
+ ```javascript
363
+ {
364
+ "type": "rating",
365
+ "data": {
366
+ "rating": 1, // 1 for positive, -1 for negative
367
+ "model_id": "model-id"
368
+ },
369
+ "meta": {
370
+ "model_id": "model-id",
371
+ "message_id": "message-uuid",
372
+ "message_index": 2,
373
+ "chat_id": "chat-uuid",
374
+ "base_models": {"model-id": "model-id"}
375
+ },
376
+ "snapshot": {
377
+ "chat": {
378
+ // Complete chat state for context
379
+ }
380
+ }
381
+ }
382
+ ```
383
+
136
384
  ## API Compatibility
137
385
 
138
386
  This component is designed to work with OpenAI-compatible APIs. The request and response interceptors handle the message format transformation between deep-chat and OpenAI formats.
@@ -159,18 +407,22 @@ This component is designed to work with OpenAI-compatible APIs. The request and
159
407
  ### Common Issues
160
408
 
161
409
  **CORS Errors**: Ensure your API endpoint allows requests from your domain
162
- **Authentication Failures**: Verify your API key is correct and has proper permissions
163
410
  **Environment Variables Not Loading**: Ensure variables are prefixed with `VITE_CHAT_BUBBLE_`
164
411
  **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`:
165
- ```html
166
- <!-- Instead of @latest -->
167
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.css">
168
- <script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.js"></script>
169
- ```
412
+
413
+ ```html
414
+ <!-- Instead of @latest -->
415
+ <link
416
+ rel="stylesheet"
417
+ href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.css"
418
+ />
419
+ <script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.2.3/dist-widget/chat-bubble.js"></script>
420
+ ```
170
421
 
171
422
  ## Support
172
423
 
173
424
  For issues and questions:
425
+
174
426
  - Create an issue in this repository
175
427
  - Check the [deep-chat documentation](https://deepchat.dev/)
176
428
  - Review the [API compatibility guide](https://deepchat.dev/docs/connect)