VAPI React Client SDK

> ⚠️ Beta Version: This library is currently in beta. APIs may change and some features might be unstable. Use with caution in production environments.

A modern React component library with embeddable voice and chat widgets built with Vite, TypeScript, and Tailwind CSS. Featuring seamless VAPI AI integration for voice conversations.

Features

- 🎙️ Voice Conversations: Real-time voice calls with VAPI AI assistants
- 💬 Chat Interface: Text-based conversations with markdown support
- 🔀 Hybrid Mode: Seamlessly switch between voice and chat
- 🎨 Highly Customizable: Themes, colors, sizes, and positions
- 🔒 Consent Management: Built-in consent form for compliance
- ⚡ Easy Integration: Use as React component or embed in any HTML page
- 📘 TypeScript: Full type safety and IntelliSense support

Installation

``bash
npm install @vapi-ai/client-sdk-react @vapi-ai/web
`

> Note: @vapi-ai/web is a peer dependency that must be installed separately to avoid WebRTC connection conflicts.

Quick Start

The simplest way to add the widget to your website:

`html






public-key="your-vapi-public-key"
assistant-id="your-assistant-id"
mode="chat"
theme="light"
size="full"
color-accent="#3B82F6"
cta-button-color="#1F2937"
cta-button-text-color="#FFFFFF"
title="AI Assistant"
cta-title="Chat with us"
cta-subtitle="24/7 Support"
chat-placeholder="How can I help you today?"
>


`

VapiWidget Props

$3

| Prop | Type | Description |
| ----------- | -------- | ------------------------ |
| publicKey | string | Your VAPI public API key |

$3

| Prop | Type | Description |
| -------------------- | -------- | ------------------------------------------------------ |
| assistantId | string | VAPI assistant ID (supported by both voice and chat) |
| assistant | object | Full assistant configuration object (voice only) |
| assistantOverrides | object | Assistant overrides (supported by both voice and chat) |

> Note: You must provide at least one of assistantId, assistant, or both assistantId and assistantOverrides.

$3

| Prop | Type | Default | Description |
| ------------------------- | --------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| mode | 'voice' \| 'chat' \| 'hybrid' | 'chat' | Widget interaction mode |
| theme | 'light' \| 'dark' | 'light' | Color theme |
| position | 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' \| 'bottom-center' | 'bottom-right' | Screen position |
| size | 'tiny' \| 'compact' \| 'full' | 'full' | Widget size |
| borderRadius | 'none' \| 'small' \| 'medium' \| 'large' | 'medium' | Corner radius style |
| apiUrl | string | - | Custom API endpoint for chat mode |
| Colors | | | |
| baseBgColor | string | - | Main background color |
| accentColor | string | '#14B8A6' | Primary accent color |
| ctaButtonColor | string | '#000000' | CTA button background color |
| ctaButtonTextColor | string | '#FFFFFF' | CTA button text/icon color |
| Text Labels | | | |
| title | string | 'Talk with AI' | Main widget title |
| startButtonText | string | 'Start' | Voice call start button text |
| endButtonText | string | 'End Call' | Voice call end button text |
| ctaTitle | string | _(uses title)_ | Floating button main text |
| ctaSubtitle | string | - | Floating button subtitle text |
| Empty States | | | |
| voiceEmptyMessage | string | - | Message when voice mode is empty |
| voiceActiveEmptyMessage | string | - | Message during active voice call |
| chatEmptyMessage | string | - | Message when chat is empty |
| hybridEmptyMessage | string | - | Message for hybrid mode |
| Chat Configuration | | | |
| chatFirstMessage | string | - | Initial assistant message in chat |
| chatPlaceholder | string | 'Type your message...' | Chat input placeholder text |
| Voice Configuration | | | |
| voiceShowTranscript | boolean | false | Show/hide voice transcript |
| voiceAutoReconnect | boolean | false | Auto-reconnect to an active web call (see voiceReconnectStorage for scope) |
| voiceReconnectStorage | 'session' \| 'cookies' | 'session' | Storage type: 'session' (same tab only) or 'cookies' (same tab across subdomains) |
| reconnectStorageKey | string | 'vapi_widget_web_call' | Key for storing reconnection data |
| Consent Configuration | | | |
| consentRequired | boolean | false | Show consent form before first use |
| consentTitle | string | "Terms and conditions" | Consent form title |
| consentContent | string | _(default message)_ | Terms & conditions content |
| consentStorageKey | string | "vapi_widget_consent" | Key for storing consent |

$3

| Prop | Type | Description |
| -------------- | ------------------------ | -------------------------------- |
| onVoiceStart | () => void | Triggered when voice call starts |
| onVoiceEnd | () => void | Triggered when voice call ends |
| onMessage | (message: any) => void | Triggered for all messages |
| onError | (error: Error) => void | Triggered on errors |

React Component Usage

If you're using React, you can import and use the widget as a component:

`tsx
import { VapiWidget } from '@vapi-ai/client-sdk-react';

function App() {
return (
publicKey="your-vapi-public-key"
assistantId="your-assistant-id"
mode="hybrid"
position="bottom-right"
theme="light"
accentColor="#3B82F6"
title="AI Assistant"
chatPlaceholder="Ask me anything..."
voiceShowTranscript={true}
/>
);
}
`

Embedding Methods

$3

Use the widget as a custom HTML element with kebab-case attributes - the cleanest and most modern approach:

`html
public-key="pk_123"
assistant-id="asst_456"
mode="chat"
theme="dark"
accent-color="#8B5CF6"
consent-required="true"
chat-first-message="Welcome! How can I assist you?"
chat-placeholder="Type your question here..."
>
`

$3

Use this approach if your environment doesn't support custom elements or for better compatibility with older systems:

`html
data-client-widget="VapiWidget"
data-public-key="pk_123"
data-assistant-id="asst_456"
data-mode="voice"
data-theme="dark"
data-size="compact"
>