diff --git a/fern/docs.yml b/fern/docs.yml index 87043c8f..d245e131 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -95,23 +95,15 @@ navigation: layout: - section: Get started contents: - - page: Quickstart - icon: fa-light fa-bolt-lightning + - page: Dashboard + icon: fa-light fa-table-columns path: quickstart/dashboard.mdx - - page: Make a web call - icon: fa-light fa-browser + - page: Web SDK + icon: fa-light fa-laptop-code path: quickstart/web.mdx - - section: How Vapi works - icon: fa-light fa-diagram-project - contents: - - page: Core models - path: quickstart.mdx - icon: fa-light fa-microchip-ai - - page: Orchestration models - icon: fa-light fa-network-wired - path: how-vapi-works.mdx - section: Examples icon: fa-light fa-code + path: examples.mdx contents: - page: Inbound support path: examples/inbound-support.mdx @@ -373,6 +365,15 @@ navigation: - page: FAQ path: faq.mdx icon: fa-light fa-question + - section: How Vapi works + icon: fa-light fa-diagram-project + contents: + - page: Core models + path: quickstart.mdx + icon: fa-light fa-microchip-ai + - page: Orchestration models + icon: fa-light fa-network-wired + path: how-vapi-works.mdx - section: Integrations collapsed: true icon: fa-light fa-link diff --git a/fern/examples.mdx b/fern/examples.mdx new file mode 100644 index 00000000..480065e3 --- /dev/null +++ b/fern/examples.mdx @@ -0,0 +1,20 @@ +--- +title: Examples +subtitle: Explore complete examples with step-by-step instructions to build with Vapi +slug: examples +--- + + + + Create an outbound sales agent that can schedule appointments automatically + + + Build a technical support assistant that remembers where you left off between calls + + + Build a pizza ordering assistant for your website using the Web SDK + + + Easily integrate the Vapi Voice Widget into your website for enhanced user interaction + + diff --git a/fern/quickstart/dashboard.mdx b/fern/quickstart/dashboard.mdx index d8a6022d..3068c1d0 100644 --- a/fern/quickstart/dashboard.mdx +++ b/fern/quickstart/dashboard.mdx @@ -1,6 +1,6 @@ --- title: Dashboard -subtitle: Learn to build a voice agent in under 5 minutes. +subtitle: Learn to build a voice agent in under 5 minutes using the Vapi dashboard. slug: quickstart/dashboard --- diff --git a/fern/quickstart/web.mdx b/fern/quickstart/web.mdx index 64f4a16a..14c73e40 100644 --- a/fern/quickstart/web.mdx +++ b/fern/quickstart/web.mdx @@ -1,116 +1,597 @@ --- -title: Web call -subtitle: Make a web call to your assistant from a browser +title: Web SDK Quickstart +subtitle: Build a customer support voice assistant in under 5 minutes using Vapi Web SDK. +slug: quickstart/web --- -## Overview +In this quickstart, we'll build a **customer support voice assistant** that can help users with order inquiries, account questions, and general support. You'll learn how to integrate Vapi's Web SDK and see both ways to configure your assistant. -This guide shows you how to integrate live, two-way voice calls with your Vapi assistant into any web app. You can use Vapi in plain JavaScript, React, Next.js, or any other web framework. +## Ways to Configure Assistant -Get started with either the Vapi web SDK or by connecting to an assistant you created in the dashboard. +With Vapi, you have flexibility in how you configure your assistant: -See the full next.js [demo here on v0](https://v0.dev/chat/vapi-quickstart-nextjs-z3lv02T7Dd5). To try it live and make edits, follow these steps: + + + Dashboard Configuration + + Recommended for production + + + } icon="dashboard"> + + Configure your assistant in the [Vapi Dashboard](https://dashboard.vapi.ai/assistants). Your configuration is stored securely and pulled automatically when you provide the assistant ID. + + + SDK Configuration + + Great for customization + + + } icon="code"> + + Pass configuration directly to the Web SDK. You can override existing assistants or create entirely new ones programmatically based on your app logic. + + -1. Fork the app in v0 -2. Go to settings --> environment variables -3. Create a new environment variable called `NEXT_PUBLIC_VAPI_API_KEY` -4. Add your [public api key from the dashboard](https://dashboard.vapi.ai/org/api-keys)! +Instructions below are going to primarily focus on configuring the assistant via the Web SDK. ## Installation - ### Install the SDK - + + + + ```bash + npm install @vapi-ai/web + ``` + + + ```bash + yarn add @vapi-ai/web + ``` + + + ```bash + pnpm add @vapi-ai/web + ``` + + + ```bash + bun add @vapi-ai/web + ``` + + + + + + You'll need your public API key from the [Dashboard → Vapi API Keys](https://dashboard.vapi.ai/org/api-keys). + + + Always use your **public key** (starts with `pk_`) in client-side code. Never expose your private key in the browser. + + - ### Import the SDK - + + **Option 1: Dashboard Configuration** + + Create an assistant in the [Dashboard → Assistants](https://dashboard.vapi.ai/assistants) with this system prompt: + + ``` + You are a helpful customer support assistant for TechCorp. You can help with: + - Order status and tracking + - Account questions + - Product information + - Technical support + + Be friendly, professional, and concise. If you need to look up specific information, ask for order numbers or account details. + ``` + + **Option 2: SDK Configuration** + + We'll show you how to configure the assistant directly in code below. + -## Get started +## Build an Assistant - + - - Create an assistant object. - - ```javascript - const assistantOptions = { - name: "Vapi's Pizza Front Desk", - firstMessage: "Vapi's Pizzeria speaking, how can I help you?", - transcriber: { - provider: "deepgram", - model: "nova-2", - language: "en-US", - }, - voice: { - provider: "playht", - voiceId: "jennifer", - }, - model: { - provider: "openai", - model: "gpt-4", - messages: [ - { - role: "system", - content: `You are a voice assistant for Vappy's Pizzeria, a pizza shop located on the Internet.\n\nYour job is to take the order of customers calling in. The menu has only 3 types of items: pizza, sides, and drinks. There are no other types of items on the menu.\n\n1) There are 3 kinds of pizza: cheese pizza, pepperoni pizza, and vegetarian pizza (often called \"veggie\" pizza).\n2) There are 3 kinds of sides: french fries, garlic bread, and chicken wings.\n3) There are 2 kinds of drinks: soda, and water. (if a customer asks for a brand name like \"coca cola\", just let them know that we only offer \"soda\")\n\nCustomers can only order 1 of each item. If a customer tries to order more than 1 item within each category, politely inform them that only 1 item per category may be ordered.\n\nCustomers must order 1 item from at least 1 category to have a complete order. They can order just a pizza, or just a side, or just a drink.\n\nBe sure to introduce the menu items, don't assume that the caller knows what is on the menu (most appropriate at the start of the conversation).\n\nIf the customer goes off-topic or off-track and talks about anything but the process of ordering, politely steer the conversation back to collecting their order.\n\nOnce you have all the information you need pertaining to their order, you can end the conversation. You can say something like \"Awesome, we'll have that ready for you in 10-20 minutes.\" to naturally let the customer know the order has been fully communicated.\n\nIt is important that you collect the order in an efficient manner (succinct replies & direct questions). You only have 1 task here, and it is to collect the customers order, then end the conversation.\n\n- Be sure to be kind of funny and witty!\n- Keep all your responses short and simple. Use casual language, phrases like \"Umm...\", \"Well...\", and \"I mean\" are preferred.\n- This is a voice conversation, so keep your responses short, like in a real conversation. Don't ramble for too long.`, - }, - ], - }, - }; + + ```env title=".env.local" + NEXT_PUBLIC_VAPI_API_KEY=pk_your_public_key_here + # Only needed if using Dashboard configuration + NEXT_PUBLIC_VAPI_ASSISTANT_ID=your_assistant_id_here ``` + + + + ```typescript title="components/voice-button.tsx" + 'use client'; - **Parameters:** - - `name` sets the display name for the assistant (internal use) - - `firstMessage` is the first message the assistant says - - `transcriber` selects the speech-to-text provider and model - - `voice` selects the text-to-speech provider and voice - - `model` sets the LLM provider, model, and system prompt + import Vapi from '@vapi-ai/web'; + import { useState } from 'react'; + + export function VoiceButton() { + const [vapi] = useState(() => new Vapi(process.env.NEXT_PUBLIC_VAPI_API_KEY!)); + const [isActive, setIsActive] = useState(false); + + const toggleCall = async () => { + if (isActive) { + vapi.stop(); + } else { + // Option 1: Use Dashboard-configured assistant + if (process.env.NEXT_PUBLIC_VAPI_ASSISTANT_ID) { + await vapi.start(process.env.NEXT_PUBLIC_VAPI_ASSISTANT_ID); + } else { + // Option 2: Configure assistant directly in SDK + await vapi.start({ + model: { + provider: "openai", + model: "gpt-4o-2024-05-13", + messages: [ + { + role: "system", + content: "You are a helpful customer support assistant for TechCorp. You can help with order status, account questions, product information, and technical support. Be friendly, professional, and concise." + } + ] + }, + voice: { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + firstMessage: "Hi! I'm here to help with your TechCorp support needs. How can I assist you today?", + }); + } + } + }; + + vapi.on('call-start', () => setIsActive(true)); + vapi.on('call-end', () => setIsActive(false)); + + return ( + + ); + } + ``` - - Start a call using your assistant configuration. - ```javascript - vapi.start(assistantOptions); + + ```typescript title="app/page.tsx" + import { VoiceButton } from '@/components/voice-button'; + + export default function Home() { + return ( +
+

TechCorp Customer Support

+

+ Need help? Click the button below to speak with our AI support assistant. +

+ +
+ ); + } ``` - + + - - To create an assistant in the dashboard, follow the step-by-step guide in the [Dashboard Quickstart](https://docs.vapi.ai/quickstart/dashboard#get-started). + + ```env title=".env" + VITE_VAPI_API_KEY=pk_your_public_key_here + # Only needed if using Dashboard configuration + VITE_VAPI_ASSISTANT_ID=your_assistant_id_here + ``` - - Once you have your assistant's ID, you can start a call with it: - - Assistant ID in dashboard - + + ```typescript title="components/VoiceButton.tsx" + import Vapi from '@vapi-ai/web'; + import { useState } from 'react'; + + export function VoiceButton() { + const [vapi] = useState(() => new Vapi(import.meta.env.VITE_VAPI_API_KEY)); + const [isActive, setIsActive] = useState(false); + + const toggleCall = async () => { + if (isActive) { + vapi.stop(); + } else { + // Option 1: Use Dashboard-configured assistant + if (import.meta.env.VITE_VAPI_ASSISTANT_ID) { + await vapi.start(import.meta.env.VITE_VAPI_ASSISTANT_ID); + } else { + // Option 2: Configure assistant directly in SDK + await vapi.start({ + model: { + provider: "openai", + model: "gpt-4o-2024-05-13", + messages: [ + { + role: "system", + content: "You are a helpful customer support assistant for TechCorp. You can help with order status, account questions, product information, and technical support. Be friendly, professional, and concise." + } + ] + }, + voice: { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + firstMessage: "Hi! I'm here to help with your TechCorp support needs. How can I assist you today?", + }); + } + } + }; + + vapi.on('call-start', () => setIsActive(true)); + vapi.on('call-end', () => setIsActive(false)); - ```javascript - vapi.start("YOUR_ASSISTANT_ID_FROM_THE_DASHBOARD"); + return ( + + ); + } ``` - - To override assistant settings or set template variables, pass an `assistantOverrides` object as the second argument. - - ```javascript - const assistantOverrides = { - transcriber: { - provider: "deepgram", - model: "nova-2", - language: "en-US", - }, - recordingEnabled: false, - variableValues: { - name: "John", - }, - }; - vapi.start("YOUR_ASSISTANT_ID_FROM_THE_DASHBOARD", assistantOverrides); + + ```typescript title="src/App.tsx" + import { VoiceButton } from './components/VoiceButton'; + + function App() { + return ( +
+

TechCorp Customer Support

+

+ Need help? Click the button below to speak with our AI support assistant. +

+ +
+ ); + } + + export default App; ``` + + + ```javascript title="main.js" + import Vapi from '@vapi-ai/web'; + + const vapi = new Vapi('pk_your_public_key_here'); + const button = document.getElementById('voice-btn'); + let isActive = false; + + button.addEventListener('click', async () => { + if (isActive) { + vapi.stop(); + } else { + // Option 1: Use Dashboard-configured assistant + // await vapi.start('your_assistant_id'); + + // Option 2: Configure assistant directly in SDK + await vapi.start({ + model: { + provider: "openai", + model: "gpt-4o-2024-05-13", + messages: [ + { + role: "system", + content: "You are a helpful customer support assistant for TechCorp. You can help with order status, account questions, product information, and technical support. Be friendly, professional, and concise." + } + ] + }, + voice: { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + firstMessage: "Hi! I'm here to help with your TechCorp support needs. How can I assist you today?", + }); + } + }); + + vapi.on('call-start', () => { + isActive = true; + button.textContent = 'End Call'; + }); + + vapi.on('call-end', () => { + isActive = false; + button.textContent = 'Start Call'; + }); + ``` + + +## Customize an Assistant + +### Start and Stop Calls + +Start voice conversations with your AI assistant using either a pre-configured assistant ID or inline configuration. You can customize the model, voice, and behavior on-the-fly. + +```typescript +import Vapi from "@vapi-ai/web"; +import { CreateAssistantDTO } from "@vapi-ai/web/dist/api"; + +// Initialize Vapi +const vapi = new Vapi('pk_your_public_key'); + +// Start a call with assistant ID (Dashboard configuration) +await vapi.start('your_assistant_id'); + +// Start with inline assistant config (SDK configuration) +const assistantConfig: CreateAssistantDTO = { + model: { + provider: "openai", + model: "gpt-4o-2024-05-13", + messages: [ + { + role: "system", + content: "You are a helpful customer support assistant for TechCorp. You can help with order status, account questions, product information, and technical support. Be friendly, professional, and concise." + } + ] + }, + voice: { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + firstMessage: "Hi! I'm here to help with your TechCorp support needs. How can I assist you today?", +}; +await vapi.start(assistantConfig); + +// End a call +vapi.stop(); +``` + +### Handle Events + +Monitor call lifecycle, speech activity, and real-time transcription. These events help you build responsive UIs and handle call state changes. + +```typescript +// Call lifecycle events +vapi.on('call-start', () => { + console.log('Customer support call started'); +}); + +vapi.on('call-end', () => { + console.log('Customer support call ended'); +}); + +// Speech events +vapi.on('speech-start', () => { + console.log('Customer started speaking'); +}); + +vapi.on('speech-end', () => { + console.log('Customer stopped speaking'); +}); + +// Message events +vapi.on('message', (message) => { + console.log('Received message:', message); +}); + +// Volume level (for visualizations) +vapi.on('volume-level', (level) => { + console.log('Volume level:', level); +}); + +// Error handling +vapi.on('error', (error) => { + console.error('Call error:', error); +}); +``` + +### Send Messages + +Inject context or trigger actions by sending messages to your assistant during an active call. Useful for providing real-time updates or user interface interactions. + +```typescript +// Send customer context when they log in +vapi.send({ + type: 'add-message', + message: { + role: 'system', + content: 'Customer John Doe (ID: 12345) has logged in. Recent orders: #ORD-789, #ORD-456.' + } +}); + +// Add tool call result for order lookup +vapi.send({ + type: 'add-message', + message: { + role: 'tool', + content: { + name: 'getOrderStatus', + parameters: { orderId: 'ORD-789' }, + } + } +}); +``` + +### Mute the Microphone + +Control microphone input during calls. Essential for privacy and managing when the assistant should listen to user speech. + +```typescript +// Mute/unmute the microphone +vapi.setMuted(true); // Mute +vapi.setMuted(false); // Unmute + +// Check if muted +const isMuted = vapi.isMuted(); +``` + +### Assistant Overrides + +Customize assistant behavior for specific calls without modifying your base assistant configuration in Vapi Dashboard. Override transcription settings, recording options, conversation flow, etc. + +```typescript +const vapi = new Vapi('pk_your_key'); + +const overrides: OverrideAssistantDTO = { + // Assistant overrides for customer support + firstMessageMode: 'assistant-waits-for-user', // wait for customer to speak first + recordingEnabled: true, // record calls for quality assurance + + // Use Deepgram for better customer service transcription + transcriber: { + provider: 'deepgram', + model: 'nova-2', + language: 'en-US' + }, + + // Custom summary for support tickets + analysisPlan: { + summaryPrompt: 'Summarize this customer support conversation including: customer issue, resolution provided, and any follow-up needed.', + }, +}; + +// Start call with overrides +await vapi.start('your_assistant_id', overrides); +``` + +### Add Custom Tools + +Enable your assistant to call external functions and APIs for order lookups, account management, and more. + +```typescript +// Customer support assistant with function calling +const customerSupportAssistant: CreateAssistantDTO = { + model: { + provider: "openai", + model: "gpt-4o-2024-05-13", + tools: [ + { + type: "function", + function: { + name: "get_order_status", + description: "Get the current status of a customer order", + parameters: { + type: "object", + properties: { + orderId: { + type: "string", + description: "The order ID to look up" + } + }, + required: ["orderId"] + } + } + }, + { + type: "function", + function: { + name: "get_account_info", + description: "Get customer account information", + parameters: { + type: "object", + properties: { + customerId: { + type: "string", + description: "The customer ID" + } + }, + required: ["customerId"] + } + } + } + ], + messages: [ + { + role: "system", + content: "You are a helpful customer support assistant for TechCorp. You can help with order status, account questions, product information, and technical support. Use the available tools to look up specific information when customers provide order numbers or account details." + } + ] + }, + voice: { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + serverUrl: "https://your-domain.com/api/webhook", + firstMessage: "Hi! I'm here to help with your TechCorp support needs. I can look up order status, account information, and answer product questions. How can I assist you today?", +}; + +await vapi.start(customerSupportAssistant); +``` + +### Enable Video Recording + +Capture video recordings of customer support calls for compliance, training and quality assurance purposes. + +```typescript +// Customer support assistant with video recording enabled +const videoSupportAssistant = { + model: { + provider: "openai", + model: "gpt-4o-2024-11-20", + messages: [ + { + role: "system", + content: "You are a helpful customer support assistant for TechCorp. This call is being recorded for quality assurance purposes." + } + ] + }, + voice: { + provider: "11labs", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + artifactPlan: { + videoRecordingEnabled: true, + recordingEnabled: true, + }, + firstMessage: "Hi! I'm here to help with your TechCorp support needs. Please note this call is being recorded for quality assurance. How can I assist you today?", +}; + +await vapi.start(videoSupportAssistant); +``` + +## Next Steps + + + + Complete Web SDK documentation + + + Complete API reference documentation + + + + + **Need help?** Join our [Discord community](https://discord.gg/vapi) or check out the [full documentation](/overview). +