Repository navigation
Expand file tree
/
Copy pathweb-widget.mdx
More file actions
474 lines (385 loc) · 13.6 KB
/
Copy pathweb-widget.mdx
File metadata and controls
474 lines (385 loc) · 13.6 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
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
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
---
title: Web widget
subtitle: Add AI chat and voice capabilities to any website with a simple embeddable widget
description: "Add Vapi's web widget to a website for voice and text conversations, configure its appearance and behavior, and meet usage-based chat access requirements."
slug: chat/web-widget
---
## Overview
Add a complete AI chat and voice interface to your website with a single line of code. The Vapi Web Widget provides a customizable, floating chat interface that supports both text chat and voice conversations.
**What You'll Build:**
* Embeddable chat widget with voice and text capabilities
* Customizable themes, colors, and positioning
* Real-time conversations with context management
* Cross-platform compatibility with minimal setup
**Widget Features:**
* **Voice Mode** - Full voice conversations with transcription
* **Chat Mode** - Text-based conversations like ChatGPT
* **Custom Styling** - Match your website's design
<Note>
View the complete source code and examples on [GitHub](https://github.com/VapiAI/client-sdk-react).
</Note>
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/) with a [public API key](/security-and-privacy/api-keys)
* An existing assistant or willingness to create one
* A website where you want to embed the widget
## Scenario
We'll add a customer support widget to "TechFlow's" website that allows visitors to get help through both voice and text conversations.
---
## 1. Get Your Public API Key
<Steps>
<Step title="Get your Vapi public API key">
Follow the [Vapi API key guide](/security-and-privacy/api-keys) to create, view, or copy a public key.
<Note>
Unlike private keys, public keys are safe to expose in your website code.
</Note>
</Step>
<Step title="Get your Assistant ID">
Navigate to `Assistants` in the left sidebar and copy the ID of the assistant you want to use.
</Step>
</Steps>
---
## 2. Install the Widget
<Tabs>
<Tab title="CDN Script">
Add the widget script to your HTML page:
```html title="index.html"
<!DOCTYPE html>
<html>
<head>
<title>Your Website</title>
</head>
<body>
<!-- Your website content -->
<!-- Add Vapi Widget -->
<script src="https://unpkg.com/@vapi-ai/client-sdk-react/dist/embed/widget.umd.js" async type="text/javascript"></script>
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
theme="light"
></vapi-widget>
</body>
</html>
```
</Tab>
<Tab title="React Component">
Install the React package and use it as a component:
<CodeBlocks>
```bash title="npm"
npm install @vapi-ai/client-sdk-react
```
```bash title="yarn"
yarn add @vapi-ai/client-sdk-react
```
```bash title="pnpm"
pnpm add @vapi-ai/client-sdk-react
```
</CodeBlocks>
```tsx title="App.tsx"
import { VapiWidget } from '@vapi-ai/client-sdk-react';
function App() {
return (
<div>
{/* Your app content */}
<VapiWidget
publicKey="your-public-key"
assistantId="your-assistant-id"
mode="chat"
theme="light"
/>
</div>
);
}
```
</Tab>
</Tabs>
---
## 3. Configure Widget Modes
<Steps>
<Step title="Choose the right mode for your use case">
The widget supports two interaction modes:
**Voice Mode** - Voice-only conversations
```html
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="voice"
size="compact"
></vapi-widget>
```
**Chat Mode** - Text-only conversations
```html
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
size="full"
></vapi-widget>
```
</Step>
<Step title="Test the widget">
Open your website and click the floating widget button to test the integration.
</Step>
</Steps>
---
## 4. Customize Appearance
<Steps>
<Step title="Choose theme and colors">
Customize the widget to match your website's design:
```html title="Custom Styling"
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
theme="dark"
size="full"
radius="large"
base-color="#1a1a1a"
accent-color="#3B82F6"
button-base-color="#000000"
button-accent-color="#FFFFFF"
></vapi-widget>
```
</Step>
<Step title="Customize labels and messages">
Set custom text for better user experience:
```html title="Custom Labels"
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
main-label="Chat with Support"
start-button-text="Start Voice Chat"
end-button-text="End Call"
empty-chat-message="Hi! How can I help you today?"
empty-voice-message="Click to start a voice conversation"
></vapi-widget>
```
</Step>
</Steps>
---
## 5. Handle Events and Callbacks
<Steps>
<Step title="Add event listeners for the widget">
Handle widget events to integrate with your application:
```html title="Event Handling"
<script>
document.addEventListener('DOMContentLoaded', function() {
const widget = document.querySelector('vapi-widget');
// Listen for call events
widget.addEventListener('call-start', function(event) {
console.log('Voice call started');
// Track analytics, update UI, etc.
});
widget.addEventListener('call-end', function(event) {
console.log('Voice call ended');
// Update UI, save conversation, etc.
});
widget.addEventListener('message', function(event) {
console.log('Message received:', event.detail);
// Process message, update state, etc.
});
widget.addEventListener('error', function(event) {
console.error('Widget error:', event.detail);
// Handle errors, show fallback UI, etc.
});
});
</script>
```
</Step>
<Step title="React event handling">
Handle events in React components:
```tsx title="React Events"
import { VapiWidget } from '@vapi-ai/client-sdk-react';
function App() {
const handleCallStart = () => {
console.log('Voice call started');
// Update state, track analytics, etc.
};
const handleCallEnd = () => {
console.log('Voice call ended');
// Update state, save conversation, etc.
};
const handleMessage = (message: any) => {
console.log('Message received:', message);
// Process message, update state, etc.
};
const handleError = (error: Error) => {
console.error('Widget error:', error);
// Handle errors, show fallback UI, etc.
};
return (
<VapiWidget
publicKey="your-public-key"
assistantId="your-assistant-id"
mode="voice"
onCallStart={handleCallStart}
onCallEnd={handleCallEnd}
onMessage={handleMessage}
onError={handleError}
/>
);
}
```
</Step>
</Steps>
---
## 6. Advanced Configuration
<Steps>
<Step title="Use dynamic assistant configuration">
Configure the assistant directly without pre-creating it:
<Note>
The `assistant` configuration is only supported in **voice mode**. For chat mode, use `assistant-id` with optional `assistant-overrides`.
</Note>
```html title="Inline Assistant Configuration"
<vapi-widget
public-key="your-public-key"
mode="voice"
assistant='{
"model": {
"provider": "openai",
"model": "gpt-4.1-mini",
"messages": [
{
"role": "system",
"content": "You are a helpful customer support agent for TechFlow. Be friendly and helpful."
}
]
}
}'
></vapi-widget>
```
</Step>
<Step title="Override assistant settings">
Modify existing assistant behavior with overrides:
```html title="Assistant Overrides"
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
assistant-overrides='{
"variableValues": {
"customerName": "John Doe",
"customerTier": "Premium"
}
}'
></vapi-widget>
```
</Step>
<Step title="Add consent management">
Implement consent requirements for compliance:
```html title="Consent Management"
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
require-consent="true"
terms-content="By using this chat widget, you agree to our privacy policy and terms of service. Your conversations may be recorded for quality assurance."
local-storage-key="techflow_widget_consent"
></vapi-widget>
```
</Step>
</Steps>
---
## 7. Production Considerations
<Steps>
<Step title="Optimize for performance">
Consider these optimizations for production:
```html title="Performance Optimizations"
<vapi-widget
public-key="your-public-key"
assistant-id="your-assistant-id"
mode="chat"
size="compact"
show-transcript="false"
></vapi-widget>
```
</Step>
<Step title="Handle errors gracefully">
Implement proper error handling:
```javascript title="Error Handling"
document.addEventListener('DOMContentLoaded', function() {
const widget = document.querySelector('vapi-widget');
widget.addEventListener('error', function(event) {
const error = event.detail;
// Log error for debugging
console.error('Widget error:', error);
// Show user-friendly message
if (error.message.includes('microphone')) {
alert('Please allow microphone access to use voice features.');
} else if (error.message.includes('network')) {
alert('Connection error. Please check your internet connection.');
} else {
alert('Something went wrong. Please try again.');
}
});
});
```
</Step>
</Steps>
---
## Configuration Reference
### Required Props
| Prop | Type | Description |
|------|------|-------------|
| `public-key` | string | Your Vapi public API key |
### Assistant Configuration
| Prop | Type | Description |
|------|------|-------------|
| `assistant-id` | string | ID of your Vapi assistant |
| `assistant` | object | Full assistant configuration (JSON string) - **Voice mode only** |
| `assistant-overrides` | object | Override existing assistant settings (JSON string) |
<Note>
You must provide either `assistant-id`, `assistant`, or both `assistant-id` and `assistant-overrides`. The `assistant` prop is only supported in voice mode.
</Note>
### Appearance Options
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `voice` \| `chat` | `chat` | Widget interaction mode |
| `theme` | `light` \| `dark` | `light` | Color theme |
| `position` | `bottom-right` \| `bottom-left` \| `top-right` \| `top-left` | `bottom-right` | Screen position |
| `size` | `tiny` \| `compact` \| `full` | `full` | Widget size |
| `radius` | `none` \| `small` \| `medium` \| `large` | `medium` | Border radius |
### Styling Options
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `base-color` | string | - | Main background color |
| `accent-color` | string | `#14B8A6` | Primary accent color |
| `button-base-color` | string | `#000000` | Floating button background |
| `button-accent-color` | string | `#FFFFFF` | Floating button text/icon color |
### Text Customization
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `main-label` | string | `Talk with AI` | Widget header text |
| `start-button-text` | string | `Start` | Voice call start button text |
| `end-button-text` | string | `End Call` | Voice call end button text |
| `empty-chat-message` | string | - | Message when chat is empty |
| `empty-voice-message` | string | - | Message when voice mode is empty |
### Advanced Options
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `require-consent` | boolean | `false` | Show consent form before first use |
| `terms-content` | string | - | Custom consent form text |
| `local-storage-key` | string | `vapi_widget_consent` | Key for storing consent |
| `show-transcript` | boolean | `true` | Show/hide voice transcript |
## Browser Support
* Chrome/Edge 79+
* Firefox 86+
* Safari 14.1+
* Mobile browsers with WebRTC support
## Requirements
* Microphone access for voice mode
* HTTPS required in production
* Vapi account and [API key](/security-and-privacy/api-keys)
## Next Steps
Enhance your widget integration:
* **[Chat API](/chat/quickstart)** - Build custom chat interfaces using the API directly
* **[Voice calls](/calls/outbound-calling)** - Add programmatic voice calling capabilities
* **[Function tools](/tools/custom-tools)** - Give your assistant access to external APIs
* **[Assistant customization](/assistants/quickstart)** - Fine-tune your assistant's behavior
<Tip>
The widget automatically handles microphone permissions, audio processing, and cross-browser compatibility. For custom implementations, consider using the [Web SDK](/quickstart/web) directly.
</Tip>
<Callout>
Need help? Ask other developers in the [Vapi Discord community](https://discord.gg/v5Ee6FhAZt) or mention us on [X/Twitter](https://x.com/Vapi_AI).
</Callout>