Web SDK

The Vapi Web SDK provides web developers a simple API for interacting with the realtime call functionality of Vapi.

Installation

Install the package:

$
yarn add @vapi-ai/web

or w/ npm:

$
npm install @vapi-ai/web

Importing

Import the package:

1
import Vapi from "@vapi-ai/web";

Then, create a new instance of the Vapi class, passing your Public Key as a parameter to the constructor:

1
const vapi = new Vapi("your-public-key");

You can find your public key in the Vapi Dashboard.

Usage

.start()

You can start a web call by calling the .start() function. The start function can either accept:

1. a string, representing an assistant ID
2. an object, representing a set of assistant configs (see Create Assistant)

The start function returns a promise that resolves to a call object. For example:

1
const call = await vapi.start(assistantId);
2
// { "id": "bd2184a1-bdea-4d4f-9503-b09ca8b185e6", "orgId": "6da6841c-0fca-4604-8941-3d5d65f43a17", "createdAt": "2024-11-13T19:20:24.606Z", "updatedAt": "2024-11-13T19:20:24.606Z", "type": "webCall", ... }

Passing an Assistant ID

If you already have an assistant that you created (either via the Dashboard or the API), you can start the call with the assistant’s ID:

1
vapi.start("79f3XXXX-XXXX-XXXX-XXXX-XXXXXXXXce48");

Passing Assistant Configuration Inline

You can also specify configuration for your assistant inline.

This will not create a persistent assistant that is saved to your account, rather it will create an ephemeral assistant only used for this call specifically.

You can pass the assistant’s configuration in an object (see Create Assistant for a list of acceptable fields):

1
vapi.start({
2
  transcriber: {
3
    provider: "deepgram",
4
    model: "nova-2",
5
    language: "en-US",
6
  },
7
  model: {
8
    provider: "openai",
9
    model: "gpt-3.5-turbo",
10
    messages: [
11
      {
12
        role: "system",
13
        content: "You are a helpful assistant.",
14
      },
15
    ],
16
  },
17
  voice: {
18
    provider: "playht",
19
    voiceId: "jennifer",
20
  },
21
  name: "My Inline Assistant",
22
  ...
23
});

Overriding Assistant Configurations

To override assistant settings or set template variables, you can pass assistantOverrides as the second argument.

For example, if the first message is “Hello {{name}}”, set assistantOverrides to the following to replace {{name}} with John:

1
const assistantOverrides = {
2
  transcriber: {
3
    provider: "deepgram",
4
    model: "nova-2",
5
    language: "en-US",
6
  },
7
  recordingEnabled: false,
8
  variableValues: {
9
    name: "Alice",
10
  },
11
};
12
13
vapi.start("79f3XXXX-XXXX-XXXX-XXXX-XXXXXXXXce48", assistantOverrides);

.send()

During the call, you can send intermediate messages to the assistant (like background messages).

• type will always be "add-message"
• the message field will have 2 items, role and content.

1
vapi.send({
2
  type: "add-message",
3
  message: {
4
    role: "system",
5
    content: "The user has pressed the button, say peanuts",
6
  },
7
});

.stop()

You can stop the call session by calling the stop method:

1
vapi.stop();

This will stop the recording and close the connection.

.isMuted()

Check if the user’s microphone is muted:

1
vapi.isMuted();

.setMuted(muted: boolean)

You can mute & unmute the user’s microphone with setMuted:

1
vapi.isMuted(); // false
2
vapi.setMuted(true);
3
vapi.isMuted(); // true

say(message: string, endCallAfterSpoken?: boolean)

The say method can be used to invoke speech and gracefully terminate the call if needed

1
vapi.say("Our time's up, goodbye!", true)

Events

You can listen on the vapi instance for events. These events allow you to react to changes in the state of the call or user speech.

speech-start

Occurs when your AI assistant has started speaking.

1
vapi.on("speech-start", () => {
2
  console.log("Assistant speech has started.");
3
});

speech-end

Occurs when your AI assistant has finished speaking.

1
vapi.on("speech-end", () => {
2
  console.log("Assistant speech has ended.");
3
});

call-start

Occurs when the call has connected & begins.

1
vapi.on("call-start", () => {
2
  console.log("Call has started.");
3
});

call-end

Occurs when the call has disconnected & ended.

1
vapi.on("call-end", () => {
2
  console.log("Call has ended.");
3
});

volume-level

Realtime volume level updates for the assistant. A floating-point number between 0 & 1.

1
vapi.on("volume-level", (volume) => {
2
  console.log(`Assistant volume level: ${volume}`);
3
});

message

Various assistant messages can be sent back to the client during the call. These are the same messages that your server would receive.

At assistant creation time, you can specify on the clientMessages field the set of messages you’d like the assistant to send back to the client.

Those messages will come back via the message event:

1
// Various assistant messages can come back (like function calls, transcripts, etc)
2
vapi.on("message", (message) => {
3
  console.log(message);
4
});

error

Handle errors that occur during the call.

1
vapi.on("error", (e) => {
2
  console.error(e);
3
});

Resources