Web Calling
Get started with Vapi on the Web.
Anywhere you can run client-side JavaScript, you can run Vapi. All the way from vanilla to complex component-based applications with React and Next.js.
Installation
Install the package:
or w/ npm:
Import the package:
Then, create a new instance of the Vapi class, passing your Public Key as a parameter to the constructor:
You can find your public key in the Vapi Dashboard.
Starting a Call
Assistants can either be created on the fly (temporary) or created & persisted to your account (persistent).
Option 1: Temporary Assistant
If you want to customize properties from the frontend on the fly, you can create an assistant configuration object and pass it to the .start()
method.
Assistant Configuration
Here are the options we will pass to .start()
:
Let’s break down the configuration options we passed:
- name: the display name for the assistant in our dashboard (for internal purposes only)
- firstMessage: the first message that our assistant will say when it picks up the web call
- transcriber: the transcriber is what turns user speech into processable text for our LLM. This is the first step in the end-to-end voice pipeline. We are using Deepgram for transcription, specifically, their
Nova 2
model. We also set the language to be transcribed as English. - voice: the final portion of the voice pipeline is turning LLM output-text into speech. This process is called “Text-to-speech” (or TTS for short). We use a voice provider called PlayHT, & a voice provided by them called
jennifer
. - model: for our LLM, we use
gpt-4
(from OpenAI) & set our system prompt for the assistant. The system prompt configures the context, role, personality, instructions and so on for the assistant. In our case, the system prompt above will give us the behaviour we want.
Now we can call .start()
, passing the temporary assistant configuration:
More configuration options can be found in the Assistant API reference.
Option 2: Persistent Assistant
If you want to create an assistant that you can reuse across multiple calls, you can create a persistent assistant in the Vapi Dashboard. Here’s how you can do that:
Sign-up or Log-in to Vapi
If you haven’t already signed-up, you’re going to need an account before you can use the web dashboard. When you visit dashboard.vapi.ai you may see something like this:
Sign-up for an account (or log-in to your existing account) — you will then find yourself inside the web dashboard. It will look something like this:
Create an Assistant
Now that you’re in your dashboard, we’re going to create an assistant.
Assistants are at the heart of how Vapi models AI voice agents — we will be setting certain properties on a new assistant to model an order-taking agent.
Once in the “Assistants” dashboard tab (you should be in it by-default after log-in), you will see a button to create a new assistant.
After clicking the create new assistant button, you will see a pop-up modal that asks you to pick a starter template. For our example we will start from a blank slate so choose the Blank Template
option.
You will then be able to name your assistant — you can name it whatever you’d like (Vapi’s Pizza Front Desk
, for example):
This name is only for internal labeling use. It is not an identifier, nor will the assistant be aware of this name.
Once you have named your assistant, you can hit “Create” to create it. You will then see something like this:
This is the assistant overview view — it gives you the ability to edit different attributes about your assistant, as well as see cost & latency projection information for each portion of it’s voice pipeline (this is very important data to have handy when building out your assistants).
Model Setup
Now we’re going to set the “brains” of the assistant, the large language model. We’re going to be using GPT-4
(from OpenAI) for this demo (though you’re free to use GPT-3.5
, or any one of your favorite LLMs).
Set Your OpenAI Provider Key (optional)
Before we proceed, we can set our provider key for OpenAI (this is just your OpenAI secret key).
You can see all of your provider keys in the “Provider Keys” dashboard tab. You can also go directly to dashboard.vapi.ai/keys.
Vapi uses provider keys you provide to communicate with LLM, TTS, & STT vendors on your behalf. It is most ideal that we set keys for the vendors we intend to use ahead of time.
While we’re here it’d be ideal for you to go & set up provider keys for other providers you’re familiar with & intend to use later.
Set a First Message
Assistants can optionally be configured with a First Message
. This first message will be spoken by your assistant when either:
- A Web Call Connects: when a web call is started with your assistant
- An Inbound Call is Picked-up: an inbound call is picked-up & answered by your assistant
- An Outbound Call is Dialed & Picked-up: an outbound call is dialed by your assistant & a person picks up
Note that this first message cannot be interrupted & is guaranteed to be spoken. Certain use cases need a first message, while others do not.
For our use case, we will want a first message. It would be ideal for us to have a first message like this:
Some text-to-speech voices may struggle to pronounce ‘Vapi’ correctly, compartmentalizing it to be spoken letter by letter “V. A. P. I.”
Some aspects of configuring your voice pipeline will require tweaks like this to get the target behaviour you want.
This will be spoken by the assistant when a web or inbound phone call is received.
Set the System Prompt
We will now set the System Prompt
for our assistant. If you’re familiar with OpenAI’s API, this is the first prompt in the message list that we feed our LLM (learn more about prompt engineering on the OpenAI docs).
The system prompt can be used to configure the context, role, personality, instructions and so on for the assistant. In our case, a system prompt like this will give us the behaviour we want:
You can copy & paste the above prompt into the System Prompt
field. Now the model configuration for your assistant should look something like this:
Transcriber Setup
The transcriber is what turns user speech into processable text for our LLM. This is the first step in the end-to-end voice pipeline.
Set Your Deepgram Provider Key (optional)
We will be using Deepgram (which provides blazing-fast & accurate Speech-to-Text) as our STT provider.
We will set our provider key for them in “Provider Keys”:
Set Transcriber
We will set the model to Nova 2
& the language to en
for English. Now your assistant’s transcriber configuration should look something like this:
Voice Setup
The final portion of the voice pipeline is turning LLM output-text into speech. This process is called “Text-to-speech” (or TTS for short).
We will be using a voice provider called PlayHT (they have very conversational voices), & a voice provided by them labeled Jennifer
(female
, en-US
).
You are free to use your favorite TTS voice platform here. ElevenLabs is another alternative — by now you should get the flow of plugging in vendors into Vapi (add provider key + pick provider in assistant config).
You can skip the next step(s) if you don’t intend to use PlayHT.
Set Your PlayHT Provider Key (optional)
If you haven’t already, sign up for an account with PlayHT at play.ht. Since their flows are liable to change — you can just grab your API Key
& User ID
from them.
Set Voice
You will want to select playht
in the “provider” field, & Jennifer
in the “voice” field. We will leave all of the other settings untouched.
To customize additional fields, this can be done via the Assistant API instead.
Then, you can copy the assistant’s ID at the top of the assistant detail page:
Now we can call .start()
, passing the persistent assistant’s ID:
If you need to override any assistant settings or set template variables, you can pass assistantOverrides
as the second argument.
For example, if the first message is “Hello {{name}}
”, you can set assistantOverrides
to replace {{name}}
with John
: