# Introduction
> Build voice AI agents that can make and receive phone calls
## What is Vapi?
Vapi is the developer platform for building voice AI agents. We handle the complex infrastructure so you can focus on creating great voice experiences.
**Voice agents** allow you to:
* Have natural conversations with users
* Make and receive phone calls
* Integrate with your existing systems and APIs
* Handle complex workflows like appointment scheduling, customer support, and more
## How voice agents work
Every Vapi assistant combines three core technologies:
Converts user speech into text that your agent can understand
Processes the conversation and generates intelligent responses
Converts your agent's responses back into natural speech
You have full control over each component, with dozens of providers and models to choose from; OpenAI, Anthropic, Google, Deepgram, ElevenLabs, and many, many more.
## Two ways to build voice agents
Vapi offers two main primitives for building voice agents, each designed for different use cases:
**Best for:** Quick kickstart for simple conversations
Assistants use a single system prompt to control behavior. Perfect for:
* Customer support chatbots
* Simple question-answering agents
* Getting started quickly with minimal setup
**Best for:** Complex logic and multi-step processes
Workflows use visual decision trees and conditional logic. Perfect for:
* Appointment scheduling with availability checks
* Lead qualification with branching questions
* Complex customer service flows with escalation
## Key capabilities
* **Real-time conversations:** Sub-600ms response times with natural turn-taking
* **Phone integration:** Make and receive calls on any phone number
* **Web integration:** Embed voice calls directly in your applications
* **Tool integration:** Connect to your APIs, databases, and existing systems
* **Custom workflows:** Build complex multi-step processes with decision trees
## Choose your path
* Create a voice agent for inbound/outbound calls
* Build customer support or sales automation
* Get started with no coding required
*Build your first voice agent in 5 minutes using our dashboard.*
* Add voice capabilities to your web application
* Integrate voice chat into your existing product
* Build with code and SDKs
*Embed live voice conversations directly in your app.*
## Developer tools
### Vapi CLI
The Vapi CLI brings the full power of the platform to your terminal:
Install in seconds with:
```bash
curl -sSL https://vapi.ai/install.sh | bash
```
Everything from the dashboard, now in your terminal.
* **Project Integration:** Auto-detect and set up Vapi in any codebase
* **Webhook Forwarding:** Test webhooks on your local server
* **MCP Support:** Turn your IDE into a Vapi expert
* **Multi-account:** Switch between environments seamlessly
## Popular use cases
Built with Assistants
Automate inbound support calls with agents that can access your knowledge base and escalate to humans when needed.
Built with Workflows
Make outbound sales calls, qualify leads, and schedule appointments with sophisticated branching logic.
Built with Workflows
Handle booking requests, check availability, and confirm appointments with conditional routing.
Built with Workflows
Emergency routing and appointment scheduling for healthcare.
Built with Workflows
Order tracking, returns, and customer support workflows.
See our collection of examples covering a wide range of use cases.
# Phone calls
> Learn to make your first phone call with a voice agent
## Overview
Vapi makes it easy to build voice agents that can make and receive phone calls. In under 5 minutes, you'll create a voice assistant and start talking to it over the phone.
**In this quickstart, you'll learn to:**
* Create an assistant using the Dashboard or programmatically
* Set up a phone number
* Make your first inbound and outbound calls
## Prerequisites
* [A Vapi account](https://dashboard.vapi.ai)
* For SDK usage: API key from the Dashboard
**Using the Vapi CLI?** You can create assistants, manage phone numbers, and make calls directly from your terminal:
```bash
# Install the CLI
curl -sSL https://vapi.ai/install.sh | bash
# Login and create an assistant
vapi login
vapi assistant create
```
[Learn more about the Vapi CLI →](/cli)
## Create your first voice assistant
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
In the dashboard, create a new assistant using the customer support specialist template.
Set the first message and system prompt for your assistant:
**First message:**
```plaintext
Hi there, this is Alex from TechSolutions customer support. How can I help you today?
```
**System prompt:**
```plaintext
You are Alex, a customer service voice assistant for TechSolutions. Your primary purpose is to help customers resolve issues with their products, answer questions about services, and ensure a satisfying support experience.
- Sound friendly, patient, and knowledgeable without being condescending
- Use a conversational tone with natural speech patterns
- Speak with confidence but remain humble when you don't know something
- Demonstrate genuine concern for customer issues
```
```bash title="npm"
npm install @vapi-ai/server-sdk
```
```bash title="yarn"
yarn add @vapi-ai/server-sdk
```
```bash title="pnpm"
pnpm add @vapi-ai/server-sdk
```
```bash title="bun"
bun add @vapi-ai/server-sdk
```
```typescript
import { VapiClient } from '@vapi-ai/server-sdk';
// Initialize the Vapi client
const vapi = new VapiClient({
token: 'your-api-key', // Replace with your actual API key
});
// Define the system prompt for customer support
const systemPrompt = `You are Alex, a customer service voice assistant for TechSolutions. Your primary purpose is to help customers resolve issues with their products, answer questions about services, and ensure a satisfying support experience.
- Sound friendly, patient, and knowledgeable without being condescending
- Use a conversational tone with natural speech patterns
- Speak with confidence but remain humble when you don'\''t know something
- Demonstrate genuine concern for customer issues`;
async function createSupportAssistant() {
try {
const assistant = await vapi.assistants.create({
name: 'Customer Support Assistant',
// Configure the AI model
model: {
provider: 'openai',
model: 'gpt-4o',
messages: [
{
role: 'system',
content: systemPrompt,
},
],
},
// Configure the voice
voice: {
provider: 'playht',
voice_id: 'jennifer',
},
// Set the first message
firstMessage: 'Hi there, this is Alex from TechSolutions customer support. How can I help you today?',
});
console.log('Assistant created:', assistant.id);
return assistant;
} catch (error) {
console.error('Error creating assistant:', error);
throw error;
}
}
// Create the assistant
createSupportAssistant();
```
```bash
pip install vapi_server_sdk
```
```python
from vapi import Vapi
# Initialize the Vapi client
client = Vapi(token="your-api-key") # Replace with your actual API key
# Define the system prompt for customer support
system_prompt = """You are Alex, a customer service voice assistant for TechSolutions. Your primary purpose is to help customers resolve issues with their products, answer questions about services, and ensure a satisfying support experience.
- Sound friendly, patient, and knowledgeable without being condescending
- Use a conversational tone with natural speech patterns
- Speak with confidence but remain humble when you don't know something
- Demonstrate genuine concern for customer issues"""
def create_support_assistant():
try:
assistant = client.assistants.create(
name="Customer Support Assistant",
# Configure the AI model
model={
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": system_prompt,
}
],
},
# Configure the voice
voice={
"provider": "playht",
"voice_id": "jennifer",
},
# Set the first message
first_message="Hi there, this is Alex from TechSolutions customer support. How can I help you today?",
)
print(f"Assistant created: {assistant.id}")
return assistant
except Exception as error:
print(f"Error creating assistant: {error}")
raise error
# Create the assistant
create_support_assistant()
```
```bash
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support Assistant",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are Alex, a customer service voice assistant for TechSolutions. Your primary purpose is to help customers resolve issues with their products, answer questions about services, and ensure a satisfying support experience.\n- Sound friendly, patient, and knowledgeable without being condescending\n- Use a conversational tone with natural speech patterns\n- Speak with confidence but remain humble when you don'\''t know something\n- Demonstrate genuine concern for customer issues"
}
]
},
"voice": {
"provider": "playht",
"voice_id": "jennifer"
},
"firstMessage": "Hi there, this is Alex from TechSolutions customer support. How can I help you today?"
}'
```
## Set up a phone number
In the Phone Numbers tab, create a free US phone number or import an existing number from another provider.
Free Vapi phone numbers are only available for US national use. For international calls, you'll need to import a number from Twilio or another provider.
Select your assistant in the inbound settings for your phone number. When this number is called, your assistant will automatically answer.
```typescript
async function purchasePhoneNumber() {
try {
// Purchase a phone number
const phoneNumber = await vapi.phoneNumbers.create({
fallbackDestination: {
type: 'number',
number: '+1234567890', // Your fallback number
},
});
console.log('Phone number created:', phoneNumber.number);
return phoneNumber;
} catch (error) {
console.error('Error creating phone number:', error);
throw error;
}
}
```
```typescript
async function configureInboundCalls(phoneNumberId: string, assistantId: string) {
try {
// Update phone number with assistant configuration
const updatedNumber = await vapi.phoneNumbers.update(phoneNumberId, {
assistantId: assistantId,
});
console.log('Phone number configured for inbound calls');
return updatedNumber;
} catch (error) {
console.error('Error configuring phone number:', error);
throw error;
}
}
```
```python
def purchase_phone_number():
try:
# Purchase a phone number
phone_number = client.phone_numbers.create(
fallback_destination={
"type": "number",
"number": "+1234567890", # Your fallback number
}
)
print(f"Phone number created: {phone_number.number}")
return phone_number
except Exception as error:
print(f"Error creating phone number: {error}")
raise error
```
```python
def configure_inbound_calls(phone_number_id: str, assistant_id: str):
try:
# Update phone number with assistant configuration
updated_number = client.phone_numbers.update(
phone_number_id,
assistant_id=assistant_id,
)
print("Phone number configured for inbound calls")
return updated_number
except Exception as error:
print(f"Error configuring phone number: {error}")
raise error
```
```bash
curl -X POST "https://api.vapi.ai/phone-number" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"fallbackDestination": {
"type": "number",
"number": "+1234567890"
}
}'
```
```bash
curl -X PATCH "https://api.vapi.ai/phone-number/{phone-number-id}" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id"
}'
```
## Make your first calls
Call the phone number you just created. Your assistant will pick up and start the conversation with your configured first message.
**Using the Dashboard:**
In the dashboard, go to the outbound calls section:
1. Enter your own phone number as the target
2. Select your assistant
3. Click "Make Call"
**Using the SDK:**
```typescript
async function makeOutboundCall(assistantId: string, phoneNumber: string) {
try {
const call = await vapi.calls.create({
assistant: {
assistantId: assistantId,
},
phoneNumberId: 'your-phone-number-id', // Your Vapi phone number ID
customer: {
number: phoneNumber, // Target phone number
},
});
console.log('Outbound call initiated:', call.id);
return call;
} catch (error) {
console.error('Error making outbound call:', error);
throw error;
}
}
// Make a call to your own number for testing
makeOutboundCall('your-assistant-id', '+1234567890');
```
```python
def make_outbound_call(assistant_id: str, phone_number: str):
try:
call = client.calls.create(
assistant_id=assistant_id,
phone_number_id="your-phone-number-id", # Your Vapi phone number ID
customer={
"number": phone_number, # Target phone number
},
)
print(f"Outbound call initiated: {call.id}")
return call
except Exception as error:
print(f"Error making outbound call: {error}")
raise error
# Make a call to your own number for testing
make_outbound_call("your-assistant-id", "+1234567890")
```
```bash
curl -X POST "https://api.vapi.ai/call" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"assistant": {
"assistantId": "your-assistant-id"
},
"phoneNumberId": "your-phone-number-id",
"customer": {
"number": "+1234567890"
}
}'
```
Your assistant will call the specified number immediately.
You can also test your assistant directly in the dashboard by clicking the call button—no phone number required.
## Next steps
Now that you have a working voice assistant:
* **Customize the conversation:** Update the system prompt to match your use case
* **Add tools:** Connect your assistant to external APIs and databases
* **Configure models:** Try different speech and language models for better performance
* **Scale with APIs:** Use Vapi's REST API to create assistants programmatically
Ready to integrate voice into your application? Check out the [Web integration guide](/quickstart/web-integration) to embed voice calls directly in your app.
# Web calls
> Build voice interfaces and backend integrations using Vapi's Web and Server SDKs
## Overview
Build powerful voice applications that work across web browsers, mobile apps, and backend systems. This guide covers both client-side voice interfaces and server-side call management using Vapi's comprehensive SDK ecosystem.
**In this quickstart, you'll learn to:**
* Create real-time voice interfaces for web and mobile
* Build automated outbound and inbound call systems
* Handle events and webhooks for call management
* Implement voice widgets and backend integrations
**Developing locally?** The Vapi CLI makes it easy to initialize projects and test webhooks:
```bash
# Initialize Vapi in your project
vapi init
# Forward webhooks to local server
vapi listen --forward-to localhost:3000/webhook
```
[Learn more about the Vapi CLI →](/cli)
## Choose your integration approach
**Best for:** User-facing applications, voice widgets, mobile apps
* Browser-based voice assistants and widgets
* Real-time voice conversations
* Mobile voice applications (iOS, Android, React Native, Flutter)
* Direct user interaction with assistants
**Best for:** Backend automation, bulk operations, system integrations
* Automated outbound call campaigns
* Inbound call routing and management
* CRM integrations and bulk operations
* Webhook processing and real-time events
## Web voice interfaces
Build browser-based voice assistants and widgets for real-time user interaction.
### Installation and setup
Build browser-based voice interfaces:
```bash title="npm"
npm install @vapi-ai/web
```
```bash title="yarn"
yarn add @vapi-ai/web
```
```bash title="pnpm"
pnpm add @vapi-ai/web
```
```bash title="bun"
bun add @vapi-ai/web
```
```typescript
import Vapi from '@vapi-ai/web';
const vapi = new Vapi('YOUR_PUBLIC_API_KEY');
// Start voice conversation
vapi.start('YOUR_ASSISTANT_ID');
// Listen for events
vapi.on('call-start', () => console.log('Call started'));
vapi.on('call-end', () => console.log('Call ended'));
vapi.on('message', (message) => {
if (message.type === 'transcript') {
console.log(`${message.role}: ${message.transcript}`);
}
});
```
Build voice-enabled mobile apps:
```bash
npm install @vapi-ai/react-native
```
```jsx
import { VapiProvider, useVapi } from '@vapi-ai/react-native';
const VoiceApp = () => {
const { start, stop, isConnected } = useVapi();
return (
);
};
export default () => (
);
```
Create voice apps with Flutter:
```yaml
dependencies:
vapi_flutter: ^1.0.0
```
```dart
import 'package:vapi_flutter/vapi_flutter.dart';
class VoiceWidget extends StatefulWidget {
@override
_VoiceWidgetState createState() => _VoiceWidgetState();
}
class _VoiceWidgetState extends State {
final VapiClient _vapi = VapiClient('YOUR_PUBLIC_API_KEY');
bool _isConnected = false;
@override
Widget build(BuildContext context) {
return ElevatedButton(
onPressed: () {
if (_isConnected) {
_vapi.stop();
} else {
_vapi.start('YOUR_ASSISTANT_ID');
}
},
child: Text(_isConnected ? 'End Call' : 'Start Call'),
);
}
}
```
Build native iOS voice apps:
```swift
import VapiSDK
class VoiceViewController: UIViewController {
private let vapi = VapiClient(apiKey: "YOUR_PUBLIC_API_KEY")
@IBAction func startCallTapped(_ sender: UIButton) {
vapi.start(assistantId: "YOUR_ASSISTANT_ID")
}
override func viewDidLoad() {
super.viewDidLoad()
vapi.delegate = self
}
}
extension VoiceViewController: VapiClientDelegate {
func vapiCallDidStart() {
print("Call started")
}
func vapiCallDidEnd() {
print("Call ended")
}
}
```
### Voice widget implementation
Create a voice widget for your website:
The fastest way to get started. Copy this snippet into your website:
```html
```
Build a complete React voice widget:
```tsx
import React, { useState, useEffect } from 'react';
import Vapi from '@vapi-ai/web';
interface VapiWidgetProps {
apiKey: string;
assistantId: string;
config?: Record;
}
const VapiWidget: React.FC = ({
apiKey,
assistantId,
config = {}
}) => {
const [vapi, setVapi] = useState(null);
const [isConnected, setIsConnected] = useState(false);
const [isSpeaking, setIsSpeaking] = useState(false);
const [transcript, setTranscript] = useState>([]);
useEffect(() => {
const vapiInstance = new Vapi(apiKey);
setVapi(vapiInstance);
// Event listeners
vapiInstance.on('call-start', () => {
console.log('Call started');
setIsConnected(true);
});
vapiInstance.on('call-end', () => {
console.log('Call ended');
setIsConnected(false);
setIsSpeaking(false);
});
vapiInstance.on('speech-start', () => {
console.log('Assistant started speaking');
setIsSpeaking(true);
});
vapiInstance.on('speech-end', () => {
console.log('Assistant stopped speaking');
setIsSpeaking(false);
});
vapiInstance.on('message', (message) => {
if (message.type === 'transcript') {
setTranscript(prev => [...prev, {
role: message.role,
text: message.transcript
}]);
}
});
vapiInstance.on('error', (error) => {
console.error('Vapi error:', error);
});
return () => {
vapiInstance?.stop();
};
}, [apiKey]);
const startCall = () => {
if (vapi) {
vapi.start(assistantId);
}
};
const endCall = () => {
if (vapi) {
vapi.stop();
}
};
return (
);
};
export default VapiWidget;
// Usage in your app:
//
```
## Server-side call management
Automate outbound calls and handle inbound call processing with server-side SDKs.
### Installation and setup
Install the TypeScript Server SDK:
```bash title="npm"
npm install @vapi-ai/server-sdk
```
```bash title="yarn"
yarn add @vapi-ai/server-sdk
```
```bash title="pnpm"
pnpm add @vapi-ai/server-sdk
```
```bash title="bun"
bun add @vapi-ai/server-sdk
```
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({
token: process.env.VAPI_API_KEY!
});
// Create an outbound call
const call = await vapi.calls.create({
phoneNumberId: "YOUR_PHONE_NUMBER_ID",
customer: { number: "+1234567890" },
assistantId: "YOUR_ASSISTANT_ID"
});
console.log(`Call created: ${call.id}`);
```
Install the Python Server SDK:
```bash
pip install vapi_server_sdk
```
```python
from vapi import Vapi
vapi = Vapi(token=os.getenv("VAPI_API_KEY"))
# Create an outbound call
call = vapi.calls.create(
phone_number_id="YOUR_PHONE_NUMBER_ID",
customer={"number": "+1234567890"},
assistant_id="YOUR_ASSISTANT_ID"
)
print(f"Call created: {call.id}")
```
Add the Java SDK to your project:
```xml
ai.vapiserver-sdk1.0.0
```
```java
import ai.vapi.VapiClient;
import ai.vapi.models.Call;
VapiClient vapi = VapiClient.builder()
.apiKey(System.getenv("VAPI_API_KEY"))
.build();
// Create an outbound call
Call call = vapi.calls().create(CreateCallRequest.builder()
.phoneNumberId("YOUR_PHONE_NUMBER_ID")
.customer(Customer.builder().number("+1234567890").build())
.assistantId("YOUR_ASSISTANT_ID")
.build());
System.out.println("Call created: " + call.getId());
```
Install the Ruby Server SDK:
```bash
gem install vapi-server-sdk
```
```ruby
require 'vapi'
vapi = Vapi::Client.new(api_key: ENV['VAPI_API_KEY'])
# Create an outbound call
call = vapi.calls.create(
phone_number_id: "YOUR_PHONE_NUMBER_ID",
customer: { number: "+1234567890" },
assistant_id: "YOUR_ASSISTANT_ID"
)
puts "Call created: #{call.id}"
```
Install the C# Server SDK:
```bash
dotnet add package Vapi.ServerSDK
```
```csharp
using Vapi;
var vapi = new VapiClient(Environment.GetEnvironmentVariable("VAPI_API_KEY"));
// Create an outbound call
var call = await vapi.Calls.CreateAsync(new CreateCallRequest
{
PhoneNumberId = "YOUR_PHONE_NUMBER_ID",
Customer = new Customer { Number = "+1234567890" },
AssistantId = "YOUR_ASSISTANT_ID"
});
Console.WriteLine($"Call created: {call.Id}");
```
Install the Go Server SDK:
```bash
go get github.com/VapiAI/server-sdk-go
```
```go
package main
import (
"fmt"
"os"
"github.com/VapiAI/server-sdk-go"
)
func main() {
client := vapi.NewClient(os.Getenv("VAPI_API_KEY"))
// Create an outbound call
call, err := client.Calls.Create(&vapi.CreateCallRequest{
PhoneNumberID: "YOUR_PHONE_NUMBER_ID",
Customer: &vapi.Customer{
Number: "+1234567890",
},
AssistantID: "YOUR_ASSISTANT_ID",
})
if err != nil {
panic(err)
}
fmt.Printf("Call created: %s\n", call.ID)
}
```
### Creating assistants
```typescript
const assistant = await vapi.assistants.create({
name: "Sales Assistant",
firstMessage: "Hi! I'm calling about your interest in our software solutions.",
model: {
provider: "openai",
model: "gpt-4o",
temperature: 0.7,
messages: [{
role: "system",
content: "You are a friendly sales representative. Keep responses under 30 words."
}]
},
voice: {
provider: "11labs",
voiceId: "21m00Tcm4TlvDq8ikWAM"
}
});
```
```python
assistant = vapi.assistants.create(
name="Sales Assistant",
first_message="Hi! I'm calling about your interest in our software solutions.",
model={
"provider": "openai",
"model": "gpt-4o",
"temperature": 0.7,
"messages": [{
"role": "system",
"content": "You are a friendly sales representative. Keep responses under 30 words."
}]
},
voice={
"provider": "11labs",
"voice_id": "21m00Tcm4TlvDq8ikWAM"
}
)
```
```java
Assistant assistant = vapi.assistants().create(CreateAssistantRequest.builder()
.name("Sales Assistant")
.firstMessage("Hi! I'm calling about your interest in our software solutions.")
.model(Model.builder()
.provider("openai")
.model("gpt-4o")
.temperature(0.7)
.messages(List.of(Message.builder()
.role("system")
.content("You are a friendly sales representative. Keep responses under 30 words.")
.build()))
.build())
.voice(Voice.builder()
.provider("11labs")
.voiceId("21m00Tcm4TlvDq8ikWAM")
.build())
.build());
```
```ruby
assistant = vapi.assistants.create(
name: "Sales Assistant",
first_message: "Hi! I'm calling about your interest in our software solutions.",
model: {
provider: "openai",
model: "gpt-4o",
temperature: 0.7,
messages: [{
role: "system",
content: "You are a friendly sales representative. Keep responses under 30 words."
}]
},
voice: {
provider: "11labs",
voice_id: "21m00Tcm4TlvDq8ikWAM"
}
)
```
```csharp
var assistant = await vapi.Assistants.CreateAsync(new CreateAssistantRequest
{
Name = "Sales Assistant",
FirstMessage = "Hi! I'm calling about your interest in our software solutions.",
Model = new Model
{
Provider = "openai",
ModelName = "gpt-4o",
Temperature = 0.7,
Messages = new List
{
new Message
{
Role = "system",
Content = "You are a friendly sales representative. Keep responses under 30 words."
}
}
},
Voice = new Voice
{
Provider = "11labs",
VoiceId = "21m00Tcm4TlvDq8ikWAM"
}
});
```
```go
assistant, err := client.Assistants.Create(&vapi.CreateAssistantRequest{
Name: "Sales Assistant",
FirstMessage: "Hi! I'm calling about your interest in our software solutions.",
Model: &vapi.Model{
Provider: "openai",
Model: "gpt-4o",
Temperature: 0.7,
Messages: []vapi.Message{
{
Role: "system",
Content: "You are a friendly sales representative. Keep responses under 30 words.",
},
},
},
Voice: &vapi.Voice{
Provider: "11labs",
VoiceID: "21m00Tcm4TlvDq8ikWAM",
},
})
```
### Bulk operations
Run automated call campaigns for sales, surveys, or notifications:
```typescript
async function runBulkCallCampaign(assistantId: string, phoneNumberId: string) {
const prospects = [
{ number: "+1234567890", name: "John Smith" },
{ number: "+1234567891", name: "Jane Doe" },
// ... more prospects
];
const calls = [];
for (const prospect of prospects) {
const call = await vapi.calls.create({
assistantId,
phoneNumberId,
customer: prospect,
metadata: { campaign: "Q1_Sales" }
});
calls.push(call);
// Rate limiting
await new Promise(resolve => setTimeout(resolve, 2000));
}
return calls;
}
```
```python
import time
def run_bulk_call_campaign(assistant_id: str, phone_number_id: str):
prospects = [
{"number": "+1234567890", "name": "John Smith"},
{"number": "+1234567891", "name": "Jane Doe"},
# ... more prospects
]
calls = []
for prospect in prospects:
call = vapi.calls.create(
assistant_id=assistant_id,
phone_number_id=phone_number_id,
customer=prospect,
metadata={"campaign": "Q1_Sales"}
)
calls.append(call)
# Rate limiting
time.sleep(2)
return calls
```
```java
public List runBulkCallCampaign(String assistantId, String phoneNumberId) {
List prospects = Arrays.asList(
Customer.builder().number("+1234567890").name("John Smith").build(),
Customer.builder().number("+1234567891").name("Jane Doe").build()
// ... more prospects
);
List calls = new ArrayList<>();
for (Customer prospect : prospects) {
Call call = vapi.calls().create(CreateCallRequest.builder()
.assistantId(assistantId)
.phoneNumberId(phoneNumberId)
.customer(prospect)
.metadata(Map.of("campaign", "Q1_Sales"))
.build());
calls.add(call);
// Rate limiting
Thread.sleep(2000);
}
return calls;
}
```
```ruby
def run_bulk_call_campaign(assistant_id, phone_number_id)
prospects = [
{ number: "+1234567890", name: "John Smith" },
{ number: "+1234567891", name: "Jane Doe" },
# ... more prospects
]
calls = []
prospects.each do |prospect|
call = vapi.calls.create(
assistant_id: assistant_id,
phone_number_id: phone_number_id,
customer: prospect,
metadata: { campaign: "Q1_Sales" }
)
calls << call
# Rate limiting
sleep(2)
end
calls
end
```
```csharp
public async Task> RunBulkCallCampaign(string assistantId, string phoneNumberId)
{
var prospects = new List
{
new Customer { Number = "+1234567890", Name = "John Smith" },
new Customer { Number = "+1234567891", Name = "Jane Doe" },
// ... more prospects
};
var calls = new List();
foreach (var prospect in prospects)
{
var call = await vapi.Calls.CreateAsync(new CreateCallRequest
{
AssistantId = assistantId,
PhoneNumberId = phoneNumberId,
Customer = prospect,
Metadata = new Dictionary { ["campaign"] = "Q1_Sales" }
});
calls.Add(call);
// Rate limiting
await Task.Delay(2000);
}
return calls;
}
```
```go
func runBulkCallCampaign(client *vapi.Client, assistantID, phoneNumberID string) ([]*vapi.Call, error) {
prospects := []*vapi.Customer{
{Number: "+1234567890", Name: "John Smith"},
{Number: "+1234567891", Name: "Jane Doe"},
// ... more prospects
}
var calls []*vapi.Call
for _, prospect := range prospects {
call, err := client.Calls.Create(&vapi.CreateCallRequest{
AssistantID: assistantID,
PhoneNumberID: phoneNumberID,
Customer: prospect,
Metadata: map[string]interface{}{"campaign": "Q1_Sales"},
})
if err != nil {
return nil, err
}
calls = append(calls, call)
// Rate limiting
time.Sleep(2 * time.Second)
}
return calls, nil
}
```
## Webhook integration
Handle real-time events for both client and server applications:
```typescript
import express from 'express';
const app = express();
app.use(express.json());
app.post('/webhook/vapi', async (req, res) => {
const { message } = req.body;
switch (message.type) {
case 'status-update':
console.log(`Call ${message.call.id}: ${message.call.status}`);
break;
case 'transcript':
console.log(`${message.role}: ${message.transcript}`);
break;
case 'function-call':
return handleFunctionCall(message, res);
}
res.status(200).json({ received: true });
});
function handleFunctionCall(message: any, res: express.Response) {
const { functionCall } = message;
switch (functionCall.name) {
case 'lookup_order':
const orderData = { orderId: functionCall.parameters.orderId, status: 'shipped' };
return res.json({ result: orderData });
default:
return res.status(400).json({ error: 'Unknown function' });
}
}
app.listen(3000, () => console.log('Webhook server running on port 3000'));
```
```python
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhook/vapi', methods=['POST'])
def handle_vapi_webhook():
payload = request.get_json()
message = payload.get('message', {})
if message.get('type') == 'status-update':
call = message.get('call', {})
print(f"Call {call.get('id')}: {call.get('status')}")
elif message.get('type') == 'transcript':
print(f"{message.get('role')}: {message.get('transcript')}")
elif message.get('type') == 'function-call':
return handle_function_call(message)
return jsonify({"received": True}), 200
def handle_function_call(message):
function_call = message.get('functionCall', {})
function_name = function_call.get('name')
if function_name == 'lookup_order':
order_data = {
"orderId": function_call.get('parameters', {}).get('orderId'),
"status": "shipped"
}
return jsonify({"result": order_data})
return jsonify({"error": "Unknown function"}), 400
if __name__ == '__main__':
app.run(port=5000)
```
```java
@RestController
@RequestMapping("/webhook")
public class VapiWebhookController {
@PostMapping("/vapi")
public ResponseEntity handleVapiWebhook(@RequestBody Map payload) {
Map message = (Map) payload.get("message");
String type = (String) message.get("type");
switch (type) {
case "status-update":
Map call = (Map) message.get("call");
System.out.println("Call " + call.get("id") + ": " + call.get("status"));
break;
case "transcript":
System.out.println(message.get("role") + ": " + message.get("transcript"));
break;
case "function-call":
return handleFunctionCall(message);
}
return ResponseEntity.ok(Map.of("received", true));
}
private ResponseEntity handleFunctionCall(Map message) {
Map functionCall = (Map) message.get("functionCall");
String functionName = (String) functionCall.get("name");
if ("lookup_order".equals(functionName)) {
Map parameters = (Map) functionCall.get("parameters");
Map orderData = Map.of(
"orderId", parameters.get("orderId"),
"status", "shipped"
);
return ResponseEntity.ok(Map.of("result", orderData));
}
return ResponseEntity.badRequest().body(Map.of("error", "Unknown function"));
}
}
```
```ruby
require 'sinatra'
require 'json'
post '/webhook/vapi' do
payload = JSON.parse(request.body.read)
message = payload['message']
case message['type']
when 'status-update'
call = message['call']
puts "Call #{call['id']}: #{call['status']}"
when 'transcript'
puts "#{message['role']}: #{message['transcript']}"
when 'function-call'
return handle_function_call(message)
end
content_type :json
{ received: true }.to_json
end
def handle_function_call(message)
function_call = message['functionCall']
function_name = function_call['name']
case function_name
when 'lookup_order'
order_data = {
orderId: function_call['parameters']['orderId'],
status: 'shipped'
}
content_type :json
{ result: order_data }.to_json
else
status 400
content_type :json
{ error: 'Unknown function' }.to_json
end
end
```
```csharp
[ApiController]
[Route("webhook")]
public class VapiWebhookController : ControllerBase
{
[HttpPost("vapi")]
public IActionResult HandleVapiWebhook([FromBody] WebhookPayload payload)
{
var message = payload.Message;
switch (message.Type)
{
case "status-update":
Console.WriteLine($"Call {message.Call.Id}: {message.Call.Status}");
break;
case "transcript":
Console.WriteLine($"{message.Role}: {message.Transcript}");
break;
case "function-call":
return HandleFunctionCall(message);
}
return Ok(new { received = true });
}
private IActionResult HandleFunctionCall(WebhookMessage message)
{
var functionCall = message.FunctionCall;
switch (functionCall.Name)
{
case "lookup_order":
var orderData = new
{
orderId = functionCall.Parameters["orderId"],
status = "shipped"
};
return Ok(new { result = orderData });
default:
return BadRequest(new { error = "Unknown function" });
}
}
}
```
```go
package main
import (
"encoding/json"
"fmt"
"net/http"
)
type WebhookPayload struct {
Message WebhookMessage `json:"message"`
}
type WebhookMessage struct {
Type string `json:"type"`
Call *Call `json:"call,omitempty"`
Role string `json:"role,omitempty"`
Transcript string `json:"transcript,omitempty"`
FunctionCall *FunctionCall `json:"functionCall,omitempty"`
}
func handleVapiWebhook(w http.ResponseWriter, r *http.Request) {
var payload WebhookPayload
if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
message := payload.Message
switch message.Type {
case "status-update":
fmt.Printf("Call %s: %s\n", message.Call.ID, message.Call.Status)
case "transcript":
fmt.Printf("%s: %s\n", message.Role, message.Transcript)
case "function-call":
handleFunctionCall(w, message)
return
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]bool{"received": true})
}
func handleFunctionCall(w http.ResponseWriter, message WebhookMessage) {
functionCall := message.FunctionCall
switch functionCall.Name {
case "lookup_order":
orderData := map[string]interface{}{
"orderId": functionCall.Parameters["orderId"],
"status": "shipped",
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{"result": orderData})
default:
http.Error(w, `{"error": "Unknown function"}`, http.StatusBadRequest)
}
}
func main() {
http.HandleFunc("/webhook/vapi", handleVapiWebhook)
fmt.Println("Webhook server running on port 8080")
http.ListenAndServe(":8080", nil)
}
```
## Next steps
Now that you understand both client and server SDK capabilities:
* **Explore use cases:** Check out our [examples section](/assistants/examples/inbound-support) for complete implementations
* **Add tools:** Connect your voice agents to external APIs and databases with [custom tools](/tools/custom-tools)
* **Configure models:** Try different [speech and language models](/assistants/speech-configuration) for better performance
* **Scale with workflows:** Use [Vapi workflows](/workflows/quickstart) for complex multi-step processes
## Resources
**Client SDKs:**
* [Web SDK GitHub](https://github.com/VapiAI/web)
* [React Native SDK GitHub](https://github.com/VapiAI/react-native)
* [Flutter SDK GitHub](https://github.com/VapiAI/flutter)
* [iOS SDK GitHub](https://github.com/VapiAI/ios)
* [Python Client GitHub](https://github.com/VapiAI/python)
**Server SDKs:**
* [TypeScript SDK GitHub](https://github.com/VapiAI/server-sdk-typescript)
* [Python SDK GitHub](https://github.com/VapiAI/server-sdk-python)
* [Java SDK GitHub](https://github.com/VapiAI/server-sdk-java)
* [Ruby SDK GitHub](https://github.com/VapiAI/server-sdk-ruby)
* [C# SDK GitHub](https://github.com/VapiAI/server-sdk-csharp)
* [Go SDK GitHub](https://github.com/VapiAI/server-sdk-go)
**Documentation:**
* [API Reference](/api-reference)
* [Discord Community](https://discord.gg/pUFNcf2WmH)
# Guides
> Explore real-world, cloneable examples to build voice agents with Vapi. Now including new Workflow-based guides!
Built with Workflows
Build an appointment scheduling assistant that can schedule appointments for a barbershop
Built with Workflows
Build a medical triage and scheduling assistant that can triage patients and schedule appointments for a clinic
Built with Workflows
Build an ecommerce order management assistant that can track orders and process returns
Built with Workflows
Build a call routing workflow that dynamically routes tenant calls based on verification and inquiry type
Built with Workflows
Create an outbound sales agent that can schedule appointments automatically
Built with Workflows
Build a structured multilingual support workflow with language selection and dedicated conversation paths
Built with Assistants
Build a dynamic agent with automatic language detection and real-time language switching
Built with Assistants
Build an intelligent support escalation system with dynamic routing based on customer tier and issue complexity
Built with Assistants
Build a docs agent that can answer questions about your documentation
Built with Assistants
Build a technical support assistant that remembers where you left off between calls
Built with Assistants
Easily integrate the Vapi Voice Widget into your website for enhanced user interaction
Developer Tool
Build voice AI agents faster with the Vapi CLI - project integration, local testing, and IDE enhancement
# Vapi CLI
> Command-line interface for building voice AI applications faster
## Overview
The Vapi CLI is the official command-line interface that brings world-class developer experience to your terminal and IDE. Build, test, and deploy voice AI applications without leaving your development environment.
**In this guide, you'll learn to:**
* Install and authenticate with the Vapi CLI
* Initialize Vapi in existing projects
* Manage assistants, phone numbers, and workflows from your terminal
* Forward webhooks to your local development server
* Turn your IDE into a Vapi expert with MCP integration
## Installation
Install the Vapi CLI in seconds with our automated scripts:
```bash
curl -sSL https://vapi.ai/install.sh | bash
```
```powershell
iex ((New-Object System.Net.WebClient).DownloadString('https://vapi.ai/install.ps1'))
```
```bash
docker run -it ghcr.io/vapiai/cli:latest --help
```
## Quick start
Connect your Vapi account:
```bash
vapi login
```
This opens your browser for secure OAuth authentication.
Add Vapi to an existing project:
```bash
vapi init
```
The CLI auto-detects your tech stack and sets up everything you need.
Build a voice assistant:
```bash
vapi assistant create
```
Follow the interactive prompts to configure your assistant.
## Key features
### 🚀 Project integration
Drop Vapi into any existing codebase with intelligent auto-detection:
```bash
vapi init
# Detected: Next.js application
# ✓ Installed @vapi-ai/web SDK
# ✓ Generated components/VapiButton.tsx
# ✓ Created pages/api/vapi/webhook.ts
# ✓ Added environment template
```
Supports React, Vue, Next.js, Python, Go, Flutter, React Native, and dozens more frameworks.
### 🤖 MCP integration
Turn your IDE into a Vapi expert with Model Context Protocol:
```bash
vapi mcp setup
```
Your IDE's AI assistant (Cursor, Windsurf, VSCode) gains complete, accurate knowledge of Vapi's APIs and best practices. No more hallucinated code or outdated examples.
### 🔗 Local webhook testing
Forward webhooks to your local server for debugging:
```bash
# Terminal 1: Create tunnel (e.g., with ngrok)
ngrok http 4242
# Terminal 2: Forward webhooks
vapi listen --forward-to localhost:3000/webhook
```
**Important:** `vapi listen` is a local forwarder only - it does NOT provide a public URL. You need a separate tunneling service (like ngrok) to expose the CLI's port to the internet. Update your webhook URLs in Vapi to use the tunnel's public URL.
### 🔐 Multi-account management
Switch between organizations and environments seamlessly:
```bash
# List all authenticated accounts
vapi auth status
# Switch between accounts
vapi auth switch production
# Add another account
vapi auth login
```
### 📱 Complete feature parity
Everything you can do in the dashboard, now in your terminal:
* **Assistants**: Create, update, list, and delete voice assistants
* **Phone numbers**: Purchase, configure, and manage phone numbers
* **Calls**: Make outbound calls and view call history
* **Workflows**: Manage conversation flows (visual editing in dashboard)
* **Campaigns**: Create and manage AI phone campaigns at scale
* **Tools**: Configure custom functions and integrations
* **Webhooks**: Set up and test event delivery
* **Logs**: View system logs, call logs, and debug issues
## Common commands
```bash
# List all assistants
vapi assistant list
# Create a new assistant
vapi assistant create
# Get assistant details
vapi assistant get
# Update an assistant
vapi assistant update
# Delete an assistant
vapi assistant delete
```
```bash
# List your phone numbers
vapi phone list
# Purchase a new number
vapi phone create
# Update number configuration
vapi phone update
# Release a number
vapi phone delete
```
```bash
# List recent calls
vapi call list
# Make an outbound call
vapi call create
# Get call details
vapi call get
# End an active call
vapi call end
```
```bash
# View system logs
vapi logs list
# View call-specific logs
vapi logs calls
# View error logs
vapi logs errors
# View webhook logs
vapi logs webhooks
```
## Configuration
The CLI stores configuration in `~/.vapi-cli.yaml`. You can also use environment variables:
```bash
# Set API key via environment
export VAPI_API_KEY=your-api-key
# View current configuration
vapi config get
# Update configuration
vapi config set
# Manage analytics preferences
vapi config analytics disable
```
## Auto-updates
The CLI automatically checks for updates and notifies you when new versions are available:
```bash
# Check for updates manually
vapi update check
# Update to latest version
vapi update
```
## Next steps
Now that you have the Vapi CLI installed:
* **[Initialize a project](/cli/init):** Add Vapi to your existing codebase
* **[Set up MCP](/cli/mcp):** Enhance your IDE with Vapi intelligence
* **[Test webhooks locally](/cli/webhook):** Debug webhooks with tunneling services
* **[Manage authentication](/cli/auth):** Work with multiple accounts
***
**Resources:**
* [GitHub Repository](https://github.com/VapiAI/cli)
* [Report Issues](https://github.com/VapiAI/cli/issues)
* [Discord Community](https://discord.gg/vapi)
# Transient vs permanent configurations
> Learn to choose between inline and stored assistant configurations
## Overview
Choose between **transient** (inline) and **permanent** (stored) configurations to optimize your Vapi implementation for flexibility, reusability, and management needs.
**In this guide, you'll learn to:**
* Understand when to use transient vs permanent configurations
* Implement both approaches with practical examples
* Apply best practices for each configuration type
## Key differences
| Aspect | Transient | Permanent |
| -------------------- | ------------------------------- | ------------------------------------ |
| **Definition** | Complete JSON in API request | ID reference to stored configuration |
| **Storage** | Exists only during API call | Stored on Vapi servers |
| **Reusability** | Defined per request | Reusable across multiple calls |
| **Dashboard access** | Not visible | Visible and manageable |
| **Best for** | Dynamic, personalized scenarios | Shared, reusable setups |
## Transient configurations
Use **transient configurations** when you need dynamic, call-specific behavior without pre-creating stored configurations.
### When to use transient
**Best for:** Customer-specific data Embed user information directly in
system messages
**Best for:** Configuration experiments Test different setups without
permanent storage
**Best for:** Short-term promotions Event-specific assistants that don't
need persistence
**Best for:** Rapid prototyping Iterate quickly without managing stored
configs
### Customer service with pre-filled data
```json title="Transient assistant"
{
"assistant": {
"name": "Customer Service Agent",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a customer service representative for Acme Corp. The customer's name is John Smith and their account status is premium. Provide personalized assistance based on their business account history."
}
],
"temperature": 0.7
},
"voice": {
"provider": "11labs",
"voiceId": "N2lVS1w4EtoT3dr4eOWO"
},
"firstMessage": "Hello John, I see you're calling about your business account. How can I help you today?"
}
}
```
```bash title="Create call with transient assistant"
curl -X POST "https://api.vapi.ai/call" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "your-phone-number-id",
"customer": {
"number": "+1234567890"
},
"assistant": {
"name": "Personalized Sales Agent",
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are calling John about their interest in Enterprise Solution. Their budget is $5000."
}
]
},
"voice": {
"provider": "11labs",
"voiceId": "N2lVS1w4EtoT3dr4eOWO"
},
"firstMessage": "Hi John, this is Sarah from Acme Corp calling about Enterprise Solution. Do you have a moment to chat?"
}
}'
```
### A/B testing scenario
```json title="Variant A - Enthusiastic approach"
{
"assistant": {
"name": "A/B Test Assistant - Variant A",
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are an enthusiastic sales representative. Use upbeat language and emphasize benefits."
}
],
"temperature": 0.9
},
"voice": {
"provider": "11labs",
"voiceId": "energetic-voice-id"
},
"firstMessage": "Hey there! Exciting news - I'd love to tell you about our amazing new features!",
"analysisPlan": {
"summaryPrompt": "Rate the customer's engagement level and interest in the product on a scale of 1-10.",
"structuredDataPlan": {
"enabled": true,
"schema": {
"type": "object",
"properties": {
"engagement_score": { "type": "number" },
"interest_level": {
"type": "string",
"enum": ["high", "medium", "low"]
},
"conversion_likelihood": { "type": "number" }
}
}
}
}
}
}
```
```json title="Variant B - Professional approach"
{
"assistant": {
"name": "A/B Test Assistant - Variant B",
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are a professional sales consultant. Use formal language and focus on business value."
}
],
"temperature": 0.3
},
"voice": {
"provider": "11labs",
"voiceId": "professional-voice-id"
},
"firstMessage": "Good afternoon. I'm calling to discuss how our enterprise solutions can benefit your organization.",
"analysisPlan": {
"summaryPrompt": "Rate the customer's engagement level and interest in the product on a scale of 1-10.",
"structuredDataPlan": {
"enabled": true,
"schema": {
"type": "object",
"properties": {
"engagement_score": { "type": "number" },
"interest_level": {
"type": "string",
"enum": ["high", "medium", "low"]
},
"conversion_likelihood": { "type": "number" }
}
}
}
}
}
}
```
### Transient tools
Create custom tools for specific integrations or workflows:
```json title="Customer-specific function tool"
{
"tools": [
{
"type": "function",
"name": "check_inventory",
"description": "Check product inventory for the customer's specific region",
"parameters": {
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "The product ID to check"
},
"region": {
"type": "string",
"description": "Customer's region code"
}
},
"required": ["productId", "region"]
},
"server": {
"url": "https://api.customer-integration.com/inventory",
"secret": "customer-webhook-secret",
"timeoutSeconds": 30
}
}
]
}
```
```json title="Context-specific transfer tool"
{
"tools": [
{
"type": "transferCall",
"destinations": [
{
"type": "assistant",
"assistantName": "technical-support",
"description": "Transfer to technical support specialist",
"message": "Let me connect you with our technical team who can better assist with your technical question."
},
{
"type": "number",
"number": "+1234567890",
"description": "Emergency escalation line",
"message": "Transferring you to our priority support team."
}
]
}
]
}
```
**Transient limitations:** Configurations exist only during the API call and
cannot be managed through the dashboard or reused across calls.
## Permanent configurations
Use **permanent configurations** for reusable setups that multiple teams can access and manage through the dashboard.
### When to use permanent
**Best for:** Team collaboration Assistants used across multiple departments
**Best for:** Non-technical users Visual configuration management
**Best for:** Standard workflows Consistent configurations across calls
**Best for:** Change tracking Maintain configuration history
### Creating permanent configurations
Store your assistant configuration on Vapi servers
Use the returned UUID to reference the assistant
Use the ID instead of inline configuration
```bash title="Create permanent assistant"
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "General Support Assistant",
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are a helpful customer service representative for Acme Corp. Provide accurate information about our products and services."
}
]
},
"voice": {
"provider": "11labs",
"voiceId": "N2lVS1w4EtoT3dr4eOWO"
},
"firstMessage": "Hello! Thank you for calling Acme Corp. How can I assist you today?"
}'
```
```bash title="Create permanent tool"
curl -X POST "https://api.vapi.ai/tool" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"name": "update_crm_contact",
"description": "Update contact information in the CRM system",
"parameters": {
"type": "object",
"properties": {
"contactId": {
"type": "string",
"description": "CRM contact ID"
},
"updates": {
"type": "object",
"description": "Fields to update"
}
},
"required": ["contactId", "updates"]
},
"server": {
"url": "https://api.yourcrm.com/contacts/update",
"secret": "your-webhook-secret"
}
}'
```
```bash title="Use permanent configurations"
curl -X POST "https://api.vapi.ai/call" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "your-phone-number-id",
"customer": {
"number": "+1234567890"
},
"assistantId": "your-assistant-id",
"assistantOverrides": {
"toolIds": ["tool-id-1", "tool-id-2"],
"variableValues": {
"customerName": "John Smith",
"accountId": "ACC123456"
}
}
}'
```
## Mixed configurations
Combine transient and permanent configurations for maximum flexibility:
```json title="Squad with mixed configurations"
{
"squad": [
{
"assistantId": "permanent-receptionist-assistant-id",
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "technical-support"
}
]
},
{
"assistant": {
"name": "technical-support",
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are a technical support specialist for Enterprise Software. The customer has high priority issue."
}
]
},
"voice": {
"provider": "11labs",
"voiceId": "technical-voice-id"
}
},
"assistantDestinations": []
}
]
}
```
```json title="Server message with transient assistant"
{
"assistant": {
"name": "Dynamic Inbound Handler",
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "The caller is from West Coast calling during business hours. Adjust your approach accordingly."
}
]
},
"voice": {
"provider": "11labs",
"voiceId": "appropriate-voice-for-region"
},
"firstMessage": "Hello! I see you're calling from West Coast. How can I help you today?"
}
}
```
## Best practices
**Use transient when:**
* Customer data needs to be embedded in system messages
* Testing different configurations temporarily
* Creating user-specific personalizations
* Rapid prototyping and development
**Use permanent when:**
* Multiple teams need access to the same configuration
* Non-technical users manage configurations via dashboard
* Consistency across multiple API calls is required
* Version control and change tracking are important
* **Transient:** Slightly larger request payloads but no additional API calls
* **Permanent:** Smaller request payloads but requires initial creation calls
* **Mixed:** Optimize by using permanent for stable configs, transient for dynamic parts
* **Transient:** Full configuration visible in API requests - avoid sensitive data
* **Permanent:** Stored securely on Vapi servers with proper access controls
* **Recommendation:** Use permanent configurations for sensitive integrations
## Limitations
* **No persistence:** Cannot retrieve or reuse after API call - **No
dashboard access:** Not visible in Vapi dashboard - **No version control:**
Cannot track configuration changes - **Request size:** Larger payloads may
impact performance
* **Setup overhead:** Requires separate creation API calls - **ID
management:** Need to track and manage configuration UUIDs - **Update
complexity:** Changes require additional API calls
## Next steps
Now that you understand transient vs permanent configurations:
* **[Assistant creation guide](/docs/assistants):** Learn to build and customize assistants
* **[Tool integration](/docs/tools):** Connect external services and functions
* **[Squad configuration](/docs/squads):** Set up multi-assistant workflows
* **[API reference](/fern/api-reference):** Explore all configuration options
# Variables
> Personalize assistant messages with dynamic and default variables
## Overview
Use dynamic variables in the system prompt or any message in the dashboard with double curly braces (e.g., `{{name}}`).
To set values, make a phone call request through the API and set `assistantOverrides`. You cannot set variable values directly in the dashboard.
For example, set the assistant's first message to "Hello, `{{name}}`!" and assign `name` to `John` by passing `assistantOverrides` with `variableValues`:
```json
{
"variableValues": {
"name": "John"
}
}
```
## Using dynamic variables in a phone call
Create a JSON payload with these key-value pairs:
* **`assistantId`**: Replace `"your-assistant-id"` with your assistant's actual ID.
* **`assistantOverride`**: Customize your assistant's behavior.
* **`variableValues`**: Include dynamic variables in the format `{ "variableName": "variableValue" }`. Example: `{ "name": "John" }`.
* **`customer`**: Represent the call recipient.
* **`number`**: Replace `"+1xxxxxxxxxx"` with the recipient's phone number (E.164 format).
* **`phoneNumberId`**: Replace `"your-phone-id"` with your registered phone number's ID. Find it on the [Phone number](https://dashboard.vapi.ai/phone-numbers) page.
Send the JSON payload to the `/call/phone` endpoint using your preferred method (e.g., HTTP POST request).
```json
{
"assistantId": "your-assistant-id",
"assistantOverrides": {
"variableValues": {
"name": "John"
}
},
"customer": {
"number": "+1xxxxxxxxxx"
},
"phoneNumberId": "your-phone-id"
}
```
Ensure `{{variableName}}` is included in all prompts where needed.
## Default Variables
These variables are automatically filled based on the current (UTC) time, so you don't need to set them manually in `variableValues`:
| Variable | Description | Example |
| --------------------- | --------------------------- | -------------------- |
| `{{now}}` | Current date and time (UTC) | Jan 1, 2024 12:00 PM |
| `{{date}}` | Current date (UTC) | Jan 1, 2024 |
| `{{time}}` | Current time (UTC) | 12:00 PM |
| `{{month}}` | Current month (UTC) | January |
| `{{day}}` | Current day of month (UTC) | 1 |
| `{{year}}` | Current year (UTC) | 2024 |
| `{{customer.number}}` | Customer's phone number | +1xxxxxxxxxx |
| `{{customer.X}}` | Any other customer property | |
## Advanced date and time usage
You can use advanced date and time formatting in any prompt or message that supports dynamic variables in the dashboard or API. We use [LiquidJS](https://liquidjs.com/) for formatting - see their docs for details.
Format a date or time using the LiquidJS `date` filter:
```liquid
{{"now" | date: "%A, %B %d, %Y, %I:%M %p", "America/Los_Angeles"}}
```
Outputs: `Monday, January 01, 2024, 03:45 PM`
**Examples:**
* 24-hour time:
```liquid
{{"now" | date: "%H:%M", "Europe/London"}}
```
→ `17:30`
* Day of week:
```liquid
{{"now" | date: "%A"}}
```
→ `Tuesday`
* With customer number:
```liquid
Hello, your number is {{customer.number}} and the time is {{"now" | date: "%I:%M %p", "America/New_York"}}
```
**Common formats:**
| Format String | Output | Description |
| ------------- | ------------ | ----------------- |
| `%Y-%m-%d` | 2024-01-01 | Year-Month-Day |
| `%I:%M %p` | 03:45 PM | Hour:Minute AM/PM |
| `%H:%M` | 15:45 | 24-hour time |
| `%A` | Monday | Day of week |
| `%b %d, %Y` | Jan 01, 2024 | Abbrev. Month Day |
```
## Using dynamic variables in the dashboard
To use dynamic variables in the dashboard, include them in your prompts or messages using double curly braces. For example:
```
Hello, \{\{name}}!
```
When you start a call, you must provide a value for each variable (like `name`) in the call configuration or via the API/SDK.
Always use double curly braces (`{{variableName}}`) to reference dynamic variables in your prompts and messages.
```
# Multilingual support
> Configure multilingual voice AI agents with automatic language detection, cross-language conversation, and localized voices
## Overview
Configure your voice assistant to communicate in multiple languages with automatic language detection, native voice quality, and cultural context awareness.
**In this guide, you'll learn to:**
* Set up automatic language detection for speech recognition
* Configure multilingual voice synthesis
* Design language-aware system prompts
* Test and optimize multilingual performance
**Multilingual Support:** Multiple providers support automatic language detection. **Deepgram** (Nova 2, Nova 3 with "Multi" setting) and **Google STT** (with "Multilingual" setting) both offer automatic language detection for seamless multilingual conversations.
## Configure automatic language detection
Set up your transcriber to automatically detect and process multiple languages.
1. Navigate to **Assistants** in your [Vapi Dashboard](https://dashboard.vapi.ai/)
2. Create a new assistant or edit an existing one
3. In the **Transcriber** section:
* **Provider**: Select `Deepgram` (recommended) or `Google`
* **Model**: For Deepgram, choose `Nova 2` or `Nova 3`; for Google, choose `Latest`
* **Language**: Set to `Multi` (Deepgram) or `Multilingual` (Google)
4. **Other providers**: Single language only, no automatic detection
5. Click **Save** to apply the configuration
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Recommended: Deepgram for multilingual support
const assistant = await vapi.assistants.create({
name: "Multilingual Assistant",
transcriber: {
provider: "deepgram",
model: "nova-2", // or "nova-3"
language: "multi"
}
});
// Alternative: Google for multilingual support
const googleMultilingual = {
provider: "google",
model: "latest",
language: "multilingual"
};
```
```python
from vapi import Vapi
import os
client = Vapi(token=os.getenv("VAPI_API_KEY"))
# Recommended: Deepgram for multilingual support
assistant = client.assistants.create(
name="Multilingual Assistant",
transcriber={
"provider": "deepgram",
"model": "nova-2", # or "nova-3"
"language": "multi"
}
)
# Alternative: Google for multilingual support
google_multilingual = {
"provider": "google",
"model": "latest",
"language": "multilingual"
}
```
```bash
# Recommended: Deepgram for multilingual support
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Multilingual Assistant",
"transcriber": {
"provider": "deepgram",
"model": "nova-2",
"language": "multi"
}
}'
# Alternative: Google for multilingual support
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transcriber": {
"provider": "google",
"model": "latest",
"language": "multilingual"
}
}'
```
**Provider Performance:** **Deepgram** offers the best balance of speed and multilingual accuracy. **Google** provides broader language support but may be slower. Both providers support automatic language detection within conversations.
## Set up multilingual voices
Configure your assistant to use appropriate voices for each detected language.
1. In the **Voice** section of your assistant:
* **Provider**: Select `Azure` (best multilingual coverage)
* **Voice**: Choose `multilingual-auto` for automatic voice selection
2. **Alternative**: Configure specific voices for each language:
* Select a primary voice (e.g., `en-US-AriaNeural`)
* Click **Add Fallback Voices**
* Add voices for other languages:
* Spanish: `es-ES-ElviraNeural`
* French: `fr-FR-DeniseNeural`
* German: `de-DE-KatjaNeural`
3. Click **Save** to apply the voice configuration
```typescript
// Option 1: Automatic voice selection (recommended)
const voice = {
provider: "azure",
voiceId: "multilingual-auto"
};
// Option 2: Specific voices with fallbacks
const voiceWithFallbacks = {
provider: "azure",
voiceId: "en-US-AriaNeural", // Primary voice
fallbackPlan: {
voices: [
{ provider: "azure", voiceId: "es-ES-ElviraNeural" },
{ provider: "azure", voiceId: "fr-FR-DeniseNeural" },
{ provider: "azure", voiceId: "de-DE-KatjaNeural" }
]
}
};
await vapi.assistants.update(assistantId, { voice });
```
```python
# Option 1: Automatic voice selection (recommended)
voice = {
"provider": "azure",
"voiceId": "multilingual-auto"
}
# Option 2: Specific voices with fallbacks
voice_with_fallbacks = {
"provider": "azure",
"voiceId": "en-US-AriaNeural", # Primary voice
"fallbackPlan": {
"voices": [
{"provider": "azure", "voiceId": "es-ES-ElviraNeural"},
{"provider": "azure", "voiceId": "fr-FR-DeniseNeural"},
{"provider": "azure", "voiceId": "de-DE-KatjaNeural"}
]
}
}
client.assistants.update(assistant_id, voice=voice)
```
```bash
curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"voice": {
"provider": "azure",
"voiceId": "multilingual-auto"
}
}'
```
**Voice Provider Support:** Unlike transcription, all major voice providers (Azure, ElevenLabs, OpenAI, etc.) support multiple languages. Azure offers the most comprehensive coverage with 400+ voices across 140+ languages.
## Configure language-aware prompts
Create system prompts that explicitly list supported languages and handle multiple languages gracefully.
1. In the **Model** section, update your system prompt to explicitly list supported languages:
```
You are a helpful assistant that can communicate in English, Spanish, and French.
Language Instructions:
- You can speak and understand: English, Spanish, and French
- Automatically detect and respond in the user's language
- Switch languages seamlessly when the user changes languages
- Maintain consistent personality across all languages
- Use culturally appropriate greetings and formality levels
If a user speaks a language other than English, Spanish, or French, politely explain that you only support these three languages and ask them to continue in one of them.
```
2. Click **Save** to apply the prompt changes
```typescript
const systemPrompt = `You are a helpful assistant that can communicate in English, Spanish, and French.
Language Instructions:
- You can speak and understand: English, Spanish, and French
- Automatically detect and respond in the user's language
- Switch languages seamlessly when the user changes languages
- Maintain consistent personality across all languages
- Use culturally appropriate greetings and formality levels
If a user speaks a language other than English, Spanish, or French, politely explain that you only support these three languages and ask them to continue in one of them.`;
const model = {
provider: "openai",
model: "gpt-4",
messages: [
{
role: "system",
content: systemPrompt
}
]
};
await vapi.assistants.update(assistantId, { model });
```
```python
system_prompt = """You are a helpful assistant that can communicate in English, Spanish, and French.
Language Instructions:
- You can speak and understand: English, Spanish, and French
- Automatically detect and respond in the user's language
- Switch languages seamlessly when the user changes languages
- Maintain consistent personality across all languages
- Use culturally appropriate greetings and formality levels
If a user speaks a language other than English, Spanish, or French, politely explain that you only support these three languages and ask them to continue in one of them."""
model = {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": system_prompt
}
]
}
client.assistants.update(assistant_id, model=model)
```
```bash
curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant that can communicate in English, Spanish, and French..."
}
]
}
}'
```
**Critical for Multilingual Success:** You must explicitly list the supported languages in your system prompt. Assistants struggle to understand they can speak multiple languages without this explicit instruction.
## Add multilingual greetings
Configure greeting messages that work across multiple languages.
1. In the **First Message** field, enter a multilingual greeting:
```
Hello! I can assist you in English, Spanish, or French. How can I help you today?
```
2. **Optional**: For more personalized greetings, use the **Advanced Message Configuration**:
* Enable **Language-Specific Messages**
* Add greetings for each target language
3. Click **Save** to apply the greeting
```typescript
// Simple multilingual greeting
const firstMessage = "Hello! I can assist you in English, Spanish, or French. How can I help you today?";
// Language-specific greetings (advanced)
const multilingualGreeting = {
contents: [
{
type: "text",
text: "Hello! How can I help you today?",
language: "en"
},
{
type: "text",
text: "¡Hola! ¿Cómo puedo ayudarte hoy?",
language: "es"
},
{
type: "text",
text: "Bonjour! Comment puis-je vous aider?",
language: "fr"
}
]
};
await vapi.assistants.update(assistantId, { firstMessage });
```
```python
# Simple multilingual greeting
first_message = "Hello! I can assist you in English, Spanish, or French. How can I help you today?"
# Language-specific greetings (advanced)
multilingual_greeting = {
"contents": [
{
"type": "text",
"text": "Hello! How can I help you today?",
"language": "en"
},
{
"type": "text",
"text": "¡Hola! ¿Cómo puedo ayudarte hoy?",
"language": "es"
},
{
"type": "text",
"text": "Bonjour! Comment puis-je vous aider?",
"language": "fr"
}
]
}
client.assistants.update(assistant_id, first_message=first_message)
```
```bash
curl -X PATCH "https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstMessage": "Hello! I can assist you in English, Spanish, or French. How can I help you today?"
}'
```
## Test your multilingual assistant
Validate your configuration with different languages and scenarios.
1. Use the **Test Assistant** feature in your dashboard
2. Test these scenarios:
* Start conversations in different languages
* Switch languages mid-conversation
* Use mixed-language input
3. Monitor the **Call Analytics** for:
* Language detection accuracy
* Voice quality consistency
* Response appropriateness
4. Adjust configuration based on test results
```typescript
// Create test call
const testCall = await vapi.calls.create({
assistantId: "your-multilingual-assistant-id",
customer: {
number: "+1234567890"
}
});
// Monitor call events
vapi.on('call-end', (event) => {
console.log('Language detection results:', event.transcript);
console.log('Call summary:', event.summary);
});
```
```python
# Create test call
test_call = client.calls.create(
assistant_id="your-multilingual-assistant-id",
customer={
"number": "+1234567890"
}
)
# Retrieve call details for analysis
call_details = client.calls.get(test_call.id)
print(f"Language detection: {call_details.transcript}")
```
```bash
# Create test call
curl -X POST "https://api.vapi.ai/call" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-multilingual-assistant-id",
"customer": {
"number": "+1234567890"
}
}'
```
## Provider capabilities (Accurate as of testing)
### Speech Recognition (Transcription)
| Provider | Multilingual Support | Languages | Notes |
| ------------------ | --------------------- | --------- | ------------------------------------------------------------ |
| **Deepgram** | ✅ Full auto-detection | 100+ | **Recommended**: Nova 2/Nova 3 with "Multi" language setting |
| **Google STT** | ✅ Full auto-detection | 125+ | Latest models with "Multilingual" language setting |
| **Assembly AI** | ❌ English only | English | No multilingual support |
| **Azure STT** | ❌ Single language | 100+ | Many languages, but no auto-detection |
| **OpenAI Whisper** | ❌ Single language | 90+ | Many languages, but no auto-detection |
| **Gladia** | ❌ Single language | 80+ | Many languages, but no auto-detection |
| **Speechmatics** | ❌ Single language | 50+ | Many languages, but no auto-detection |
| **Talkscriber** | ❌ Single language | 40+ | Many languages, but no auto-detection |
### Voice Synthesis (Text-to-Speech)
| Provider | Languages | Multilingual Voice Selection | Best For |
| -------------- | --------- | ---------------------------- | ----------------------------------- |
| **Azure** | 140+ | ✅ Automatic | Maximum language coverage |
| **ElevenLabs** | 30+ | ✅ Automatic | Premium voice quality |
| **OpenAI TTS** | 50+ | ✅ Automatic | Consistent quality across languages |
| **PlayHT** | 80+ | ✅ Automatic | Cost-effective scaling |
## Common challenges and solutions
**Solutions:**
* Use Deepgram (Nova 2/Nova 3 with "Multi") or Google STT (with "Multilingual")
* Ensure high-quality audio input for better detection accuracy
* Test with native speakers of target languages
* Consider provider-specific language combinations for optimal results
**Solutions:**
* **Explicitly list all supported languages** in your system prompt
* Include language capabilities in the assistant's instructions
* Test the prompt with multilingual conversations
* Avoid generic "multilingual" statements without specifics
**Solutions:**
* Use Deepgram Nova 2/Nova 3 for optimal speed and multilingual support
* For Google STT, use latest models for better performance
* Consider the speed vs accuracy tradeoff for your use case
* Optimize audio quality and format to improve processing speed
**Solutions:**
* Test different voice providers for each language
* Use Azure for maximum language coverage
* Configure fallback voices as backup options
* Consider premium providers for key languages
## Next steps
Now that you have multilingual support configured:
* **[Build a complete multilingual agent](../assistants/examples/multilingual-agent):** Follow our step-by-step implementation guide
* **[Custom voices](custom-voices/custom-voice):** Set up region-specific custom voices
* **[System prompting](../prompting-guide):** Design effective multilingual prompts
* **[Call analysis](../call-analysis):** Monitor language performance and usage
# Personalization with user information
> Add customer-specific information to your voice assistant conversations
## Overview
Personalization lets you include customer-specific information in your voice assistant conversations. When a customer calls, your server can provide data about that customer, which is then used to tailor the conversation in real time.
This approach is ideal for use cases like customer support, account management, or any scenario where the assistant should reference details unique to the caller.
## How Personalization Works
When a call comes in, Vapi sends a request to your server instead of using a fixed assistant configuration.
Your server receives the request, identifies the caller (for example, by phone number), and fetches relevant customer data from your database or CRM.
Your server responds to Vapi with either:
* An existing assistant ID and a set of dynamic variables to personalize the conversation, or
* A complete assistant configuration, with customer data embedded directly in the prompts or instructions.
Vapi uses the personalized assistant configuration or variables to guide the conversation, referencing the customer's information as needed.
## Prerequisites
* A Vapi phone number
* A created Vapi Assistant
* A server endpoint to receive Vapi's requests
## Implementation
Use variable placeholders in your assistant's instructions or messages with the `{{variable_name}}` syntax.
Example:\
`"Hello {{customerName}}! I see you've been a {{accountType}} customer since {{joinDate}}."`
Update your phone number so that Vapi sends incoming call events to your server, rather than using a static assistant.
```json
PATCH /phone-number/{id}
{
"assistantId": null,
"squadId": null,
"server": {
"url": "https://your-server.com/api/assistant-selector"
}
}
```
Your server must respond within 7.5 seconds, or the call will fail.
Your server should handle POST requests from Vapi and return either:
**Option 1: Use an Existing Assistant with Dynamic Variables**
```javascript
app.post("/api/assistant-selector", async (req, res) => {
if (req.body.message?.type === "assistant-request") {
const phoneNumber = req.body.call.from.phoneNumber;
const customer = await crmAPI.getCustomerByPhone(phoneNumber);
res.json({
assistantId: "asst_customersupport",
assistantOverrides: {
variableValues: {
customerName: customer.name,
accountType: customer.tier,
joinDate: customer.createdAt
}
}
});
}
});
```
**Option 2: Return a Complete Assistant Configuration**
```javascript
app.post("/api/assistant-selector", async (req, res) => {
if (req.body.message?.type === "assistant-request") {
const phoneNumber = req.body.call.from.phoneNumber;
const customer = await crmAPI.getCustomerByPhone(phoneNumber);
res.json({
assistant: {
name: "Dynamic Customer Support Assistant",
model: {
provider: "openai",
model: "gpt-4o",
messages: [{
role: "system",
content: `You are helping ${customer.name}, a ${customer.tier} member since ${customer.createdAt}.`
}]
},
voice: {
provider: "11labs",
voiceId: "shimmer"
}
}
});
}
});
```
## Error Handling
If your server encounters an error or cannot find the customer, return a response like this to end the call with a spoken message:
```json
{
"error": "Unable to find customer record. Please try again later."
}
```
## Common Issues
* Use the exact `{{variable_name}}` syntax for variables in your assistant configuration.
* Your server must respond within 7.5 seconds.
* Implement fallbacks for missing or incomplete customer data.
* Ensure your endpoint is highly available to avoid missed calls.
# Voice formatting plan
> Format LLM output for natural-sounding speech
## Overview
Voice formatting automatically transforms raw text from your language model (LLM) into a format that sounds natural when spoken by a text-to-speech (TTS) provider. This process—called **Voice Input Formatted**—is enabled by default for all assistants.
Formatting helps with things like:
* Expanding numbers and currency (e.g., `$42.50` → "forty two dollars and fifty cents")
* Expanding abbreviations (e.g., `ST` → "STREET")
* Spacing out phone numbers (e.g., `123-456-7890` → "1 2 3 4 5 6 7 8 9 0")
You can turn off formatting if you want the TTS to read the raw LLM output.
## How voice input formatting works
When enabled, the formatter runs a series of transformations on your text, each handled by a specific function. Here's the order and what each function does:
| **Step** | **Function Name** | **Description** | **Before** | **After** | **Default** | **Precedence** |
| :------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | :------------------------------------ | :------------------------------------------------------------------------ | :---------- | :------------- |
| 1 | `removeAngleBracketContent` | Removes anything within `<...>`, except for ``, ``, or double angle brackets `<< >>`. | `Hello world` | `Hello world` | ✅ | - |
| 2 | `removeMarkdownSymbols` | Removes markdown symbols like `_`, `` ` ``, and `~`. Asterisks (`*`) are preserved in this step. | `**Wanted** to say *hi*` | `**Wanted** to say *hi*` | ✅ | 0 |
| 3 | `removePhrasesInAsterisks` | Removes text surrounded by single or double asterisks. | `**Wanted** to say *hi*` | ` to say` | ❌ | 0 |
| 4 | `replaceNewLinesWithPeriods` | Converts new lines (`\n`) to periods for smoother speech. | `Hello world\n to say\nWe have NASA` | `Hello world . to say . We have NASA` | ✅ | 0 |
| 5 | `replaceColonsWithPeriods` | Replaces `:` with `.` for better phrasing. | `price: $42.50` | `price. $42.50` | ✅ | 0 |
| 6 | `formatAcronyms` | Converts known acronyms to lowercase (e.g., NASA → nasa) or spaces out unknown all-caps words unless they contain vowels. | `NASA and .NET` | `nasa and .net` | ✅ | 0 |
| 7 | `formatDollarAmounts` | Converts currency amounts to spoken words. | `$42.50` | `forty two dollars and fifty cents` | ✅ | 0 |
| 8 | `formatEmails` | Replaces `@` with "at" and `.` with "dot" in emails. | `JOHN.DOE@example.COM` | `JOHN dot DOE at example dot COM` | ✅ | 0 |
| 9 | `formatDates` | Converts date strings into spoken date format. | `2023 05 10` | `Wednesday, May 10, 2023` | ✅ | 0 |
| 10 | `formatTimes` | Expands or simplifies time expressions. | `14:00` | `14` | ✅ | 0 |
| 11 | `formatDistances`, `formatUnits`, `formatPercentages`, `formatPhoneNumbers` | Converts units, distances, percentages, and phone numbers into spoken words. | `5km`, `43 lb`, `50%`, `123-456-7890` | `5 kilometers`, `forty three pounds`, `50 percent`, `1 2 3 4 5 6 7 8 9 0` | ✅ | 0 |
| 12 | `formatNumbers` | Formats general numbers: years read as digits, large numbers spelled out, negative and decimal numbers clarified. | `-9`, `2.5`, `2023` | `minus nine`, `two point five`, `2023` | ✅ | 0 |
| 13 | `removeAsterisks` | Removes all asterisk characters from the text. | `**Bold** and *italic*` | `Bold and italic` | ✅ | 1 |
| 14 | `Applying Replacements` | Applies user-defined final replacements like expanding street abbreviations. | `320 ST 21 RD` | `320 STREET 21 ROAD` | ✅ | - |
***
## Customizing the formatting plan
You can control some aspects of formatting:
### Enabled
Formatting is on by default. To disable, set:
```js
voice.chunkPlan.formatPlan.enabled = false
```
### Number-to-digits cutoff
Controls when numbers are read as digits instead of words.
* **Default:** `2025` (current year)
* Example: With a cutoff of `2025`, numbers above this are read as digits.
* To spell out larger numbers, set the cutoff higher (e.g., `300000`).
### Replacements
Add exact or regex-based substitutions to customize output.
* **Example 1:** Replace `hello` with `hi`:
```js
{ type: 'exact', key: 'hello', value: 'hi' }
```
* **Example 2:** Replace words matching a pattern:
```js
{ type: 'regex', regex: '\b[a-zA-Z]{5}\b', value: 'hi' }
```
Currently, only replacements and the number-to-digits cutoff are customizable. Other options are not exposed.
***
## Turning formatting off
To disable all formatting and use raw LLM output, set either of these to `false`:
```js
voice.chunkPlan.enabled = false
// or
voice.chunkPlan.formatPlan.enabled = false
```
***
## Summary
* Voice input formatting improves clarity and naturalness for TTS.
* Each transformation step targets a specific pattern for better speech output.
* You can customize or disable formatting as needed.
# Flush syntax
> Force immediate voice transmission with VAPI's flush syntax for real-time interactions
## Overview
The flush syntax is a VAPI audio control token that forces immediate transmission of LLM output to voice providers, eliminating buffering delays for real-time voice interactions.
**When to use flush syntax:**
* Acknowledge user requests immediately during processing
* Provide feedback during long-running tool executions
* Create natural conversation pauses
* Support custom LLM integrations with processing delays
Use flush strategically—overuse can cause audio fragmentation and degrade
conversation quality.
## How it works
The flush syntax bypasses normal buffering to provide immediate audio feedback:
1. **Detection**: VAPI scans LLM output for flush syntax using regex pattern
2. **Split**: Text is divided at the flush position
3. **Immediate Send**: Content before flush is sent instantly to voice provider
4. **Continue**: Remaining text follows normal buffering
```typescript title="Processing Example"
const { sendToTTS, flush, remainingBuffer } = ttsBuffer(buffer, voice);
if (sendToTTS.length > 0) {
pushBuffer(sendToTTS, flush); // flush=true triggers immediate send
buffer = remainingBuffer;
}
```
```python title="Conceptual Flow"
# 1. LLM generates: "I'm processing your request... Here's the result"
# 2. VAPI detects flush syntax
# 3. Sends "I'm processing your request..." immediately to voice
# 4. Continues with "Here's the result" using normal buffering
```
## Syntax formats
VAPI supports three flush formats with case-insensitive matching:
````html title="Self-closing (Recommended)"
``` ```html title="Opening tag"
``` ```html title="Closing tag"
````
All formats use regex pattern `/<\s*flush\s*\/?>|<\s*\/\s*flush\s*>/i` allowing whitespace variations.
## Configuration requirements
Flush syntax requires proper voice configuration:
```json title="Assistant Configuration"
{
"voice": {
"chunkPlan": {
"enabled": true // Required for flush to work
}
}
}
```
```typescript title="TypeScript SDK"
const assistant = await vapi.assistants.create({
voice: {
chunkPlan: {
enabled: true
}
}
// ... other configuration
});
```
Flush will NOT work when `chunkPlan.enabled: false`. The tags will appear in
voice output instead of being processed.
## Usage examples
### Basic acknowledgment
```javascript
"I'm processing your request... Let me check that for you.";
```
### Tool processing feedback
```javascript
"Looking up that information... This may take a moment.";
```
### Conversation flow
```javascript
"That's a great question. Based on the data I have...";
```
### Custom LLM integration
```javascript
"Here's your answer: 42. Would you like an explanation?";
```
## Best practices
### When to use flush
Immediately confirm you've received and understood the user's request
Provide feedback during tool calls or processing that takes time
Create conversation breaks at logical points
Support external LLM integrations with processing delays
### When to avoid flush
* **Every response** - Causes audio fragmentation
* **Mid-sentence** - Breaks natural speech flow
* **Short responses** - Normal buffering is sufficient
* **Multiple per response** - Can create choppy audio
### Implementation guidelines
1. **Place at natural boundaries** - Use between complete thoughts or sentences
2. **Test with your voice provider** - Effectiveness varies by provider
3. **Monitor conversation quality** - Ensure audio remains smooth and natural
4. **Document usage** - Include in code comments for team understanding
## Advanced usage
### Dynamic insertion
```typescript
const acknowledgment = "I understand your request";
const detailedResponse = await processRequest(userInput);
const responseWithFlush = `${acknowledgment} ${detailedResponse}`;
```
### System prompt integration
```javascript
const systemPrompt = `When providing lengthy responses, use after acknowledging the user's request to provide immediate feedback.`;
```
### Nested handling
```javascript
"Starting process... Step 1 complete Moving to step 2...";
```
## Troubleshooting
**Cause**: `chunkPlan.enabled` is set to `false` or missing **Solution**: -
Verify `chunkPlan.enabled: true` in voice configuration - Check assistant
configuration in dashboard or API calls - Test with a minimal configuration
to isolate the issue
{" "}
**Cause**: Malformed flush syntax or typos **Solution**: - Use exact formats:
`
`, ``, or `` - Avoid extra parameters or attributes - Check for
typos in tag spelling
**Cause**: Overuse of flush syntax
**Solution**:
* Reduce flush frequency in responses
* Place only at sentence boundaries
* Test with real users to
validate experience
## Technical considerations
### Provider compatibility
* **Effectiveness varies** by voice provider
* **Test thoroughly** with your chosen provider
* **Monitor performance** impact on response times
### Cost implications
* **Increased API calls** to voice provider
* **Higher usage** on usage-based pricing
* **Monitor billing** if using flush frequently
### VAPI-only feature
* **Platform exclusive** - not available on other voice platforms
* **Configuration dependent** - requires chunking enabled
* **Version specific** - ensure using compatible VAPI version
## Next steps
Now that you understand flush syntax:
* **[Voice formatting plan](/assistants/voice-formatting-plan):** Control voice output formatting and timing
* **[Background messages](/assistants/background-messages):** Send messages during conversations
* **[Custom tools](/tools/custom-tools):** Build tools that benefit from flush syntax feedback
# Background messages
> Silently update chat history with background messages
## Overview
Background messages let you add information to the chat history without interrupting or notifying the user. This is useful for logging actions, tracking background events, or updating conversation context silently.
For example, you might want to log when a user presses a button or when a background process updates the conversation. These messages help you keep a complete record of the conversation and system events, all without disrupting the user experience.
Add a button to your interface with an `onClick` event handler that will call a function to send the system message:
```html
```
When the button is clicked, the `logUserAction` function will silently insert a system message into the chat history:
```js
function logUserAction() {
// Function to log the user action
vapi.send({
type: "add-message",
message: {
role: "system",
content: "The user has pressed the button, say peanuts",
},
});
}
```
* `vapi.send`: The primary function to interact with your assistant, handling various requests or commands.
* `type: "add-message"`: Specifies the command to add a new message.
* `message`: This is the actual message that you want to add to the message history.
* `role`: "system" Designates the message origin as 'system', ensuring the addition is unobtrusive. Other possible values of role are 'user' | 'assistant' | 'tool' | 'function'
* `content`: The actual message text to be added.
* Silent logging of user activities.
* Contextual updates in conversations triggered by background processes.
* Non-intrusive user experience enhancements through additional information provision.
# Idle messages
> Keep users engaged during conversation pauses
## Overview
Idle messages automatically prompt users during periods of inactivity to maintain engagement and reduce call abandonment. They work alongside silence timeout messages to handle conversation flow during calls.
**Idle messages help you:**
* Re-engage users who become distracted or experience audio delays
* Reduce call abandonment rates during silent periods
* Provide proactive assistance when users hesitate or need guidance
Idle messages are automatically disabled during tool calls and warm transfers
to avoid interrupting system processes.
## How idle messages work
When a user stops speaking, Vapi starts a timer. After the configured timeout period, it randomly selects and speaks one of your idle messages. This process repeats until either the user responds or the maximum message count is reached.
Timer starts when user stops speaking
Random message plays after timeout
Counter resets when user responds (optional)
## Configuration
Configure idle messages in your assistant's `messagePlan`:
```typescript title="TypeScript (Server SDK)"
import { VapiClient } from "@vapi-ai/server-sdk";
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
const assistant = await client.assistants.create({
name: "Support Assistant",
messagePlan: {
idleMessages: [
"Are you still there?",
"Can I help you with anything else?",
"I'm here whenever you're ready to continue."
],
idleTimeoutSeconds: 15,
idleMessageMaxSpokenCount: 3,
idleMessageResetCountOnUserSpeechEnabled: true
}
});
```
```python title="Python (Server SDK)"
from vapi import Vapi
client = Vapi(token=os.getenv("VAPI_API_KEY"))
assistant = client.assistants.create(
name="Support Assistant",
message_plan={
"idle_messages": [
"Are you still there?",
"Can I help you with anything else?",
"I'm here whenever you're ready to continue."
],
"idle_timeout_seconds": 15,
"idle_message_max_spoken_count": 3,
"idle_message_reset_count_on_user_speech_enabled": True
}
)
```
```bash title="cURL"
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Assistant",
"messagePlan": {
"idleMessages": [
"Are you still there?",
"Can I help you with anything else?",
"I'"'"'m here whenever you'"'"'re ready to continue."
],
"idleTimeoutSeconds": 15,
"idleMessageMaxSpokenCount": 3,
"idleMessageResetCountOnUserSpeechEnabled": true
}
}'
```
## Configuration options
### Core settings
| Parameter | Type | Range | Default | Description |
| ------------------------------------------ | ---------- | ---------------- | ----------- | ----------------------------------------- |
| `idleMessages` | `string[]` | ≤1000 chars each | `undefined` | Array of messages to randomly select from |
| `idleTimeoutSeconds` | `number` | 5-60 seconds | 10 | Timeout before triggering first message |
| `idleMessageMaxSpokenCount` | `number` | 1-10 messages | 3 | Maximum times to repeat messages |
| `idleMessageResetCountOnUserSpeechEnabled` | `boolean` | - | `false` | Reset count when user speaks |
### Advanced configuration
```json
{
"messagePlan": {
"idleMessages": ["Are you still there?"],
"idleTimeoutSeconds": 10
}
}
```
```json
{
"messagePlan": {
"idleMessages": ["Hello, are you there?"],
"idleTimeoutSeconds": 15,
"idleMessageMaxSpokenCount": 5,
"idleMessageResetCountOnUserSpeechEnabled": true
}
}
```
```json
{
"messagePlan": {
"idleMessages": ["Can I help you with anything else?"],
"idleTimeoutSeconds": 20,
"silenceTimeoutMessage": "I'll end our call now. Thank you!"
},
"silenceTimeoutSeconds": 60
}
```
## Multilingual support
Handle multiple languages by creating language-specific assistants or dynamically updating messages:
```typescript
// English assistant
const enAssistant = await client.assistants.create({
name: "EN Support",
messagePlan: {
idleMessages: [
"Are you still there?",
"Can I help you with anything else?"
]
}
});
// Spanish assistant
const esAssistant = await client.assistants.create({
name: "ES Support",
messagePlan: {
idleMessages: [
"¿Sigues ahí?",
"¿Puedo ayudarte con algo más?"
]
}
});
```
```typescript
async function updateIdleMessagesForLanguage(
assistantId: string,
detectedLanguage: string
) {
const languageMessages = {
en: ['Are you still there?', 'Can I help you with anything else?'],
es: ['¿Sigues ahí?', '¿Puedo ayudarte con algo más?'],
fr: ['Êtes-vous toujours là?', 'Puis-je vous aider avec autre chose?']
};
await client.assistants.update(assistantId, {
messagePlan: {
idleMessages: languageMessages[detectedLanguage] || languageMessages['en']
}
});
}
```
## Best practices
### Message content guidelines
* **Keep messages concise** - Users may be distracted, so shorter is better
* **Use encouraging tone** - Avoid demanding or impatient language
* **Offer specific help** - Guide users toward productive next steps
**Good examples:** - "Are you still there?" - "Is there anything specific you
need help with?" - "I'm here whenever you're ready to continue."
**Avoid:** - "Why aren't you responding?" - "Hello? Hello? Are you there?" -
Long explanations or complex questions
### Timing recommendations
Choose timeout duration based on your use case:
**5-10 seconds** For transactional or time-sensitive interactions
**10-20 seconds** For general customer service and assistance
**20-30 seconds** For problem-solving or decision-making conversations
### Frequency management
Balance engagement with user experience:
```json
{
"idleMessageMaxSpokenCount": 2,
"idleMessageResetCountOnUserSpeechEnabled": true,
"idleTimeoutSeconds": 15
}
```
Enable `idleMessageResetCountOnUserSpeechEnabled` to give users multiple
chances to engage throughout long conversations.
## Troubleshooting
### Messages not triggering
Check that idle messages are properly configured:
```typescript
const assistant = await client.assistants.get(assistantId);
console.log('Idle config:', assistant.messagePlan);
```
Account for audio processing delays (2-3 seconds):
```json
{ "idleTimeoutSeconds": 12 }
```
Ensure the maximum count hasn't been reached:
```json
{
"idleMessageMaxSpokenCount": 5,
"idleMessageResetCountOnUserSpeechEnabled": true
}
```
### Common issues and solutions
**Solution:** Increase the timeout duration
```json
{ "idleTimeoutSeconds": 25 }
```
**Solution:** Enable reset on user speech and increase max count
```json
{
"idleMessageMaxSpokenCount": 5,
"idleMessageResetCountOnUserSpeechEnabled": true
}
```
**Solution:** This shouldn't happen - idle messages are automatically disabled during tool calls and transfers. If it persists, contact support.
## Limitations
* **Static content**: Messages cannot be dynamically generated based on conversation context
* **No context awareness**: Messages don't adapt to the current conversation topic
* **Character limits**: Each message is limited to 1000 characters
* **Processing delays**: Account for 2-3 seconds of audio processing time in your timeout settings
## Next steps
Now that you have idle messages configured:
* **[Background messages](/assistants/background-messages):** Add contextual information silently
* **[Assistant hooks](/assistants/assistant-hooks):** Handle call events and state changes
* **[Voice formatting plan](/assistants/voice-formatting-plan):** Control speech patterns and delivery
# Assistant hooks
> Automate actions on call events and interruptions
## Overview
Assistant hooks let you automate actions when specific events occur during a call. Use hooks to transfer calls, run functions, or send messages in response to events like call ending or speech interruptions.
Supported events include:
* `call.ending`: When a call is ending
* `assistant.speech.interrupted`: When the assistant's speech is interrupted
* `customer.speech.interrupted`: When the customer's speech is interrupted
You can combine actions and add filters to control when hooks trigger.
## How hooks work
Hooks are defined in the `hooks` array of your assistant configuration. Each hook includes:
* `on`: The event that triggers the hook
* `do`: The actions to perform (supports `transfer`, `function`, and `say`)
* `filters`: (Optional) Conditions that must be met for the hook to trigger
The `call.endedReason` filter can be set to any of the [call ended reasons](/api-reference/calls/get#response.body.endedReason).\
The transfer destination type follows the [transfer call tool destinations](/api-reference/tools/create#request.body.transferCall.destinations) schema.
## Example: Transfer on pipeline error
Transfer a call to a fallback number if a pipeline error occurs:
```json
{
"hooks": [{
"on": "call.ending",
"filters": [{
"type": "oneOf",
"key": "call.endedReason",
"oneOf": ["pipeline-error"]
}],
"do": [{
"type": "transfer",
"destination": {
"type": "number",
"number": "+1234567890",
"callerId": "+1987654321"
}
}]
}]
}
```
You can also transfer to a SIP destination:
```json
{
"hooks": [{
"on": "call.ending",
"filters": [{
"type": "oneOf",
"key": "call.endedReason",
"oneOf": ["pipeline-error"]
}],
"do": [{
"type": "transfer",
"destination": {
"type": "sip",
"sipUri": "sip:user@domain.com"
}
}]
}]
}
```
## Example: Combine actions on pipeline error
Perform multiple actions—say a message, call a function, and transfer the call—when a pipeline error occurs:
```json
{
"hooks": [{
"on": "call.ending",
"filters": [{
"type": "oneOf",
"key": "call.endedReason",
"oneOf": ["pipeline-error"]
}],
"do": [
{
"type": "say",
"exact": "I apologize for the technical difficulty. Let me transfer you to our support team."
},
{
"type": "function",
"function": {
"name": "log_error",
"parameters": {
"type": "object",
"properties": {
"error_type": {
"type": "string",
"value": "pipeline_error"
}
}
},
"description": "Logs the error details for monitoring"
},
"async": true,
"server": {
"url": "https://your-server.com/api"
}
},
{
"type": "transfer",
"destination": {
"type": "number",
"number": "+1234567890",
"callerId": "+1987654321"
}
}
]
}]
}
```
## Example: Handle speech interruptions
Respond when the assistant's speech is interrupted by the customer:
```json
{
"hooks": [{
"on": "assistant.speech.interrupted",
"do": [{
"type": "say",
"exact": ["Sorry about that", "Go ahead", "Please continue"]
}]
}]
}
```
Handle customer speech interruptions in a similar way:
```json
{
"hooks": [{
"on": "customer.speech.interrupted",
"do": [{
"type": "say",
"exact": "I apologize for interrupting. Please continue."
}]
}]
}
```
Use `"oneOf": ["pipeline-error"]` as a catch-all filter for any pipeline-related error reason.
## Common use cases
* Transfer to a human agent on errors
* Route to a fallback system if the assistant fails
* Handle customer or assistant interruptions gracefully
* Log errors or events for monitoring
## Slack Webhook on Call Failure
You can set up automatic Slack notifications when calls fail by combining assistant hooks with Slack webhooks. This is useful for monitoring call quality and getting immediate alerts when issues occur.
### Step 1: Generate a Slack webhook
Follow the [Slack webhook documentation](https://api.slack.com/messaging/webhooks) to create an incoming webhook:
1. Create a Slack app (if you don't have one already)
2. Enable incoming webhooks in your app settings
3. Create an incoming webhook for your desired channel
4. Copy the webhook URL (it will look like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX`)
### Step 2: Create a serverless function
Set up a serverless function (using a service like [val.town](https://val.town)) to convert Vapi tool call requests into Slack messages:
```javascript
export default async function(req: Request): Promise {
try {
const json = await req.json();
console.log(json);
const callId = json.message.call.id;
const reason = json.message.toolCalls[0].function.arguments.properties.callEndedReason.value;
fetch("", {
"method": "POST",
"headers": {
"Content-Type": "application/json",
},
body: JSON.stringify({
text: `🚨 Call Failed\nCall ID: ${callId}\nReason: ${reason}`
}),
});
return Response.json({
results: [{
"result": "success",
"toolCallId": "hook-function-call"
}],
});
} catch (err) {
console.error("JSON parsing error:", err);
return new Response("Invalid JSON", { status: 400 });
}
}
```
### Step 3: Configure the assistant hook
Add this hook configuration to your assistant to trigger Slack notifications on call failures:
```json
{
"hooks": [{
"on": "call.ending",
"filters": [{
"type": "oneOf",
"key": "call.endedReason",
"oneOf": ["pipeline-error"]
}],
"do": [{
"type": "function",
"function": {
"name": "report_error",
"parameters": {
"type": "object",
"properties": {
"text": {
"type": "string",
"value": "A call error occurred."
}
}
},
"description": "Reports a call error to Slack."
},
"async": false,
"server": {
"url": ""
}
}]
}]
}
```
Replace `` with your actual Slack webhook URL and `` with your serverless function endpoint.
# Background speech denoising
> Filter out noise and background speech while users are talking
## Overview
Background speech denoising helps create clearer conversations by filtering out unwanted sounds while users speak. Vapi offers two complementary denoising technologies that can be used independently or together for optimal results.
**In this guide, you'll learn to:**
* Enable Smart Denoising using Krisp technology (recommended for most users)
* Configure experimental Fourier denoising with customizable parameters
* Combine both methods for enhanced noise reduction
* Fine-tune settings for different environments
**For most use cases, Smart Denoising alone provides excellent results.** Fourier denoising is a highly experimental feature that requires significant tuning and may not work well in all environments.
## Denoising methods
### Smart Denoising (Krisp)
Smart Denoising uses Krisp's AI-powered technology to remove background noise in real-time. This method is highly effective for common noise sources like:
* Keyboard typing
* Background conversations
* Traffic and street noise
* Air conditioning and fans
* Pet sounds
### Fourier Denoising (Experimental)
Fourier denoising uses frequency-domain filtering to remove consistent background noise. This experimental method offers fine-grained control through multiple parameters and includes automatic media detection for TV/music/radio backgrounds.
Fourier denoising is highly experimental and comes with significant limitations:
* Requires extensive tweaking to work properly
* May not work well in all audio environments (e.g., when headphones are used)
* Can introduce audio artifacts or distortions
* Should only be used when Smart Denoising alone is insufficient
**For most users, Smart Denoising should be sufficient.** Only proceed with Fourier denoising if you have specific requirements and are prepared to test extensively.
## Configuration
Background speech denoising is configured through the `backgroundSpeechDenoisingPlan` property on your assistant:
```typescript title="TypeScript SDK"
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({
token: process.env.VAPI_API_KEY
});
const assistant = await vapi.assistants.create({
name: "Customer Support",
backgroundSpeechDenoisingPlan: {
// Enable Smart Denoising
smartDenoisingPlan: {
enabled: true
},
// Enable Fourier Denoising (optional)
fourierDenoisingPlan: {
enabled: true,
mediaDetectionEnabled: true,
staticThreshold: -35,
baselineOffsetDb: -15,
windowSizeMs: 3000,
baselinePercentile: 85
}
}
});
```
```python title="Python SDK"
from vapi import Vapi
import os
client = Vapi(token=os.getenv("VAPI_API_KEY"))
assistant = client.assistants.create(
name="Customer Support",
backgroundSpeechDenoisingPlan={
# Enable Smart Denoising
"smartDenoisingPlan": {
"enabled": True
},
# Enable Fourier Denoising (optional)
"fourierDenoisingPlan": {
"enabled": True,
"mediaDetectionEnabled": True,
"staticThreshold": -35,
"baselineOffsetDb": -15,
"windowSizeMs": 3000,
"baselinePercentile": 85
}
}
)
```
```bash title="cURL"
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support",
"backgroundSpeechDenoisingPlan": {
"smartDenoisingPlan": {
"enabled": true
},
"fourierDenoisingPlan": {
"enabled": true,
"mediaDetectionEnabled": true,
"staticThreshold": -35,
"baselineOffsetDb": -15,
"windowSizeMs": 3000,
"baselinePercentile": 85
}
}
}'
```
## Smart Denoising configuration
Smart Denoising has a simple on/off configuration:
Enable or disable Krisp-powered smart denoising
### Example: Smart Denoising only
```typescript title="TypeScript SDK"
const assistant = await vapi.assistants.create({
name: "Support Agent",
backgroundSpeechDenoisingPlan: {
smartDenoisingPlan: {
enabled: true
}
}
});
```
```python title="Python SDK"
assistant = client.assistants.create(
name="Support Agent",
backgroundSpeechDenoisingPlan={
"smartDenoisingPlan": {
"enabled": True
}
}
)
```
## Fourier Denoising configuration
Fourier denoising offers multiple parameters for fine-tuning:
Enable or disable experimental Fourier denoising
Automatically detect and filter consistent background media (TV/music/radio)
Fallback threshold in dB when no baseline is established (-80 to 0)
How far below the rolling baseline to filter audio, in dB (-30 to -5)
* Lower values (e.g., -10) = more aggressive filtering
* Higher values (e.g., -20) = more conservative filtering
Rolling window size in milliseconds for baseline calculation (1000 to 30000)
* Larger windows = slower adaptation, more stability
* Smaller windows = faster adaptation, less stability
Percentile for baseline calculation (1 to 99)
* Higher percentiles (e.g., 85) = focus on louder speech
* Lower percentiles (e.g., 50) = include quieter speech
### Example: Adding Fourier Denoising to Smart Denoising
```typescript title="TypeScript SDK"
const assistant = await vapi.assistants.create({
name: "Call Center Agent",
backgroundSpeechDenoisingPlan: {
// Always enable Smart Denoising first
smartDenoisingPlan: {
enabled: true
},
// Add Fourier Denoising for additional filtering
fourierDenoisingPlan: {
enabled: true,
mediaDetectionEnabled: true,
// More aggressive filtering for noisy environments
baselineOffsetDb: -10,
// Faster adaptation for dynamic environments
windowSizeMs: 2000,
// Focus on louder, clearer speech
baselinePercentile: 90
}
}
});
```
```python title="Python SDK"
assistant = client.assistants.create(
name="Call Center Agent",
backgroundSpeechDenoisingPlan={
# Always enable Smart Denoising first
"smartDenoisingPlan": {
"enabled": True
},
# Add Fourier Denoising for additional filtering
"fourierDenoisingPlan": {
"enabled": True,
"mediaDetectionEnabled": True,
# More aggressive filtering for noisy environments
"baselineOffsetDb": -10,
# Faster adaptation for dynamic environments
"windowSizeMs": 2000,
# Focus on louder, clearer speech
"baselinePercentile": 90
}
}
)
```
## Combined denoising
For maximum noise reduction, combine both methods. Processing order:
1. Smart Denoising (Krisp) processes first
2. Fourier Denoising processes the Krisp output
## Environment-specific configurations
### Quiet office environment
Minimal speech denoising for clear environments:
```typescript title="TypeScript SDK"
const assistant = await vapi.assistants.create({
name: "Office Assistant",
backgroundSpeechDenoisingPlan: {
smartDenoisingPlan: {
enabled: true
}
// No Fourier denoising needed
}
});
```
```python title="Python SDK"
assistant = client.assistants.create(
name="Office Assistant",
backgroundSpeechDenoisingPlan={
"smartDenoisingPlan": {
"enabled": True
}
# No Fourier denoising needed
}
)
```
### Noisy call center
Aggressive filtering for high-noise environments:
```typescript title="TypeScript SDK"
const assistant = await vapi.assistants.create({
name: "Call Center Agent",
backgroundSpeechDenoisingPlan: {
smartDenoisingPlan: {
enabled: true
},
fourierDenoisingPlan: {
enabled: true,
mediaDetectionEnabled: true,
baselineOffsetDb: -10, // Aggressive filtering
windowSizeMs: 2000, // Fast adaptation
baselinePercentile: 90 // Focus on clear speech
}
}
});
```
```python title="Python SDK"
assistant = client.assistants.create(
name="Call Center Agent",
backgroundSpeechDenoisingPlan={
"smartDenoisingPlan": {
"enabled": True
},
"fourierDenoisingPlan": {
"enabled": True,
"mediaDetectionEnabled": True,
"baselineOffsetDb": -10, # Aggressive filtering
"windowSizeMs": 2000, # Fast adaptation
"baselinePercentile": 90 # Focus on clear speech
}
}
)
```
### Home environment with TV/music
Optimized for media background noise:
```typescript title="TypeScript SDK"
const assistant = await vapi.assistants.create({
name: "Home Assistant",
backgroundSpeechDenoisingPlan: {
smartDenoisingPlan: {
enabled: true
},
fourierDenoisingPlan: {
enabled: true,
mediaDetectionEnabled: true, // Essential for TV/music
baselineOffsetDb: -15,
windowSizeMs: 4000,
baselinePercentile: 80
}
}
});
```
```python title="Python SDK"
assistant = client.assistants.create(
name="Home Assistant",
backgroundSpeechDenoisingPlan={
"smartDenoisingPlan": {
"enabled": True
},
"fourierDenoisingPlan": {
"enabled": True,
"mediaDetectionEnabled": True, # Essential for TV/music
"baselineOffsetDb": -15,
"windowSizeMs": 4000,
"baselinePercentile": 80
}
}
)
```
## Best practices
**For most users, Smart Denoising alone is the recommended solution.** It handles the vast majority of common noise scenarios effectively without configuration complexity. Only consider adding Fourier denoising if you have specific requirements that Smart Denoising cannot address.
### When to use each method
**Smart Denoising only:**
* General-purpose noise reduction
* Unpredictable noise patterns
* When simplicity is preferred
**Smart Denoising + Fourier Denoising:**
* Maximum noise reduction required
* Consistent background noise that Smart Denoising alone cannot fully handle
* Complex acoustic environments with media (TV/music/radio)
* Premium user experiences requiring fine-tuned control
* Willing to invest time in testing and tuning
* Not using headphones (Fourier may cause issues with headphone audio)
Fourier Denoising should never be used alone. It's designed to complement Smart Denoising by providing additional filtering after Krisp has done the initial noise reduction.
### Performance considerations
**Audio quality**: Aggressive filtering may affect voice quality. Test different settings to find the right balance between noise reduction and natural speech preservation.
### Testing recommendations
1. Test in your target environment
2. Start with default settings
3. Adjust parameters incrementally
4. Monitor user feedback
5. A/B test different configurations
## Troubleshooting fourier denoising
Reduce filtering aggressiveness:
* Increase `baselineOffsetDb` (e.g., -20 instead of -15)
* Decrease `baselinePercentile` (e.g., 75 instead of 85)
* Try Smart Denoising only
Increase filtering:
* Enable both denoising methods
* Decrease `baselineOffsetDb` (e.g., -12 instead of -15)
* Ensure `mediaDetectionEnabled` is true for TV/music
Adjust detection sensitivity:
* Increase `windowSizeMs` for more stability
* Adjust `staticThreshold` if baseline isn't establishing
* Check if user's voice level is consistent
# Speech configuration
> Control when your assistant starts and stops speaking
## Overview
Speech configuration lets you control exactly when your assistant starts and stops speaking during a conversation. By tuning these settings, you can make your assistant feel more natural, avoid interrupting the customer, and reduce awkward pauses.
Speech speed can be controlled, but only PlayHT currently supports this feature with the `speed` field. Other providers do not currently support speed.
The two main components are:
* **Speaking Plan**: Controls when the assistant begins speaking after the customer finishes or pauses.
* **Stop Speaking Plan**: Controls when the assistant stops speaking if the customer starts talking.
Fine-tuning these plans helps you adapt the assistant's responsiveness to your use case—whether you want fast, snappy replies or a more patient, human-like conversation flow.
Currently, these configurations can only be set via API.
The rest of this page explains each setting and provides practical examples for different scenarios.
## Start Speaking Plan
This plan defines the parameters for when the assistant begins speaking after the customer pauses or finishes.
* **Wait Time Before Speaking**: You can set how long the assistant waits before speaking after the customer finishes. The default is 0.4 seconds, but you can increase it if the assistant is speaking too soon, or decrease it if there's too much delay.
**Example:** For tech support calls, set `waitSeconds` for the assistant to more than 1.0 seconds to give customers time to complete their thoughts, even if they have some pauses in between.
* **Smart Endpointing Plan**: This feature uses advanced processing to detect when the customer has truly finished speaking, especially if they pause mid-thought. It can be configured in three ways:
* **Off**: Disabled by default
* **LiveKit**: Recommended for English conversations as it provides the most sophisticated solution for detecting natural speech patterns and pauses. LiveKit can be fine-tuned using the `waitFunction` parameter to adjust response timing based on the probability that the user is still speaking.
* **Vapi**: Recommended for non-English conversations or as an alternative when LiveKit isn't suitable
**LiveKit Smart Endpointing Configuration:**
When using LiveKit, you can customize the `waitFunction` parameter which determines how long the bot will wait to start speaking based on the likelihood that the user has finished speaking:
```
waitFunction: "200 + 8000 * x"
```
This function maps probabilities (0-1) to milliseconds of wait time. A probability of 0 means high confidence the caller has stopped speaking, while 1 means high confidence they're still speaking. The default function (`200 + 8000 * x`) creates a wait time between 200ms (when x=0) and 8200ms (when x=1). You can customize this with your own mathematical expression, such as `4000 * (1 - cos(pi * x))` for a different response curve.
**Example:** In insurance claims, smart endpointing helps avoid interruptions while customers think through complex responses. For instance, when the assistant asks "do you want a loan," the system can intelligently wait for the complete response rather than interrupting after the initial "yes" or "no." For responses requiring number sequences like "What's your account number?", the system can detect natural pauses between digits without prematurely ending the customer's turn to speak.
* **Transcription-Based Detection**: Customize how the assistant determines that the customer has stopped speaking based on what they're saying. This offers more control over the timing. **Example:** When a customer says, "My account number is 123456789, I want to transfer \$500."
* The system detects the number "123456789" and waits for 0.5 seconds (`WaitSeconds`) to ensure the customer isn't still speaking.
* If the customer were to finish with an additional line, "I want to transfer \$500.", the system uses `onPunctuationSeconds` to confirm the end of the speech and then proceed with the request processing.
* In a scenario where the customer has been silent for a long and has already finished speaking but the transcriber is not confident to punctuate the transcription, `onNoPunctuationSeconds` is used for 1.5 seconds.
## Stop Speaking Plan
The Stop Speaking Plan defines when the assistant stops talking after detecting customer speech.
* **Words to Stop Speaking**: Define how many words the customer needs to say before the assistant stops talking. If you want immediate reaction, set this to 0. Increase it to avoid interruptions by brief acknowledgments like "okay" or "right". **Example:** While setting an appointment with a clinic, set `numWords` to 2-3 words to allow customers to finish brief clarifications without triggering interruptions.
* **Voice Activity Detection**: Adjust how long the customer needs to be speaking before the assistant stops. The default is 0.2 seconds, but you can tweak this to balance responsiveness and avoid false triggers.
**Example:** For a banking call center, setting a higher `voiceSeconds` value ensures accuracy by reducing false positives. This avoids interruptions caused by background sounds, even if it slightly delays the detection of speech onset. This tradeoff is essential to ensure the assistant processes only correct and intended information.
* **Pause Before Resuming**: Control how long the assistant waits before starting to talk again after being interrupted. The default is 1 second, but you can adjust it depending on how quickly the assistant should resume.
**Example:** For quick queries (e.g., "What's the total order value in my cart?"), set `backoffSeconds` to 1 second.
Here's a code snippet for Stop Speaking Plan -
```json
"stopSpeakingPlan": {
"numWords": 0,
"voiceSeconds": 0.2,
"backoffSeconds": 1
}
```
## Considerations for Configuration
* **Customer Style**: Think about whether the customer pauses mid-thought or provides continuous speech. Adjust wait times and enable smart endpointing as needed.
* **Background Noise**: If there's a lot of background noise, you may need to tweak the settings to avoid false triggers. Default for phone calls is 'office' and default for web calls is 'off'.
```json
"backgroundSound": "off",
```
* **Conversation Flow**: Aim for a balance where the assistant is responsive but not intrusive. Test different settings to find the best fit for your needs.
# Voice pipeline configuration
> Complete guide to configuring VAPI's voice pipeline for optimal conversation timing and interruption handling
## Overview
Configure VAPI's voice pipeline to create natural conversation experiences through precise timing control. This guide covers how voice data moves through processing stages and how to optimize endpointing and interruption detection.
**Voice pipeline configuration enables you to:**
* Fine-tune conversation timing for specific use cases
* Control when and how your assistant begins responding
* Configure interruption detection and recovery behavior
* Optimize response timing for different languages and contexts
For implementation examples, see **[Configuration examples](#configuration-examples)**.
## Quick start
### English conversations (recommended)
```json
{
"startSpeakingPlan": {
"smartEndpointingPlan": {
"provider": "livekit",
"waitFunction": "2000 / (1 + exp(-10 * (x - 0.5)))"
},
"waitSeconds": 0.4
},
"stopSpeakingPlan": {
"numWords": 0,
"voiceSeconds": 0.2,
"backoffSeconds": 1.0
}
}
```
**What this provides:**
* Smart endpointing detects when users finish speaking (English only)
* Fast interruption using voice detection (50-100ms response)
* Natural timing with balanced wait periods
### Non-English languages
```json
{
"startSpeakingPlan": {
"transcriptionEndpointingPlan": {
"onPunctuationSeconds": 0.1,
"onNoPunctuationSeconds": 1.5,
"onNumberSeconds": 0.5
},
"waitSeconds": 0.4
},
"stopSpeakingPlan": {
"numWords": 0,
"voiceSeconds": 0.2,
"backoffSeconds": 1.0
}
}
```
**What this provides:**
* Text-based endpointing works with any language
* Punctuation detection for natural conversation flow
* Same fast interruption and timing as English setup
## Voice pipeline flow
### Complete processing pipeline
```
User Audio → VAD → Transcription → Start Speaking Decision → LLM → TTS → waitSeconds → Assistant Audio
```
### Start speaking process
Voice Activity Detection (VAD) detects utterance-stop
System evaluates completion using: - Custom Rules (highest priority) - Smart
Endpointing Plan (LiveKit for English) - Transcription Endpointing Plan
(fallback)
LLM request sent immediately → TTS processes → waitSeconds applied →
Assistant speaks
### Stop speaking process
VAD detects utterance-start during assistant speech
System checks for: - `interruptionPhrases` → Instant pipeline clear -
`acknowledgementPhrases` → Ignore interruption - Threshold evaluation based
on `numWords` setting
If threshold met → Clear pipeline → Apply `backoffSeconds` → Ready for next
input
## Start speaking plan
The start speaking plan determines when your assistant begins responding after a user stops talking.
### Transcription endpointing
Analyzes transcription text to determine user completion based on patterns like punctuation and numbers.
```json
{
"startSpeakingPlan": {
"transcriptionEndpointingPlan": {
"onPunctuationSeconds": 0.1,
"onNoPunctuationSeconds": 1.5,
"onNumberSeconds": 0.5
},
"waitSeconds": 0.4
}
}
```
**onPunctuationSeconds** (Default: 0.1)\
Wait time after punctuation marks are detected
**onNoPunctuationSeconds** (Default: 1.5)
Wait time when no punctuation is detected
**onNumberSeconds** (Default: 0.5)
Wait time after numbers are detected
**When to use:**
* Non-English languages (LiveKit not supported)
* Fallback when smart endpointing unavailable
* Predictable, rule-based endpointing behavior
### Smart endpointing
Uses AI models to analyze speech patterns, context, and audio cues to predict when users have finished speaking. Only available for English conversations.
```json
{
"startSpeakingPlan": {
"smartEndpointingPlan": {
"provider": "livekit",
"waitFunction": "2000 / (1 + exp(-10 * (x - 0.5)))"
},
"waitSeconds": 0.4
}
}
```
**livekit**\
Advanced model trained on conversation data (recommended for English)
**vapi**
Alternative VAPI-trained model
**When to use:**
* English conversations
* Natural conversation flow requirements
* Reduced false endpointing triggers
### Wait function
Mathematical expression that determines wait time based on speech completion probability. The function takes a confidence value (0-1) and returns a wait time in milliseconds.
**Aggressive (Fast Response):**
```json
"waitFunction": "2000 / (1 + exp(-10 * (x - 0.5)))"
```
* **Behavior:** Responds quickly when confident user is done speaking
* **Use case:** Customer service, gaming, real-time interactions
* **Timing:** \~200ms wait at 50% confidence, \~50ms at 90% confidence
**Normal (Balanced):**
```json
"waitFunction": "(20 + 500 * sqrt(x) + 2500 * x^3 + 700 + 4000 * max(0, x-0.5)) / 2"
```
* **Behavior:** Waits for natural pauses in conversation
* **Use case:** Most conversations, general purpose
* **Timing:** \~800ms wait at 50% confidence, \~300ms at 90% confidence
**Conservative (Careful Response):**
```json
"waitFunction": "700 + 4000 * max(0, x-0.5)"
```
* **Behavior:** Very patient, rarely interrupts users
* **Use case:** Healthcare, formal settings, sensitive conversations
* **Timing:** \~2700ms wait at 50% confidence, \~700ms at 90% confidence
### Wait seconds
Final audio delay applied after all processing completes, before the assistant speaks.
**Range:** 0-5 seconds (Default: 0.4)
**Recommended settings:**
* **0.0-0.2:** Gaming, real-time interactions
* **0.3-0.5:** Standard conversations, customer service
* **0.6-0.8:** Healthcare, formal settings
#### Pipeline timing relationship
`waitSeconds` is applied at the END of the voice pipeline processing:
```
Endpointing Triggers → LLM Processes → TTS Generates → waitSeconds Delay → Assistant Speaks
```
**Relationship with other timing components:**
* **Endpointing timing:** Varies by method (smart vs transcription)
* **LLM processing:** \~800ms average for standard responses
* **TTS generation:** \~500ms average for short responses
* **waitSeconds:** Applied as final delay before audio output
#### Complete pipeline timeline
Understanding exact timing helps optimize your voice pipeline configuration. This timeline shows what happens at every moment during the conversation flow.
```
0.0s: User stops speaking
0.1s: Smart endpointing evaluation begins
0.6s: Smart endpointing triggers (varies by waitFunction)
0.6s: LLM request sent immediately
1.4s: LLM response received (0.8s processing)
1.9s: TTS audio generated (0.5s processing)
1.9s: waitSeconds (0.4s) starts
2.3s: Assistant begins speaking
```
**Total Response Time:** Smart Endpointing (0.6s) + LLM (0.8s) + TTS (0.5s) + waitSeconds (0.4s) = **2.3s**
**Key optimization insights:**
* The 0.6s endpointing time varies based on your waitFunction choice
* Aggressive functions reduce endpointing to \~0.2s
* Conservative functions increase endpointing to \~2.7s
* Total response time ranges from 1.9s (aggressive) to 4.7s (conservative)
### Custom endpointing rules
Highest priority rules that override all other endpointing decisions when patterns match.
```json
{
"customEndpointingRules": [
{
"type": "assistant",
"regex": "(phone|email|address)",
"timeoutSeconds": 3.0
},
{
"type": "user",
"regex": "\\d{3}-\\d{3}-\\d{4}",
"timeoutSeconds": 2.0
}
]
}
```
**Use cases:**
* **Data collection:** Extended wait times for phone numbers, addresses
* **Spelling:** Extra time for letter-by-letter input
* **Complex responses:** Additional processing time for detailed information
## Stop speaking plan
The stop speaking plan controls how interruptions are detected and handled when users speak while the assistant is talking.
### Number of words
Sets the interruption detection method and threshold.
**VAD-based (numWords = 0):**
```json
{
"stopSpeakingPlan": {
"numWords": 0,
"voiceSeconds": 0.2
}
}
```
* **How it works:** Uses Voice Activity Detection for faster interruption (50-100ms)
* **Benefits:** Language independent, very responsive
* **Considerations:** More sensitive to background noise
**Transcription-based (numWords > 0):**
```json
{
"stopSpeakingPlan": {
"numWords": 2
}
}
```
* **How it works:** Waits for specified number of transcribed words
* **Benefits:** More accurate, reduces false positives
* **Considerations:** Slower response (200-500ms delay)
**Range:** 0-10 words (Default: 0)
### Voice seconds
VAD duration threshold when `numWords = 0`. Determines how long voice activity must be detected before triggering an interruption.
**Range:** 0-0.5 seconds (Default: 0.2)
**Recommended settings:**
* **0.1:** Very sensitive (risk of background noise triggering)
* **0.2:** Balanced sensitivity (recommended)
* **0.4:** Conservative (reduces false positives)
#### The numWords=0 and voiceSeconds relationship
When `numWords = 0`, the voice pipeline uses **Voice Activity Detection (VAD)** instead of waiting for transcription:
```
User Starts Speaking → VAD Detects Voice → Continuous for voiceSeconds Duration → Interrupt Assistant
```
**Why this matters:**
* **Faster:** VAD detection \~50-100ms vs transcription 200-500ms
* **More sensitive:** Detects "um", "uh", throat clearing, background noise
* **Language independent:** Works with any language
### Backoff seconds
Duration that blocks all assistant audio output after user interruption, creating a recovery period.
**Range:** 0-10 seconds (Default: 1.0)
**Recommended settings:**
* **0.5:** Quick recovery for fast-paced interactions
* **1.0:** Natural pause for most conversations
* **2.0:** Deliberate pause for formal settings
#### Pipeline timing relationship
```
User Interrupts → Assistant Audio Stopped → backoffSeconds Blocks All Output → Ready for New Input
```
**Relationship with waitSeconds:**
* `backoffSeconds`: Applied during interruption (blocks output)
* `waitSeconds`: Applied to normal responses (delays output)
* **Sequential, not cumulative:** `backoffSeconds` completes first, then normal flow resumes with `waitSeconds`
#### Complete interruption timeline
**How to read this timeline:** This shows the complete flow from interruption to recovery. Notice how backoffSeconds creates a "quiet period" before normal processing resumes.
```
0.0s: Assistant speaking: "I can help you book..."
1.2s: User interrupts: "Actually, wait"
1.2s: backoffSeconds (1.0s) starts → All audio blocked
2.2s: backoffSeconds completes → Ready for new input
2.5s: User says: "What about tomorrow?"
3.0s: Endpointing triggers → LLM processes
3.8s: TTS completes → waitSeconds (0.4s) starts
4.2s: Assistant responds: "For tomorrow..."
```
**Total Recovery Time:** backoffSeconds (1.0s) + normal processing (1.8s) + waitSeconds (0.4s) = **3.2s**
**Key insight:** Adjust backoffSeconds based on how quickly you want the assistant to recover from interruptions. Healthcare might use 2.0s for deliberate pauses, while gaming might use 0.5s for quick recovery.
## Configuration examples
### E-commerce customer support
```json
{
"startSpeakingPlan": {
"waitSeconds": 0.4,
"smartEndpointingPlan": {
"provider": "livekit",
"waitFunction": "2000 / (1 + exp(-10 * (x - 0.5)))"
}
},
"stopSpeakingPlan": {
"numWords": 0,
"voiceSeconds": 0.15,
"backoffSeconds": 0.8
}
}
```
**Optimized for:** Fast response to quick customer queries, efficient order status and product questions.
### Non-English languages (Spanish example)
```json
{
"transcriber": { "language": "es" },
"startSpeakingPlan": {
"waitSeconds": 0.4,
"transcriptionEndpointingPlan": {
"onPunctuationSeconds": 0.1,
"onNoPunctuationSeconds": 2.0
}
},
"stopSpeakingPlan": {
"numWords": 0,
"voiceSeconds": 0.3,
"backoffSeconds": 1.2
}
}
```
**Optimized for:** Text-based endpointing with longer timeouts for different speech patterns and international support.
### Education and training
```json
{
"startSpeakingPlan": {
"waitSeconds": 0.7,
"smartEndpointingPlan": {
"provider": "livekit",
"waitFunction": "(20 + 500 * sqrt(x) + 2500 * x^3 + 700 + 4000 * max(0, x-0.5)) / 2"
},
"customEndpointingRules": [
{
"type": "assistant",
"regex": "(spell|define|explain|example)",
"timeoutSeconds": 4.0
}
]
},
"stopSpeakingPlan": {
"numWords": 1,
"backoffSeconds": 1.5
}
}
```
**Optimized for:** Learning pace with extra time for complex questions and explanations.
## Next steps
Now that you understand voice pipeline configuration:
* **[Speech configuration](speech-configuration):** Learn about provider-specific voice settings
* **[Custom transcriber](custom-transcriber):** Configure transcription providers for your language
* **[Voice fallback plan](../voice-fallback-plan):** Set up backup voice options
* **[Debugging voice agents](../debugging):** Troubleshoot voice pipeline issues
# Voice Fallback Plan
> Configure fallback voices that activate automatically if your primary voice fails.
Voice fallback plans can currently only be configured through the API. We are working on making this available through our dashboard.
## Introduction
Voice fallback plans give you the ability to continue your call in the event that your primary voice fails. Your assistant will sequentially fallback to only the voices you configure within your plan, in the exact order you specify.
Without a fallback plan configured, your call will end with an error in the event that your chosen voice provider fails.
## How It Works
When a voice failure occurs, Vapi will:
1. Detect the failure of the primary voice
2. If a custom fallback plan exists:
* Switch to the first fallback voice in your plan
* Continue through your specified list if subsequent failures occur
* Terminate only if all voices in your plan have failed
## Configuration
Add the `fallbackPlan` property to your assistant's voice configuration, and specify the fallback voices within the `voices` property.
* Please note that fallback voices must be valid JSON configurations, and not strings.
* The order matters. Vapi will choose fallback voices starting from the beginning of the list.
```json
{
"voice": {
"provider": "openai",
"voiceId": "shimmer",
"fallbackPlan": {
"voices": [
{
"provider": "cartesia",
"voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d"
},
{
"provider": "playht",
"voiceId": "jennifer"
}
]
}
}
}
```
## Best practices
* Use different providers for your fallback voices to protect against provider-wide outages.
* Select voices with **similar characteristics** (tone, accent, gender) to maintain consistency in the user experience.
## How will pricing work?
There is no change to the pricing of the voices. Your call will not incur any extra fees while using fallback voices, and you will be able to see the cost for each voice in your end-of-call report.
# OpenAI Realtime
> You can use OpenAI's newest speech-to-speech model with your Vapi assistants.
The Realtime API is currently in beta, and not recommended for production use by OpenAI. We're excited to have you try this new feature and welcome your [feedback](https://discord.com/invite/pUFNcf2WmH) as we continue to refine and improve the experience.
OpenAI’s Realtime API enables developers to use a native speech-to-speech model. Unlike other Vapi configurations which orchestrate a transcriber, model and voice API to simulate speech-to-speech, OpenAI’s Realtime API natively processes audio in and audio out.
To start using it with your Vapi assistants, select `gpt-4o-realtime-preview-2024-12-17` as your model.
* Please note that only OpenAI voices may be selected while using this model. The voice selection will not act as a TTS (text-to-speech) model, but rather as the voice used within the speech-to-speech model.
* Also note that we don’t currently support Knowledge Bases with the Realtime API.
* Lastly, note that our Realtime integration still retains the rest of Vapi's orchestration layer such as Endpointing and Interruption models to enable a reliable conversational flow.
# Provider Keys
> Bring your own API keys to Vapi.
Have a custom model or voice with one of the providers? Or an enterprise account with volume pricing?
No problem! You can bring your own API keys to Vapi. You can add them in the [Dashboard](https://dashboard.vapi.ai) under the **Provider Keys** tab. Once your API key is validated, you won't be charged when using that provider through Vapi. Instead, you'll be charged directly by the provider.
## Transcription Providers
Currently, the only available transcription provider is `deepgram`. To use a custom model, you can specify the deepgram model ID in the `transcriber.model` parameter of the [Assistant](/api-reference/assistants/create-assistant).
## Model Providers
We are currently have support for any OpenAI-compatible endpoint. This includes services like [OpenRouter](https://openrouter.ai/), [AnyScale](https://www.anyscale.com/), [Together AI](https://www.together.ai/), or your own server.
To use one of these providers, you can specify the `provider` and `model` in the `model` parameter of the [Assistant](/api-reference/assistants/create-assistant).
You can find more details in the [Custom LLMs](/customization/custom-llm/fine-tuned-openai-models) section of the documentation.
## Voice Providers
All voice providers are supported. Once you've validated your API through the [Dashboard](https://dashboard.vapi.ai), any voice ID from your provider can be used in the `voice.voiceId` field of the [Assistant](/api-reference/assistants/create-assistant).
## Cloud Providers
Vapi stores recordings of conversations with assistants in the cloud. By default, Vapi stores these recordings in its
own bucket in Cloudflare R2. You can configure Vapi to store recordings in your own bucket in AWS S3, GCP, or
Cloudflare R2.
You can find more details on how to configure your Cloud Provider keys here:
* [AWS S3](/providers/cloud/s3)
* [GCP Cloud Storage](/providers/cloud/gcp)
* [Cloudflare R2](/providers/cloud/cloudflare)
# Custom transcriber
> Integrate your own transcription service with Vapi
## Overview
A custom transcriber lets you use your own transcription service with Vapi, instead of a built-in provider. This is useful if you need more control, want to use a specific provider like Deepgram, or have custom processing needs.
This guide shows you how to set up Deepgram as your custom transcriber. The same approach can be adapted for other providers.
You'll learn how to:
* Stream audio from Vapi to your server
* Forward audio to Deepgram for transcription
* Return real-time transcripts back to Vapi
## Why Use a Custom Transcriber?
* **Flexibility:** Integrate with your preferred transcription service.
* **Control:** Implement specialized processing that isn't available with built‑in providers.
* **Cost Efficiency:** Leverage your existing transcription infrastructure while maintaining full control over the pipeline.
* **Customization:** Tailor the handling of audio data, transcript formatting, and buffering according to your specific needs.
## How it works
Vapi connects to your custom transcriber endpoint (e.g. `/api/custom-transcriber`) via WebSocket. It sends an initial JSON message like this:
```json
{
"type": "start",
"encoding": "linear16",
"container": "raw",
"sampleRate": 16000,
"channels": 2
}
```
Vapi then streams binary PCM audio to your server.
Your server forwards the audio to Deepgram (or your chosen transcriber) using its SDK. Deepgram processes the audio and returns transcript events that include a `channel_index` (e.g. `[0, ...]` for customer, `[1, ...]` for assistant). The service buffers the incoming data, processes the transcript events (with debouncing and channel detection), and emits a final transcript.
The final transcript is sent back to Vapi as a JSON message:
```json
{
"type": "transcriber-response",
"transcription": "The transcribed text",
"channel": "customer" // or "assistant"
}
```
## Implementation steps
Create a new Node.js project and install the required dependencies:
```bash
mkdir vapi-custom-transcriber
cd vapi-custom-transcriber
npm init -y
```
```bash title="npm"
npm install ws express dotenv @deepgram/sdk
```
```bash title="yarn"
yarn add ws express dotenv @deepgram/sdk
```
```bash title="pnpm"
pnpm add ws express dotenv @deepgram/sdk
```
```bash title="bun"
bun add ws express dotenv @deepgram/sdk
```
Create a `.env` file with the following content:
```env
DEEPGRAM_API_KEY=your_deepgram_api_key
PORT=3001
```
Add the following files to your project:
**transcriptionService.js**
```js
const { createClient, LiveTranscriptionEvents } = require("@deepgram/sdk");
const EventEmitter = require("events");
const PUNCTUATION_TERMINATORS = [".", "!", "?"];
const MAX_RETRY_ATTEMPTS = 3;
const DEBOUNCE_DELAY_IN_SECS = 3;
const DEBOUNCE_DELAY = DEBOUNCE_DELAY_IN_SECS * 1000;
const DEEPGRAM_API_KEY = process.env["DEEPGRAM_API_KEY"] || "";
class TranscriptionService extends EventEmitter {
constructor(config, logger) {
super();
this.config = config;
this.logger = logger;
this.flowLogger = require("./fileLogger").createNamedLogger(
"transcriber-flow.log"
);
if (!DEEPGRAM_API_KEY) {
throw new Error("Missing Deepgram API Key");
}
this.deepgramClient = createClient(DEEPGRAM_API_KEY);
this.logger.logDetailed(
"INFO",
"Initializing Deepgram live connection",
"TranscriptionService",
{
model: "nova-2",
sample_rate: 16000,
channels: 2,
}
);
this.deepgramLive = this.deepgramClient.listen.live({
encoding: "linear16",
channels: 2,
sample_rate: 16000,
model: "nova-2",
smart_format: true,
interim_results: true,
endpointing: 800,
language: "en",
multichannel: true,
});
this.finalResult = { customer: "", assistant: "" };
this.audioBuffer = [];
this.retryAttempts = 0;
this.lastTranscriptionTime = Date.now();
this.pcmBuffer = Buffer.alloc(0);
this.deepgramLive.addListener(LiveTranscriptionEvents.Open, () => {
this.logger.logDetailed(
"INFO",
"Deepgram connection opened",
"TranscriptionService"
);
this.deepgramLive.on(LiveTranscriptionEvents.Close, () => {
this.logger.logDetailed(
"INFO",
"Deepgram connection closed",
"TranscriptionService"
);
this.emitTranscription();
this.audioBuffer = [];
});
this.deepgramLive.on(LiveTranscriptionEvents.Metadata, (data) => {
this.logger.logDetailed(
"DEBUG",
"Deepgram metadata received",
"TranscriptionService",
data
);
});
this.deepgramLive.on(LiveTranscriptionEvents.Transcript, (event) => {
this.handleTranscript(event);
});
this.deepgramLive.on(LiveTranscriptionEvents.Error, (err) => {
this.logger.logDetailed(
"ERROR",
"Deepgram error received",
"TranscriptionService",
{ error: err }
);
this.emit("transcriptionerror", err);
});
});
}
send(payload) {
if (payload instanceof Buffer) {
this.pcmBuffer =
this.pcmBuffer.length === 0
? payload
: Buffer.concat([this.pcmBuffer, payload]);
} else {
this.logger.warn("TranscriptionService: Received non-Buffer data chunk.");
}
if (this.deepgramLive.getReadyState() === 1 && this.pcmBuffer.length > 0) {
this.sendBufferedData(this.pcmBuffer);
this.pcmBuffer = Buffer.alloc(0);
}
}
sendBufferedData(bufferedData) {
try {
this.logger.logDetailed(
"INFO",
"Sending buffered data to Deepgram",
"TranscriptionService",
{ bytes: bufferedData.length }
);
this.deepgramLive.send(bufferedData);
this.audioBuffer = [];
this.retryAttempts = 0;
} catch (error) {
this.logger.logDetailed(
"ERROR",
"Error sending buffered data",
"TranscriptionService",
{ error }
);
this.retryAttempts++;
if (this.retryAttempts <= MAX_RETRY_ATTEMPTS) {
setTimeout(() => {
this.sendBufferedData(bufferedData);
}, 1000);
} else {
this.logger.logDetailed(
"ERROR",
"Max retry attempts reached, discarding data",
"TranscriptionService"
);
this.audioBuffer = [];
this.retryAttempts = 0;
}
}
}
handleTranscript(transcription) {
if (!transcription.channel || !transcription.channel.alternatives?.[0]) {
this.logger.logDetailed(
"WARN",
"Invalid transcript format",
"TranscriptionService",
{ transcription }
);
return;
}
const text = transcription.channel.alternatives[0].transcript.trim();
if (!text) return;
const currentTime = Date.now();
const channelIndex = transcription.channel_index
? transcription.channel_index[0]
: 0;
const channel = channelIndex === 0 ? "customer" : "assistant";
this.logger.logDetailed(
"INFO",
"Received transcript",
"TranscriptionService",
{ channel, text }
);
if (transcription.is_final || transcription.speech_final) {
this.finalResult[channel] += ` ${text}`;
this.emitTranscription();
} else {
this.finalResult[channel] += ` ${text}`;
if (currentTime - this.lastTranscriptionTime >= DEBOUNCE_DELAY) {
this.logger.logDetailed(
"INFO",
`Emitting transcript after ${DEBOUNCE_DELAY_IN_SECS}s inactivity`,
"TranscriptionService"
);
this.emitTranscription();
}
}
this.lastTranscriptionTime = currentTime;
}
emitTranscription() {
for (const chan of ["customer", "assistant"]) {
if (this.finalResult[chan].trim()) {
const transcript = this.finalResult[chan].trim();
this.logger.logDetailed(
"INFO",
"Emitting transcription",
"TranscriptionService",
{ channel: chan, transcript }
);
this.emit("transcription", transcript, chan);
this.finalResult[chan] = "";
}
}
}
}
module.exports = TranscriptionService;
```
**server.js**
```js
const express = require("express");
const http = require("http");
const TranscriptionService = require("./transcriptionService");
const FileLogger = require("./fileLogger");
require("dotenv").config();
const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.get("/", (req, res) => {
res.send("Custom Transcriber Service is running");
});
const server = http.createServer(app);
const config = {
DEEPGRAM_API_KEY: process.env.DEEPGRAM_API_KEY,
PORT: process.env.PORT || 3001,
};
const logger = new FileLogger();
const transcriptionService = new TranscriptionService(config, logger);
transcriptionService.setupWebSocketServer = function (server) {
const WebSocketServer = require("ws").Server;
const wss = new WebSocketServer({ server, path: "/api/custom-transcriber" });
wss.on("connection", (ws) => {
logger.logDetailed(
"INFO",
"New WebSocket client connected on /api/custom-transcriber",
"Server"
);
ws.on("message", (data, isBinary) => {
if (!isBinary) {
try {
const msg = JSON.parse(data.toString());
if (msg.type === "start") {
logger.logDetailed(
"INFO",
"Received start message from client",
"Server",
{ sampleRate: msg.sampleRate, channels: msg.channels }
);
}
} catch (err) {
logger.error("JSON parse error", err, "Server");
}
} else {
transcriptionService.send(data);
}
});
ws.on("close", () => {
logger.logDetailed("INFO", "WebSocket client disconnected", "Server");
if (
transcriptionService.deepgramLive &&
transcriptionService.deepgramLive.getReadyState() === 1
) {
transcriptionService.deepgramLive.finish();
}
});
ws.on("error", (error) => {
logger.error("WebSocket error", error, "Server");
});
transcriptionService.on("transcription", (text, channel) => {
const response = {
type: "transcriber-response",
transcription: text,
channel,
};
ws.send(JSON.stringify(response));
logger.logDetailed("INFO", "Sent transcription to client", "Server", {
channel,
text,
});
});
transcriptionService.on("transcriptionerror", (err) => {
ws.send(
JSON.stringify({ type: "error", error: "Transcription service error" })
);
logger.error("Transcription service error", err, "Server");
});
});
};
transcriptionService.setupWebSocketServer(server);
server.listen(config.PORT, () => {
console.log(`Server is running on http://localhost:${config.PORT}`);
});
```
1. **Deploy your server:**
```bash
node server.js
```
2. **Expose your server:**
Use a tool like ngrok to expose your server via HTTPS/WSS.
3. **Initiate a call with Vapi:**
Use the following CURL command (update the placeholders with your actual values):
```bash
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"customer": {
"number": "CUSTOMER_PHONE_NUMBER"
},
"assistant": {
"transcriber": {
"provider": "custom-transcriber",
"server": {
"url": "wss://your-server.ngrok.io/api/custom-transcriber"
},
"secret": "your_optional_secret_value"
},
"firstMessage": "Hello! I am using a custom transcriber with Deepgram."
},
"name": "CustomTranscriberTest"
}'
```
**Expected behavior:**
* Vapi connects via WebSocket to your custom transcriber at `/api/custom-transcriber`.
* The `"start"` message initializes the Deepgram session.
* PCM audio data is forwarded to Deepgram.
* Deepgram returns transcript events, which are processed with channel detection and debouncing.
* The final transcript is sent back as a JSON message:
```json
{
"type": "transcriber-response",
"transcription": "The transcribed text",
"channel": "customer" // or "assistant"
}
```
## Notes and limitations
* **Streaming support requirement:**\
The custom transcriber must support streaming. Vapi sends continuous audio data over the WebSocket, and your server must handle this stream in real time.
* **Secret header:**\
The custom transcriber configuration accepts an optional field called **`secret`**. When set, Vapi will send this value with every request as an HTTP header named `x-vapi-secret`. This can also be configured via a headers field.
* **Buffering:**\
The solution buffers PCM audio and performs simple validation (e.g. ensuring stereo PCM data length is a multiple of 4). If the audio data is malformed, it is trimmed to a valid length.
* **Channel detection:**\
Transcript events from Deepgram include a `channel_index` array. The service uses the first element to determine whether the transcript is from the customer (`0`) or the assistant (`1`). Ensure Deepgram's response format remains consistent with this logic.
***
## Conclusion
Using a custom transcriber with Vapi gives you the flexibility to integrate any transcription service into your call flows. This guide walked you through the setup, usage, and testing of a solution that streams real-time audio, processes transcripts with multi‑channel detection, and returns formatted responses back to Vapi. Follow the steps above and use the provided code examples to build your custom transcriber solution.
# Introduction to Tools
> Extend your assistant's capabilities with powerful function calling tools.
[**Tools**](/api-reference/tools/create) allow your assistant to take actions beyond just conversation. They enable your assistant to perform tasks like transferring calls, accessing external data, or triggering actions in your application. Tools can be either built-in default tools provided by Vapi or custom tools that you create.
There are three types of tools available:
1. **Default Tools**: Built-in functions provided by Vapi for common operations like call transfers and control.
2. **Custom Tools**: Your own functions that can be called by the assistant to interact with your systems.
3. **Integration Tools**: Pre-built integrations with platforms like [Make](https://www.make.com/en/integrations/vapi) and GoHighLevel (GHL) that let you trigger automated workflows via voice.
Tools are configured as part of your assistant's model configuration. You can find the complete API reference [here](/api-reference/tools/create-tool).
## Available Tools
Built-in tools for call control, transfers, and basic operations
Create your own tools to extend assistant capabilities
Import Make scenarios and GHL workflows as voice-activated tools
## Integration Tools
With Make and GHL integrations, you can:
* Import existing Make scenarios and GHL workflows directly into Vapi
* Trigger automated workflows using voice commands
* Connect your voice AI to hundreds of apps and services
* Automate complex business processes through voice interaction
Common use cases include:
* Booking appointments via voice
* Updating CRM records during calls
* Triggering email or SMS follow-ups
* Processing orders and payments
* Managing customer support tickets
## Key Features
Assistants can trigger functions based on conversation context
Tools can run synchronously or asynchronously
Connect tools to your backend via webhooks
Built-in error handling and fallback options
## Learn More
Learn how to import and use Make scenarios and GHL workflows as voice-activated tools
Get help with tool integrations from our community
# Default Tools
> Adding Transfer Call, End Call, Dial Keypad, and API Request capabilities to your assistants.
Vapi voice assistants are given additional functions: `transferCall`, `endCall`, `sms`, `dtmf` (to dial a keypad with [DTMF](https://en.wikipedia.org/wiki/DTMF)), and `apiRequest`. These functions can be used to transfer calls, hang up calls, send SMS messages, enter digits on the keypad, and integrate business logic with your existing APIs.
To add Default Tools to your agent, you need to add them in the `tools` array of your assistant. You can do this in your api request, or by creating a new tool in the dashboard tools page, and assigning it to your assistant.
#### Transfer Call
This function is provided when `transferCall` is included in the assistant's list of available tools (see configuration options [here](/api-reference/assistants/create#request.body.model.openai.tools.transferCall)). This function can be used to transfer the call to any of the `destinations` defined in the tool configuration (see details on destination options [here](/api-reference/assistants/create#request.body.model.openai.tools.transferCall.destinations)).
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are an assistant at a law firm. When the user asks to be transferred, use the transferCall function."
}
],
"tools": [
{
"type": "transferCall",
"destinations" : {
{
"type": "number",
"number": "+16054440129"
}
}
}
]
}
}
```
#### End Call
This function is provided when `endCall` is included in the assistant's list of available tools (see configuration options [here](/api-reference/assistants/create#request.body.model.openai.tools.endCall)). The assistant can use this function to end the call.
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are an assistant at a law firm. If the user is being mean, use the endCall function."
}
],
"tools": [
{
"type": "endCall"
}
]
}
}
```
#### Send Text
This function is provided when `sms` is included in the assistant's list of available tool (see configuration options [here](/api-reference/assistants/create#request.body.model.openai.tools.sms)). The assistant can use this function to send SMS messages using a configured Twilio account.
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are an assistant. When the user asks you to send a text message, use the sms function."
}
],
"tools": [
{
"type": "sms",
"metadata": {
"from": "+15551234567"
}
}
]
}
}
```
#### Dial Keypad (DTMF)
This function is provided when `dtmf` is included in the assistant's list of available tools (see configuration options [here](/api-reference/assistants/create#request.body.model.openai.tools.dtmf)). The assistant will be able to enter digits on the keypad.
Useful for IVR navigation or data entry.
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are an assistant at a law firm. When you hit a menu, use the dtmf function to enter the digits."
}
],
"tools": [
{
"type": "dtmf"
}
]
}
}
```
There are three methods for sending DTMF in a phone call:
1. **In-band**: tones are transmitted as part of the regular audio stream. This is the simplest method, but it can suffer from quality issues if the audio stream is compressed or degraded.
2. **Out-of-band via RFC 2833**: tones are transmitted separately from the audio stream, within RTP (Real-Time Protocol) packets. It's typically more reliable than in-band DTMF, particularly for VoIP applications where the audio stream might be compressed. RFC 2833 is the standard that initially defined this method. It is now replaced by RFC 4733 but this method is still referred by RFC 2833.
3. **Out-of-band via SIP INFO messages**: tones are sent as separate SIP INFO messages. While this can be more reliable than in-band DTMF, it's not as widely supported as the RFC 2833 method.
Vapi's DTMF tool integrates with telephony provider APIs to send DTMF tones using the out-of-band RFC 2833 method. This approach is widely supported and more reliable for transmitting the signals, especially in VoIP environments.
Note, the tool's effectiveness depends on the IVR system's configuration and their capturing method. If you are running into issues, try different telephony providers or have your assistant say the options out loud if available.
#### API Request
This tool allows your assistant to make HTTP requests to any external API endpoint during conversations. This tool fills the gap between Vapi and your existing business logic, bringing your own endpoints into the conversation flow.
See configuration options [here](/api-reference/tools/create).
##### Dynamic Variables with LiquidJS
Use **LiquidJS syntax** to reference conversation variables and user data in your URLs, headers, and request bodies. This allows your API requests to adapt dynamically based on the conversation context.
##### Basic Examples
**GET Request Example**
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You help users check their order status. When they provide an order number, use the checkOrderStatus function."
}
],
"tools": [
{
"type": "apiRequest",
"function": {
"name": "api_request_tool"
},
"name": "checkOrderStatus",
"url": "https://api.yourcompany.com/orders/{{orderNumber}}",
"method": "GET",
"body": {
"type": "object",
"properties": {
"orderNumber": {
"description": "The user's order number",
"type": "string"
}
},
"required": ["orderNumber"]
}
}
]
}
}
```
**POST Request Example**
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You help users book appointments. When they want to schedule, use the bookAppointment function."
}
],
"tools": [
{
"type": "apiRequest",
"function": {
"name": "api_request_tool"
},
"name": "bookAppointment",
"url": "https://api.yourcompany.com/appointments",
"method": "POST",
"headers": {
"type": "object",
"properties": {
"x-api-key": {
"type": "string",
"value": "123456789"
}
}
},
"body": {
"type": "object",
"properties": {
"date": {
"description": "The date of the appointment",
"type": "string"
},
"customerName": {
"description": "The name of the customer",
"type": "string"
},
"customerPhoneNumber": {
"description": "The phone number of the customer",
"type": "string"
}
},
"required": [
"date",
"customerName",
"customerPhoneNumber"
]
}
}
]
}
}
```
##### Advanced Configuration
**With Retry Logic**
```json
{
"type": "apiRequest",
"function": {
"name": "api_request_tool"
},
"name": "checkOrderStatus",
"url": "https://api.yourcompany.com/orders/{{orderNumber}}",
"method": "GET",
"body": {
"type": "object",
"properties": {
"orderNumber": {
"description": "The user's order number",
"type": "string"
}
},
"required": [
"orderNumber"
]
},
"backoffPlan": {
"type": "exponential",
"maxRetries": 3,
"baseDelaySeconds": 1
},
"timeoutSeconds": 45
}
```
### Custom Functions
The
**Custom Functions**
feature is being deprecated in favor of
[Tools](/tools-calling)
. Please refer to the
**Tools**
section instead. We're working on a solution to migrate your existing functions over to make this a seamless transtion.
In addition to the predefined functions, you can also define custom functions. These functions are similar to OpenAI functions and your chosen LLM will trigger them as needed based on your instructions.
The functions array in the assistant definition allows you to define custom functions that the assistant can call during a conversation. Each function is an object with the following properties:
* `name`: The name of the function. It must be a string containing a-z, A-Z, 0-9, underscores, or dashes, with a maximum length of 64.
* `description`: A brief description of what the function does. This is used by the AI to decide when and how to call the function.
* `parameters`: An object that describes the parameters the function accepts. The type property should be "object", and the properties property should be an object where each key is a parameter name and each value is an object describing the type and purpose of the parameter.
Here's an example of a function definition:
```json
{
"functions": [
{
"name": "bookAppointment",
"description": "Used to book the appointment.",
"parameters": {
"type": "object",
"properties": {
"datetime": {
"type": "string",
"description": "The date and time of the appointment in ISO format."
}
}
}
}
]
}
```
In this example, the bookAppointment function accepts one parameter, `datetime`, which is a string representing the date and time of the appointment in ISO format.
In addition to defining custom functions, you can specify a `serverUrl` where Vapi will send the function call information. This URL can be configured at the account level or at the assistant level.
At the account level, the `serverUrl` is set in the Vapi Dashboard. All assistants under the account will use this URL by default for function calls.
At the assistant level, the `serverUrl` can be specified in the assistant configuration when creating or updating an assistant. This allows different assistants to use different URLs for function calls. If a `serverUrl` is specified at the assistant level, it will override the account-level Server URL.
If the `serverUrl` is not defined either at the account level or the assistant level, the function call will simply be added to the chat history. This can be particularly useful when you want a function call to trigger an action on the frontend.
For instance, the frontend can listen for specific function calls in the chat history and respond by updating the user interface or performing other actions. This allows for a dynamic and interactive user experience, where the frontend can react to changes in the conversation in real time.
# Custom Tools
> Learn how to create and configure Custom Tools for use by your Vapi assistants.
This guide shows you how to create custom tools for your Vapi assistants. We recommend using the Vapi dashboard's dedicated Tools section, which provides a visual interface for creating and managing tools that can be reused across multiple assistants. For advanced users, API configuration is also available.
## Creating Tools in the Dashboard (Recommended)
### Step 1: Navigate to the Tools Section
1. Open your [Vapi Dashboard](https://dashboard.vapi.ai)
2. Click **Tools** in the left sidebar
3. Click **Create Tool** to start building your custom tool
### Step 2: Configure Your Tool
The dashboard provides a user-friendly interface to configure your tool:
1. **Tool Type**: Select "Function" for custom API integrations
2. **Tool Name**: Give your tool a descriptive name (e.g., "Weather Lookup")
3. **Description**: Explain what your tool does
4. **Tool Configuration**:
* **Tool Name**: The identifier for your function (e.g., `get_weather`)
* **Parameters**: Define the input parameters your function expects
* **Server URL**: The endpoint where your function is hosted
### Step 3: Configure Messages
Set up the messages your assistant will speak during tool execution. For example, if you want custom messages you can add something like this:
* **Request Start**: "Checking the weather forecast. Please wait..."
* **Request Complete**: "The weather information has been retrieved."
* **Request Failed**: "I couldn't get the weather information right now."
* **Request Delayed**: "There's a slight delay with the weather service."
### Step 4: Advanced Settings
Configure additional options:
* **Async Mode**: Enable if the tool should run asynchronously
* **Timeout Settings**: Set how long to wait for responses
* **Error Handling**: Define fallback behaviors
## Example: Creating a Weather Tool
Let's walk through creating a weather lookup tool:
### Dashboard Configuration
1. **Tool Name**: "Weather Lookup"
2. **Description**: "Retrieves current weather information for any location"
3. **Function Name**: `get_weather`
4. **Parameters**:
* `location` (string, required): "The city or location to get weather for"
5. **Server URL**: `https://api.openweathermap.org/data/2.5/weather`
This example uses OpenWeatherMap's free API. You'll need to sign up at [openweathermap.org](https://openweathermap.org/api) to get a free API key and add it as a query parameter: `?appid=YOUR_API_KEY&q={location}`
### Messages Configuration
* **Request Start**: "Let me check the current weather for you..."
* **Request Complete**: "Here's the weather information you requested."
* **Request Failed**: "I'm having trouble accessing weather data right now."
## Using Tools in Assistants
Once created, your tools can be easily added to any assistant:
### In the Dashboard
1. Go to **Assistants** → Select your assistant
2. Navigate to the **Tools** tab
3. Click **Add Tool** and select your custom tool from the dropdown
4. Save your assistant configuration
### In Workflows
Tools created in the Tools section are automatically available in the workflow builder:
1. Add a **Tool Node** to your workflow
2. Select your custom tool from the **Tool** dropdown
3. Configure any node-specific settings
### Using the Vapi CLI
Manage your custom tools directly from the terminal:
```bash
# List all tools
vapi tool list
# Get tool details
vapi tool get
# Create a new tool (interactive)
vapi tool create
# Test a tool with sample data
vapi tool test
# Delete a tool
vapi tool delete
```
Use the Vapi CLI to forward tool calls to your local server:
```bash
# Terminal 1: Create tunnel (e.g., with ngrok)
ngrok http 4242
# Terminal 2: Forward events
vapi listen --forward-to localhost:3000/tools/webhook
```
`vapi listen` is a local forwarder that requires a separate tunneling service. Configure your tool's server URL to use the tunnel's public URL for testing. [Learn more →](/cli/webhook)
## Alternative: API Configuration
For advanced users who prefer programmatic control, you can also create and manage tools via the Vapi API:
### Creating Tools via API
```bash
curl --location 'https://api.vapi.ai/tool' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
"type": "function",
"function": {
"name": "get_weather",
"description": "Retrieves current weather information for any location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city or location to get weather for"
}
},
"required": ["location"]
}
},
"server": {
"url": "https://api.openweathermap.org/data/2.5/weather"
}
}'
```
### Adding Tools to Assistants via API
```bash
curl --location --request PATCH 'https://api.vapi.ai/assistant/ASSISTANT_ID' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"model": {
"provider": "openai",
"model": "gpt-4o",
"toolIds": ["your-tool-id-here"]
}
}'
```
## Request Format: Understanding the Tool Call Request
When your server receives a tool call request from Vapi, it will be in the following format:
```json
{
"message": {
"timestamp": 1678901234567,
"type": "tool-calls",
"toolCallList": [
{
"id": "toolu_01DTPAzUm5Gk3zxrpJ969oMF",
"name": "get_weather",
"arguments": {
"location": "San Francisco"
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string"
}
}
},
"description": "Retrieves the current weather for a specified location"
},
"server": {
"url": "https://api.openweathermap.org/data/2.5/weather"
},
"messages": [],
"toolCall": {
"id": "toolu_01DTPAzUm5Gk3zxrpJ969oMF",
"type": "function",
"function": {
"name": "get_weather",
"parameters": {
"location": "San Francisco"
}
}
}
],
"artifact": {
"messages": []
},
"assistant": {
"name": "Weather Assistant",
"description": "An assistant that provides weather information",
"model":{},
"voice":{},
"artifactPlans":{},
"startSpeakingPlan":{}
},
"call": {
"id": "call-uuid",
"orgId": "org-uuid",
"type": "webCall",
"assistant": {}
}
}
}
```
For the complete API reference, see [ServerMessageToolCalls Type Definition](https://github.com/VapiAI/server-sdk-typescript/blob/main/src/api/types/ServerMessageToolCalls.ts#L7).
## Server Response Format: Providing Results and Context
When your Vapi assistant calls a tool (via the server URL you configured), your server will receive an HTTP request containing information about the tool call. Upon processing the request and executing the desired function, your server needs to send back a response in the following JSON format:
```json
{
"results": [
{
"toolCallId": "X",
"result": "Y"
}
]
}
```
**Breaking down the components:**
* **toolCallId (X):** This is a unique identifier included in the initial request from Vapi. It allows the assistant to match the response with the corresponding tool call, ensuring accurate processing and context preservation.
* **result (Y):** This field holds the actual output or result of your tool's execution. The format and content of "result" will vary depending on the specific function of your tool. It could be a string, a number, an object, an array, or any other data structure that is relevant to the tool's purpose.
**Example:**
Let's revisit the weather tool example from before. If the tool successfully retrieves the weather for a given location, the server response might look like this:
```json
{
"results": [
{
"toolCallId": "call_VaJOd8ZeZgWCEHDYomyCPfwN",
"result": "San Francisco's weather today is 62°C, partly cloudy."
}
]
}
```
**Some Key Points:**
* Pay attention to the required parameters and response format of your functions.
* Ensure your server is accessible and can handle the incoming requests from Vapi.
* Make sure to add "Tools Calls" in both the Server and Client messages and remove the function calling from it.
By following these guidelines and adapting the sample payload, you can easily configure a variety of tools to expand your Vapi assistant's capabilities and provide a richer, more interactive user experience.
**Video Tutorial:**
# Custom tools troubleshooting
> Resolve common issues with custom tool integrations
## Overview
Troubleshoot and fix common issues with custom tool integrations in your Vapi assistants.
**In this guide, you'll learn to:**
* Diagnose why tools aren't triggering
* Fix response format errors
* Resolve parameter and token issues
* Handle multiple tool scenarios
## Quick diagnosis
Start with the most common issue for your symptoms:
**Symptoms:** Assistant doesn't call your tool Check prompting and schema
setup
**Symptoms:** Logs show "no result returned" Fix response format issues
**Symptoms:** Tool returns data but assistant ignores it Resolve parsing and
format problems
**Symptoms:** Tool parameters or responses truncated Increase token limits
## Tool won't trigger
Your assistant doesn't call the tool even when it should.
### Check your assistant prompting
`txt title="❌ Too vague" Handle weather requests ` `txt title="✅
Specific and clear" When user asks for weather, use weather_tool with city
parameter `
Use the exact tool name in your assistant instructions. If your tool is named
`get_weather`, reference `get_weather` in prompts, not `weather_tool`.
### Verify required parameters
Check that your tool schema includes all required parameters:
```json title="Tool schema"
{
"name": "get_weather",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name for weather lookup"
}
},
"required": ["city"] // Must be array of required parameter names
}
}
```
### Enable schema validation
Add `strict: true` to catch validation errors early:
```json title="Tool configuration" {7}
{
"name": "get_weather",
"description": "Get current weather for a city",
"parameters": {
// ... your parameters
},
"strict": true,
"maxTokens": 500
}
```
Check your call logs for "Schema validation errors" to identify parameter
issues.
## No result returned error
Logs show "ok, no result returned" or similar messages.
### Use the correct response format
Your webhook **must** return this exact JSON structure:
```json title="✅ Success response"
{
"results": [
{
"toolCallId": "call_123",
"result": "Your response as single-line string"
}
]
}
```
```json title="✅ Error response"
{
"results": [
{
"toolCallId": "call_123",
"error": "Error message as single-line string"
}
]
}
```
### Common format mistakes
**Always return HTTP 200**, even for errors. Any other status code is ignored completely.
```json
// Return this with HTTP 200
{
"results": [
{
"toolCallId": "call_123",
"error": "Something went wrong"
}
]
}
```
Use single-line strings only. Line breaks cause parsing errors.
```json title="❌ Has line breaks"
{
"result": "Line 1\nLine 2\nLine 3"
}
```
```json title="✅ Single line"
{
"result": "Line 1, Line 2, Line 3"
}
```
The response must have the `results` array structure. Individual result objects won't work.
The `toolCallId` in your response must exactly match the ID from the request.
Both `result` and `error` fields must be strings, not objects or arrays.
## Response ignored
Tool returns data but the assistant doesn't use it in conversation.
### Fix line breaks and formatting
```json title="❌ Line breaks cause parsing errors"
{
"results": [
{
"toolCallId": "call_123",
"result": "Temperature: 72°F\nCondition: Sunny\nHumidity: 45%"
}
]
}
```
```json title="✅ Single-line string works"
{
"results": [
{
"toolCallId": "call_123",
"result": "Temperature: 72°F, Condition: Sunny, Humidity: 45%"
}
]
}
```
### Verify HTTP status and JSON structure
Ensure your webhook returns HTTP 200. Any other status code causes the
response to be ignored.
{" "}
Use a JSON validator to ensure your response structure is valid.
For multiple tools, return results in the same order as calls were
triggered, with matching `toolCallId` values.
## Token truncation
Tool parameters or responses are getting cut off.
### Increase token limits
The default token limit is only 100. Increase it for complex tools:
```json title="Tool configuration" {7}
{
"name": "complex_tool",
"description": "Tool that needs more tokens",
"parameters": {
// ... your parameters
},
"maxTokens": 500 // Increase from default 100
}
```
Look for "Token truncation warnings" in your call logs to identify when this
occurs.
## Multiple tools scenarios
Some tools in parallel calls fail or return wrong results.
### Handle multiple tool responses
Return all results in the same order as the calls were triggered:
```json title="Multiple tool response"
{
"results": [
{
"toolCallId": "call_1",
"result": "First tool success"
},
{
"toolCallId": "call_2",
"error": "Second tool failed"
},
{
"toolCallId": "call_3",
"result": "Third tool success"
}
]
}
```
Use HTTP 200 for the entire response, even if some individual tools error.
Handle errors within the `results` array using the `error` field.
## Async vs sync behavior
Tool behavior doesn't match your expectations.
**Configuration:** `"async": false` (default)
**Behavior:**
* Wait for webhook response before resolving
* Tool call resolution depends on your response
* Use for immediate operations
```json
{
"name": "sync_tool",
"async": false, // or omit (default)
// ... other config
}
```
**Configuration:** `"async": true`
**Behavior:**
* Tool call marked as resolved immediately
* Don't wait for actual processing
* Use for long-running operations
```json
{
"name": "async_tool",
"async": true,
// ... other config
}
```
Most tools should use sync behavior unless you specifically need async
processing for long-running operations.
## Reference: Required formats
### Response format template
```json title="Success response"
{
"results": [
{
"toolCallId": "call_123",
"result": "Single-line string response"
}
]
}
```
```json title="Error response"
{
"results": [
{
"toolCallId": "call_123",
"error": "Single-line error message"
}
]
}
```
### Tool schema template
```json title="Complete tool configuration"
{
"name": "tool_name",
"description": "Clear description of what the tool does",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["param1"]
},
"strict": true,
"maxTokens": 500,
"async": false
}
```
### Critical response rules
**Always return HTTP 200**
\- Even for errors
**Use single-line strings**
\- No
`\n`
line breaks
**Match tool call IDs exactly**
\- From request to response
**Include results array**
\- Required structure
**String types only**
\- For result/error values
## Debugging with call logs
Look for these key error messages in your call logs:
| Error Message | What It Means | How to Fix |
| --------------------------- | --------------------------- | -------------------------- |
| "ok, no result returned" | Wrong response format | Use correct JSON structure |
| "Tool call ID mismatches" | toolCallId doesn't match | Ensure exact ID match |
| "HTTP errors" | Webhook not returning 200 | Return HTTP 200 always |
| "Schema validation errors" | Missing required parameters | Check required array |
| "Token truncation warnings" | Need more tokens | Increase maxTokens |
| "Response parsing errors" | Malformed JSON/line breaks | Fix JSON format |
# Google Calendar Integration
> Connect your assistant to Google Calendar for seamless appointment scheduling and availability checking.
The Google Calendar integration allows your Vapi assistant to interact with Google Calendar in two ways:
1. Create calendar events through voice commands
2. Check calendar availability for scheduling
This enables your assistant to schedule appointments, meetings, and other calendar events directly during phone calls, as well as check when you're available for meetings.
## Prerequisites
Before you can use the Google Calendar integration, you need to:
1. Have a Google Calendar account
2. Have access to the Vapi Dashboard
3. Have an assistant created in Vapi
## Setup Steps
### 1. Connect Google Calendar Account
First, you need to connect your Google Calendar account to Vapi:
1. Navigate to the Vapi Dashboard
2. Go to **Providers Keys** > **Tools Provider** > **Google Calendar**
3. Click the **Connect** button
4. A Google authorization popup will appear
5. Follow the prompts to authorize Vapi to access your Google Calendar
The authorization process will request access to your Google Calendar to create events and check availability.
### 2. Create Calendar Tools
After connecting your Google Calendar account, create the tools:
1. Go to **Dashboard** > **Tools** page
2. Click the **Create Tool** button
3. Select **Google Calendar** from the available options
4. Choose which tool(s) you want to create:
* Google Calendar Create Event Tool
* Google Calendar Check Availability Tool
5. For each tool, provide a name and description explaining when it should be invoked
The description field is crucial as it helps the AI model understand when and how to use each tool. Be specific about the scenarios and conditions when each tool should be invoked.
### 3. Add Tools to Assistant
Now, add your chosen calendar tool(s) to your assistant:
1. Navigate to **Dashboard** > **Assistants** page
2. Select your assistant
3. Go to the **Tools** tab
4. In the tools dropdown, select the calendar tool(s) you want to use
5. Click **Publish** to save your changes
## Tool Configurations
### Google Calendar Create Event Tool
This tool uses the following fields to create events:
* `summary`: The title or description of the calendar event
* `startDateTime`: The start date and time of the event
* `endDateTime`: The end date and time of the event
* `attendees`: A list of email addresses for people to invite to the event
* `timeZone`: The timezone for the event, defaults to UTC
* `calendarId`: The calendar ID to create the event in, defaults to the primary calendar
### Google Calendar Check Availability Tool
This tool uses the following fields to check availability:
* `startDateTime`: The start of the time range to check
* `endDateTime`: The end of the time range to check
* `timeZone`: The timezone for the availability check, defaults to UTC
* `calendarId`: The calendar ID to check availability in, defaults to the primary calendar
All datetime fields should be provided in ISO 8601 format.
## Example Usage
Here's how the tools can be used in your assistant's configuration:
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a scheduling assistant. When users want to schedule an appointment, first check their availability using the Check Availability tool, then use the Create Event tool to schedule the event if they're available.\n\n- Gather date and time range to check availability.\n- To book an appointment, gather the purpose of the appointment, ex: general checkup, dental cleaning and etc.\n\nNotes\n- Use the purpose as summary for booking appointment.\n- Current date: {{now}}"
}
],
"tools": [
{
"type": "google.calendar.availability.check",
"name": "checkAvailability",
"description": "Use this tool to check calendar availability."
},
{
"type": "google.calendar.event.create",
"name": "scheduleAppointment",
"description": "Use this tool to schedule appointments and create calendar events. Notes: - All appointments are 30 mins. \n- Current date/time: {{now}}"
}
]
}
}
```
## Best Practices
1. **Clear Instructions**: Provide clear instructions in your assistant's system message about when to use each calendar tool
2. **Error Handling**: Include fallback responses for cases where either calendar tool fails
3. **Time Zone Awareness**: Always specify the correct timezone for events and availability checks
4. **Event Details**: Ensure all required fields are properly filled when creating events
5. **Availability Flow**: Check availability before attempting to schedule events to avoid conflicts
Join our Discord community for support with Google Calendar integration
View the complete API documentation for tools
# Google Sheets Integration
> Connect your assistant to Google Sheets for seamless data entry.
The Google Sheets integration allows your Vapi assistant to interact with Google Sheets in a simple way:
1. Add new rows to existing Google Sheets
This enables your assistant to record information and add data to spreadsheets directly during phone calls.
The Google Sheets integration currently only supports adding new rows to spreadsheets. It does not support reading from or modifying existing data in the spreadsheet.
## Prerequisites
Before you can use the Google Sheets integration, you need to:
1. Have a Google Sheets account
2. Have access to the Vapi Dashboard
3. Have an assistant created in Vapi
4. Have a Google Sheet created and ready to receive data
## Setup Steps
### 1. Connect Google Sheets Account
First, you need to connect your Google Sheets account to Vapi:
1. Navigate to the Vapi Dashboard
2. Go to **Providers Keys** > **Tools Provider** > **Google Sheets**
3. Click the **Connect** button
4. A Google authorization popup will appear
5. Follow the prompts to authorize Vapi to access your Google Sheets
The authorization process will request access to your Google Sheets.
### 2. Create and Configure Sheets Tool
After connecting your Google Sheets account, create and configure the tool:
1. Go to **Dashboard** > **Tools** page
2. Click the **Create Tool** button
3. Select **Google Sheets** from the available options
4. Choose the Google Sheets Add Row Tool
5. Provide a name and description explaining when it should be invoked
6. Configure the tool with the following required fields:
* `spreadsheetId`: The ID of your Google Sheet
* `range`: The sheet name or range (e.g., "Sheet1" or "Sheet1!A:Z")
To find your spreadsheet ID:
1. Open your Google Sheet in a browser
2. Look at the URL: `https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit`
3. Copy the SPREADSHEET\_ID portion (it's a long string of letters, numbers, and special characters)
The description field is crucial as it helps the AI model understand when and how to use the tool. Be specific about the scenarios and conditions when the tool should be invoked.
### 3. Add Tool to Assistant
Now, add the Google Sheets tool to your assistant:
1. Navigate to **Dashboard** > **Assistants** page
2. Select your assistant
3. Go to the **Tools** tab
4. In the tools dropdown, select the Google Sheets tool
5. Click **Publish** to save your changes
## Tool Configuration
### Google Sheets Add Row Tool
This tool uses the following fields to add data to your spreadsheet:
* `spreadsheetId`: The ID of your Google Sheet (found in the sheet's URL)
* `range`: The range where the data should be added (e.g., "Sheet1" or "Sheet1!A:Z")
* `values`: An array of values to be added as a new row
The range field can be specified in two ways:
1. Just the sheet name (e.g., "Sheet1") - This will append to the next empty row
2. Sheet name with range (e.g., "Sheet1!A:Z") - This will append to the specified range
## Example Usage
Here's how the tool can be used in your assistant's configuration:
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a customer feedback assistant. After each customer service call, collect feedback using the following process:\n\n1. Ask the customer if they would like to provide feedback\n2. If yes, ask for their rating (1-5 stars)\n3. Ask for specific comments about their experience\n4. Ask for any suggestions for improvement\n5. Confirm the feedback before adding it to the spreadsheet\n\nUse the Add Row tool to record the feedback with the following columns:\n- Timestamp\n- Rating (1-5)\n- Comments\n- Suggestions\n\nAlways be polite and thank the customer for their feedback."
}
],
"tools": [
{
"type": "google.sheets.row.append",
"name": "addFeedback",
"description": "Use this tool to add customer feedback to the feedback spreadsheet. Collect all required information (rating, comments, suggestions) before adding the row."
}
]
}
}
```
## Best Practices
1. **Data Validation**: Ensure all data is properly formatted before adding to the spreadsheet
2. **Error Handling**: Include fallback responses for cases where the tool fails
3. **User Confirmation**: Always confirm with the user before adding data to the spreadsheet
4. **Sheet Structure**: Be aware of the spreadsheet's structure and column requirements
Join our Discord community for support with Google Sheets integration
View the complete API documentation for tools
# Slack Integration
> Connect your assistant to Slack for seamless message sending.
The Slack integration allows your Vapi assistant to send messages to a pre-configured Slack channel during phone calls. This enables your assistant to notify team members, send updates, or share information directly through Slack.
## Prerequisites
Before you can use the Slack integration, you need to:
1. Have a Slack workspace
2. Have access to the Vapi Dashboard
3. Have an assistant created in Vapi
4. Have a Slack channel created where messages will be sent
## Setup Steps
### 1. Connect Slack Account
First, you need to connect your Slack workspace to Vapi:
1. Navigate to the Vapi Dashboard
2. Go to **Providers Keys** > **Tools Provider** > **Slack**
3. Click the **Connect** button
4. A Slack authorization popup will appear
5. Follow the prompts to authorize Vapi to access your Slack workspace
The authorization process will request access to send messages to your Slack workspace.
### 2. Create Slack Tool
After connecting your Slack workspace, create the tool:
1. Go to **Dashboard** > **Tools** page
2. Click the **Create Tool** button
3. Select **Slack** from the available options
4. Choose the Slack Send Message Tool
5. Provide a name and description explaining when it should be invoked
6. In the description field, specify the Slack channel where messages should be sent (e.g., "Send urgent notifications to the #customer-support channel")
The description field is crucial as it helps the AI model understand when and how to use the tool, and also specifies which channel to send messages to. Be specific about the scenarios, conditions, and target channel when the tool should be invoked.
### 3. Add Tool to Assistant
Now, add the Slack tool to your assistant:
1. Navigate to **Dashboard** > **Assistants** page
2. Select your assistant
3. Go to the **Functions** tab
4. In the tools dropdown, select the Slack tool
5. Click **Publish** to save your changes
## Tool Configuration
### Slack Send Message Tool
This tool sends messages to Slack channels based on the configuration specified in the tool's description:
* The target channel is specified in the tool's description field
* The message content is dynamically generated by the AI based on the conversation context
The channel name should be specified in the description in the format "#channel-name". Make sure the bot has been added to the channel before sending messages.
## Example Usage
Here's how the tool can be used in your assistant's configuration:
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a customer service assistant. When a customer requests a callback or needs urgent attention, use the Slack tool to notify the support team. Always be professional and concise in your Slack messages."
}
],
"tools": [
{
"type": "slack.message.send",
"name": "notifySupport",
"description": "Send urgent notifications to the #customer-support channel when a customer needs immediate attention or requests a callback. Include customer name, phone number, reason for callback, and any time constraints."
}
]
}
}
```
## Best Practices
1. **Channel Selection**: Always verify the correct channel name before sending messages
2. **Message Formatting**: Use clear and concise language in your Slack messages
3. **Error Handling**: Include fallback responses for cases where the tool fails
4. **User Confirmation**: Always confirm with the user before sending notifications to Slack
5. **Channel Access**: Ensure the Slack bot has been added to the target channel
Join our Discord community for support with Slack integration
View the complete API documentation for tools
# GoHighLevel Integration
> Connect your assistant to GoHighLevel for seamless appointment scheduling, contact creation, and availability checking.
The GoHighLevel integration empowers your Vapi voice agents to directly interact with your clients' GoHighLevel calendars. Your agents can use a suite of tools to manage the appointment lifecycle: check if a contact already exists using the **Get Contact** tool, create new leads or clients with the **Create Contact** tool, query specific GHL calendars for open slots via the **Check Availability** tool, and secure appointments associated with a contact using the **Create Event** tool. This enables your voice agent to handle the entire booking process seamlessly within the GHL calendar that your agency or client already uses.
## Prerequisites
Before you can use the GoHighLevel integration, you need to:
1. Have a GoHighLevel account.
2. Have a calendar in GoHighLevel to which you have permission to create and edit events.
3. Have access to the Vapi Dashboard.
## Setup Steps
### 1. Connect GoHighLevel Account
First, you need to connect your GoHighLevel account to Vapi:
1. Navigate to the Vapi Dashboard.
2. Go to **Providers Keys** > **Tools Provider** > **GoHighLevel**.
3. Click the **Connect** button.
4. A GoHighLevel authorization popup will appear.
5. Follow the prompts to authorize Vapi to access your GoHighLevel account.
The authorization process will request access to your GoHighLevel account to
manage contacts, calendars, and appointments.
### 2. Create GoHighLevel Tools
After connecting your GoHighLevel account, create the tools:
1. Go to **Dashboard** > **Tools** page.
2. Click the **Create Tool** button.
3. Select **GoHighLevel** from the available options.
4. Choose which tool(s) you want to create (e.g., Get Contact, Create Contact, Check Availability, Create Event).
5. For each tool, provide a clear and descriptive name. Adding a description is optional. If you leave it blank, Vapi will automatically generate a default description that explains the tool's purpose and includes the current date, formatted using the timezone you specify in the tool's metadata.
6. For the **Check Availability** and **Create Event** tools, ensure you provide a valid `calendarId`. You can find the `calendarId` for each of your calendars in GoHighLevel by navigating to **Settings** > **Calendars**. Each calendar listed will display its unique ID.
When creating an event in GoHighLevel, a `contactId` is required. Therefore,
if you plan to use the **Create Event** tool, you **must** also add the **Get
Contact** and **Create Contact** tools. This allows the assistant to first
retrieve an existing contact's ID or create a new contact, and then use that
ID to schedule the event.
### 3. Add Tools to Assistant
Now, add your chosen GoHighLevel tool(s) to your assistant. For an example scenario where you want your assistant to book appointments, including finding a suitable time and managing contact information, you would add all four tools: Get Contact, Create Contact, Check Availability, and Create Event.
1. Navigate to **Dashboard** > **Assistants** page.
2. Select your assistant.
3. Go to the **Tools** tab.
4. In the tools dropdown, select the GoHighLevel tool(s) you want to use.
5. Click **Publish** to save your changes.
### 4. Configure Assistant System Prompt
After adding the GoHighLevel tools to your assistant, it's crucial to provide a clear system prompt. This prompt guides the assistant on how and when to use each tool to achieve the desired workflow. For a typical appointment booking scenario, your system prompt instructs the AI on the sequence of operations and conditions for using each tool.
Here's an example system prompt to guide your assistant. Remember to replace `ghl_contact_get`, `ghl_contact_create`, `ghl_check_availability`, and `ghl_create_event` with the exact names you gave your tools if they are different.
```text
You are a helpful and efficient scheduling assistant. Your primary goal is to book appointments for users. Follow these steps carefully:
1. **Gather Information**: Start by asking for the caller\'s full name and email address.
2. **Check Existing Contact**: Use the `ghl_contact_get` tool to see if a contact already exists with the provided email.
3. **Create Contact (if needed)**: If no contact is found, use the `ghl_contact_create` tool to create a new contact with their name and email.
4. **Discuss Appointment Time**: Once you have a contact ID (either from an existing contact or a newly created one), ask the user for their preferred date and time for the appointment.
5. **Check Availability**: Use the `ghl_check_availability` tool to check for open slots. It\'s a good idea to check for the entire preferred day to offer alternatives if their initial request isn\'t available.
6. **Confirm Time**: Discuss the available options with the user and agree on a suitable time.
7. **Book Appointment**: Finally, use the `ghl_create_event` tool to book the appointment, ensuring you use the correct contact ID.
**Important Guidelines:**
* Always use `ghl_contact_get` to check for an existing contact *before* attempting to create one with `ghl_contact_create`.
* You *must* have a contact ID (from `ghl_contact_get` or `ghl_contact_create`) *before* you can book an appointment with `ghl_create_event`.
* Always confirm availability with `ghl_check_availability` *before* attempting to book an appointment with `ghl_create_event`.
```
## Tool Configurations
### GoHighLevel Get Contact Tool
This tool uses both or one of the following fields to retrieve an existing contact:
* `email`: The email address of the contact to search for.
* `phone`: The phone number of the contact to search for.
### GoHighLevel Create Contact Tool
This tool uses the following fields to create a new contact:
* `firstName`: The first name of the contact.
* `lastName`: The last name of the contact.
* `email`: The email address of the contact.
* `phone`: The phone number of the contact.
### GoHighLevel Check Availability Tool
This tool uses the following fields to check for open appointment slots:
* `calendarId`: The ID of the GoHighLevel calendar to check.
* `startDate`: The start of the time range to check for availability (epoch time in milliseconds).
* `endDate`: The end of the time range to check for availability (epoch time in milliseconds).
* `timezone`: The timezone for the availability check (e.g., "America/New\_York").
### GoHighLevel Create Event Tool
This tool uses the following fields to book an appointment:
* `calendarId`: The ID of the GoHighLevel calendar in which to create the event.
* `contactId`: The ID of the GoHighLevel contact to associate with the event.
* `title`: The title or summary for the calendar event.
* `startTime`: The start date and time for the event in ISO 8601 format.
* `endTime`: The end date and time for the event in ISO 8601 format.
## Example Usage
Here's how the tools can be configured in your assistant's JSON setup:
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a highly efficient scheduling assistant for appointments. Your goal is to seamlessly book appointments into a calendar. Follow this precise workflow:\\n\\n1. **Gather User Info**: Start by politely asking for the caller's full name and email address.\\n2. **Check Existing Contact**: Use the 'getGHLContact' tool to check if a contact already exists with the provided email.\\n3. **Create New Contact (if necessary)**: If no contact is found with the email, use the 'createGHLContact' tool to create a new contact. You will need their name and email for this.\\n4. **Determine Appointment Needs**: Once you have a contact ID (either from an existing or newly created contact), ask the user for their preferred date and time for the appointment, and the purpose of the appointment (e.g., 'dental checkup', 'initial consultation').\\n5. **Check Calendar Availability**: Use the 'checkGHLAvailability' tool to find open slots for the requested period. Check a broad enough range (e.g., the entire day) to offer alternatives if the exact preferred time is unavailable.\\n6. **Confirm Time with User**: Discuss the available options and confirm a suitable appointment time with the user.\\n7. **Book the Appointment**: Use the 'createGHLEvent' tool to schedule the appointment. Use the purpose of the appointment as the event title.\\n\\n**Critical Notes:**\\n- Always use 'getGHLContact' before 'createGHLContact'.\\n- You MUST have a contactId before calling 'createGHLEvent'.\\n- Always use 'checkGHLAvailability' before 'createGHLEvent'.\\n- Assume all appointments are 30 minutes long unless specified otherwise by the user.\\n- Today's date is {{\"now\" | date: \"%A, %B %d, %Y, %I:%M %p\", \"America/New_York\"}}."
}
],
"tools": [
{
"type": "gohighlevel.calendar.availability.check",
"function": {
"name": "checkGHLAvailability",
"description": "Use this tool to check for available appointment slots in the GoHighLevel calendar. Today's date is {{\"now\" | date: \"%A, %B %d, %Y, %I:%M %p\", \"America/New_York\"}}."
},
"metadata": {
"calendarId": "CALENDAR_ID",
"timeZone": "America/New_York"
}
},
{
"type": "gohighlevel.calendar.event.create",
"function": {
"name": "ghl_create_event",
"description": "Use this tool to create a new appointment (event) in the GoHighLevel calendar. Today's date is {{\"now\" | date: \"%A, %B %d, %Y, %I:%M %p\", \"America/New_York\"}}. - All appointments are 30 minutes long unless specified otherwise by the user."
},
"metadata": {
"calendarId": "CALENDAR_ID"
}
},
{
"type": "gohighlevel.contact.get",
"function": {
"name": "getGHLContact",
"description": "Use this tool to retrieve an existing contact from GoHighLevel using the user's email address. This helps avoid duplicate entries."
}
},
{
"type": "gohighlevel.contact.create",
"function": {
"name": "createGHLContact",
"description": "Use this tool to create a new contact in GoHighLevel."
}
}
]
}
}
```
## Best Practices
1. **Clear Instructions**: Provide clear instructions in your assistant's system message about when to use each calendar tool
2. **Error Handling**: Include fallback responses for cases where either calendar tool fails
3. **Time Zone Awareness**: Always specify the correct timezone for events and availability checks. Also remember to format \{\{now}} with your desired timezone.
4. **Event Details**: Ensure all required fields are properly filled when creating events
5. **Availability Flow**: Check availability before attempting to schedule events to avoid conflicts
6. **Contact Prerequisite for Events**: Remember that creating an event in GoHighLevel requires a `contactId`. Ensure your assistant's logic always fetches or creates a contact (using the `getGHLContact` and `createGHLContact` tools) before attempting to book an appointment with the `createGHLEvent` tool.
Join our Discord community for support with GoHighLevel integration
View the complete API documentation for tools
# Introduction to Knowledge Bases
> Learn how to create and integrate custom knowledge bases into your voice AI assistants.
## **What is Vapi's Knowledge Base?**
A [**Knowledge Base**](/api-reference/knowledge-bases/create) is a collection of custom files that contain information on specific topics or domains. By integrating a Knowledge Base into your voice AI assistant, you can enable it to provide more accurate and informative responses to user queries based on your own data. Knowledge Bases are available through both the Vapi API and dashboard.
### **Why Use a Knowledge Base?**
Using a Knowledge Base with your voice AI assistant offers several benefits:
* **Improved accuracy**: Your assistant can provide responses based on your verified information rather than general knowledge.
* **Enhanced capabilities**: A Knowledge Base enables your assistant to answer complex domain-specific queries with detailed, contextually relevant responses.
* **Customization**: With a Knowledge Base, you can tailor your assistant's responses to specific domains or topics, making it more effective for your particular use case.
* **Up-to-date information**: You control the content, ensuring your assistant always has access to the latest information.
Knowledge Bases are configured through the API or dashboard. For advanced
configuration options, view all configurable properties in the [API
Reference](/api-reference/knowledge-bases/using-query-tool).
## **How to Create a Knowledge Base**
There are two main approaches to creating a Knowledge Base in Vapi:
1. **Dashboard method**: A simplified approach using the Vapi UI
2. **API method**: A more customizable approach using direct API calls
### **Method 1: Using the Dashboard**
#### **Step 1: Upload Your Files**
1. Navigate to `Build > Files` in your Vapi dashboard
2. Click the "Upload" button to add your files
3. Select files in supported formats (`.txt`, `.pdf`, `.docx`, etc.)
4. Wait for the upload to complete - you'll see your files listed in the Files section
Vapi supports various file formats for Knowledge Bases including: .txt, .pdf, .docx, .doc, .csv, .md, .tsv, .yaml, .json, .xml, and .log files.
#### **Step 2: Configure Your Assistant with the Knowledge Base**
1. Navigate to `Build > Assistant`
2. Select the assistant you want to enhance with the Knowledge Base
3. In the assistant configuration, locate the "Files" or "Knowledge Base" section
4. Select the files you uploaded in Step 1 to associate them with this assistant
#### **Step 3: Publish the Assistant**
1. Instruct your assistant to use the knowledge base when relevant by adding appropriate prompts in your assistant's configuration. This helps ensure the assistant knows when to reference the knowledge base versus using its general knowledge.
For example, if you have a knowledge base about your company's products, you might add this prompt:
```
When users ask about our products, services, or company information, use the knowledge base to provide accurate details.
```
2. Review your assistant configuration to ensure all settings are correct
3. Click the "Publish" button to make your changes live
4. This automatically creates a default knowledge base (using the query tool) with the selected files for the assistant
When you publish an assistant with selected files, Vapi automatically creates
a query tool with those files configured as a knowledge base. For more
advanced configurations, use the API method described below or see our [Query
Tool documentation](/knowledge-base/using-query-tool).
### **Method 2: Using the API**
For more advanced configurations, you can create and configure Knowledge Bases using the API through the Query Tool. This method offers greater flexibility and control over your knowledge base setup.
For detailed instructions on creating and configuring knowledge bases via the
API, please refer to our dedicated guide: [Using the Query Tool for Knowledge
Bases](/knowledge-base/using-query-tool).
The API method allows you to:
* Upload files and obtain file IDs
* Create custom query tools with specific knowledge base configurations
* Configure multiple knowledge bases within a single query tool
* Attach query tools to your assistants
* Set advanced parameters for knowledge retrieval
This approach is recommended for developers and users who need precise control over their knowledge base implementation or are integrating Vapi into existing systems programmatically.
## **Best Practices for Creating Effective Knowledge Bases**
* **Optimize file size**: Keep individual files smaller than 300KB to ensure quick processing and response times.
* **Structure content logically**: Organize your files by topic or category with clear headings and sections.
* **Use clear and concise language**: Write in plain language with well-defined terminology to improve retrieval accuracy.
* **Update regularly**: Refresh your knowledge base files whenever information changes to maintain accuracy.
* **Test thoroughly**: After configuration, test your assistant with various queries to ensure it retrieves information correctly.
* **Provide context**: Include sufficient background information in your files to enable comprehensive responses.
* **Consider file formats**: While plain text works well, structured formats can improve information retrieval for complex topics.
For more information on creating effective Knowledge Bases, check out our
tutorial on [Best Practices for Knowledge Base
Creation](https://youtu.be/i5mvqC5sZxU).
By following these guidelines, you can create a comprehensive Knowledge Base that enhances the capabilities of your voice AI assistant and provides valuable information to users.
Currently, Vapi's Knowledge Base functionality supports Google as a provider
with the gemini-1.5-flash model for knowledge retrieval. For the most
up-to-date information on supported providers and models, please refer to our
[API documentation](api-reference/tools/create#request.body.query.knowledgeBases).
# Using the Query Tool for Knowledge Bases
> Learn how to configure and use the query tool to enhance your voice AI assistants with custom knowledge bases.
## **What is the Query Tool?**
The Query Tool is a powerful feature that allows your voice AI assistant to access and retrieve information from custom knowledge bases. By configuring a query tool with specific file IDs, you can enable your assistant to provide accurate and contextually relevant responses based on your custom data.
### **Benefits of Using the Query Tool**
* **Enhanced contextual understanding**: Your assistant can access specific knowledge to answer domain-specific questions.
* **Improved response accuracy**: Responses are based on your verified information rather than general knowledge.
* **Customizable knowledge retrieval**: Configure multiple knowledge bases for different topics or domains.
Currently, the Query Tool only supports Google as a provider with the
gemini-1.5-flash model for knowledge base retrieval.
## **How to Configure a Query Tool for Knowledge Bases**
### **Step 1: Upload Your Files**
Before creating a query tool, you need to upload the files that will form your knowledge base.
#### Option 1: Using the Dashboard (Recommended)
1. Navigate to **Files** in your Vapi dashboard
2. Click **Upload File** or **Choose file**
3. Select the files you want to upload from your computer
4. Wait for the upload to complete and note the file IDs that are generated
#### Option 2: Using the API
Alternatively, you can upload files via the API:
```bash
curl --location 'https://api.vapi.ai/file' \
--header 'Authorization: Bearer ' \
--form 'file=@""'
```
After uploading, you'll receive file IDs that you'll need for the next step.
### **Step 2: Create a Query Tool**
Create a query tool that references your knowledge base files:
#### Option 1: Using the Dashboard (Recommended)
1. Navigate to **Tools** in your Vapi dashboard
2. Click **Create Tool**
3. Select **Query** as the tool type
4. Configure the tool:
* **Tool Name**: "Product Query"
* **Knowledge Bases**: Add your knowledge base with:
* **Name**: `product-kb`
* **Description**: "Use this knowledge base when the user asks or queries about the product or services"
* **File IDs**: Select the files you uploaded in Step 1
#### Option 2: Using the API
Alternatively, you can create the tool via API:
```bash
curl --location 'https://api.vapi.ai/tool/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
"type": "query",
"function": {
"name": "product-query"
},
"knowledgeBases": [
{
"provider": "google",
"name": "product-kb",
"description": "Use this knowledge base when the user asks or queries about the product or services",
"fileIds": [
"41a2bd44-d13c-4914-bbf7-b19807dd2cf4",
"ef82ae15-21b2-47bd-bde4-dea3922c1e49"
]
}
]
}'
```
The `description` field in the knowledge base configuration helps your
assistant understand when to use this particular knowledge base. Make it
descriptive of the content.
### **Step 3: Attach the Query Tool to Your Assistant**
After creating the query tool, you need to attach it to your assistant:
#### Option 1: Using the Dashboard (Recommended)
1. Navigate to **Assistants** in your Vapi dashboard
2. Select the assistant you want to configure
3. Go to the **Tools** section
4. Click **Add Tool** and select your query tool from the dropdown
5. Save and publish your assistant
#### Option 2: Using the API
Alternatively, you can attach the tool via API using the tool ID:
```bash
curl --location --request PATCH 'https://api.vapi.ai/assistant/ASSISTANT_ID' \
--header 'Authorization: Bearer ' \
--data '{
"model": {
"temperature": 0.2,
"provider": "openai",
"model": "gpt-4o",
"toolIds": [
"9441840b-6f2f-4b0f-a0fc-de8512549a0c"
]
}
}'
```
When using the PATCH request, you must include the entire model object, not
just the toolIds field. This will overwrite any existing model configuration.
## **Advanced Configuration Options**
### **Multiple Knowledge Bases**
You can configure multiple knowledge bases within a single query tool:
```json
"knowledgeBases": [
{
"provider": "google",
"name": "product-documentation",
"description": "Use this knowledge base for product specifications and features",
"fileIds": ["file-id-1", "file-id-2"]
},
{
"provider": "google",
"name": "troubleshooting-guide",
"description": "Use this knowledge base for troubleshooting and support questions",
"fileIds": ["file-id-3", "file-id-4"]
}
]
```
### **Knowledge Base Description**
The description field helps your assistant understand when to use a particular knowledge base. Make it specific and clear:
```json
"description": "Use this knowledge base when the user asks about pricing, subscription plans, or billing information"
```
## **Best Practices for Query Tool Configuration**
* **Organize by topic**: Create separate knowledge bases for distinct topics to improve retrieval accuracy.
* **Use descriptive names**: Name your knowledge bases clearly to help your assistant understand their purpose.
* **Keep descriptions specific**: Write clear descriptions that tell the assistant exactly when to use each knowledge base.
* **Update regularly**: Refresh your knowledge bases as information changes to ensure accuracy.
* **Test thoroughly**: After configuration, test your assistant with various queries to ensure it retrieves information correctly.
For optimal performance, keep individual files under 300KB and ensure they
contain clear, well-structured information.
By following these steps and best practices, you can effectively configure the query tool to enhance your voice AI assistant with custom knowledge bases, making it more informative and responsive to user queries.
# Bring your own chunks/vectors from Trieve
> Using Trieve for improved RAG with Vapi
# Using Trieve with Vapi
Vapi integrates with [Trieve](https://trieve.ai) through the BYOD (Bring Your Own Dataset) approach, allowing you to use your Trieve API key to import your existing Trieve datasets into Vapi.
## Integrating with Trieve
The BYOD approach offers flexibility and control over your datasets. You can:
* Fully manage your datasets in Trieve's native interface
* Use Trieve's advanced features like:
* Custom chunking rules
* Search playground testing
* Manual chunk editing
* Website crawling
* Dataset visualization
### Step 1: Set Up Trieve Dataset
1. Create an account at [Trieve](https://trieve.ai)
2. Create a new dataset using Trieve's dashboard
When creating your dataset in Trieve, selecting the right embedding model is crucial for optimizing performance and accuracy. Here are some of the available options:
### jina-base-en
* **Provider**: Jina AI (Hosted by Trieve)
* **Performance**: Fast
* **Description**: This model is designed for speed and efficiency, making it suitable for applications where quick response times are critical. It provides a good balance of performance and accuracy for general use cases.
### text-embedding-3-small
* **Provider**: OpenAI
* **Performance**: Moderate
* **Description**: A smaller model from OpenAI that offers a compromise between speed and accuracy. It is suitable for applications that require a balance between computational efficiency and the quality of embeddings.
### text-embedding-3-large
* **Provider**: OpenAI
* **Performance**: Slow
* **Description**: This larger model provides the highest accuracy among the options but at the cost of slower processing times. It is ideal for applications where the quality of embeddings is prioritized over speed.
3. Add content through various methods:
#### Upload Documents
Upload documents directly through Trieve's interface:
When uploading files, you can configure advanced chunking options:
#### Edit Individual Chunks
After uploading documents, you can edit individual chunks to refine their content:
##### Editing Options
* **Chunk Content**: Modify the text directly in the rich text editor
* Fix formatting issues
* Correct errors or typos
* Split or combine chunks manually
* Add or remove content
* **Metadata Fields**:
* Date: Update document timestamps
* Number Value: Adjust numeric metadata for filtering
* Location: Set or modify geographical coordinates
* Weight: Fine-tune search relevance with custom weights
* Fulltext Boost: Add terms to enhance search visibility
* Semantic Boost: Adjust vector embedding influence
##### Best Practices for Chunk Editing
1. **Content Length**
* Keep chunks between 200-1000 tokens
* Maintain logical content boundaries
* Ensure complete thoughts within each chunk
2. **Metadata Optimization**
* Use consistent date formats
* Add relevant numeric values for filtering
* Apply weights strategically for important content
3. **Search Enhancement**
* Use boost terms for critical keywords
* Balance semantic and fulltext boosts
* Test search results after significant edits
### Advanced Chunking Options
#### Metadata
* Add custom metadata as JSON to associate with your chunks
* Useful for filtering and organizing content (e.g., `{"author": "John Doe", "category": "technical"}`)
* Keep metadata concise and relevant to avoid storage overhead
* Use consistent keys across related documents for better searchability
#### Date
* Specify the creation or relevant date for the document
* Important for version control and content freshness
* Helps with filtering outdated information
* Use actual document creation dates when possible
#### Split Delimiters
* Define custom delimiters (e.g., ".,?\n") to control where chunks are split
* Recommended defaults: ".,?\n" for general content
* Add semicolons (;) for technical documentation
* Use "\n\n" for markdown or structured content
* Avoid over-aggressive splitting that might break context
#### Target Splits Per Chunk
* Set the desired number of splits per chunk
* Default: 20 splits
* Recommended ranges:
* 15-25 for general content
* 10-15 for technical documentation
* 25-30 for narrative content
* Lower values create more granular chunks, better for precise retrieval
* Higher values maintain more context but may retrieve irrelevant information
#### Rebalance Chunks
* Enable to redistribute content evenly across chunks
* Recommended for documents with varying section lengths
* Helps maintain consistent chunk sizes
* May slightly impact natural content boundaries
* Best used with technical documentation or structured content
#### Use gpt4o chunking
* Enable GPT-4 optimized chunking for improved semantic coherence
* Recommended for:
* Complex technical documentation
* Content with intricate relationships
* Documents where context preservation is crucial
* Note: Increases processing time and cost
* Best for high-value content where accuracy is paramount
#### Heading Based Chunking
* Split content based on document headings
* Ideal for well-structured documents (e.g., documentation, reports)
* Works best with consistent heading hierarchy
* Consider enabling for:
* Technical documentation
* User manuals
* Research papers
* May create uneven chunk sizes based on section lengths
#### System Prompt
* Provide custom instructions for the chunking process
* Optional but powerful for specific use cases
* Example prompts:
* "Preserve code blocks as single chunks"
* "Keep API endpoint descriptions together"
* "Maintain question-answer pairs in the same chunk"
* Keep prompts clear and specific
* Test different prompts with sample content to optimize results
#### Website Crawling
Trieve offers powerful website crawling capabilities with extensive configuration options:
##### Crawl Configuration Options
* **Crawl Interval**: Set how often to refresh content
* Options: Daily, Weekly, Monthly
* Recommended: Daily for frequently updated content
* **Page Limit**: Control the maximum number of pages to crawl
* Default: 1000 pages
* Adjust based on your site size and content relevance
* **URL Patterns**
* Include/Exclude specific URL patterns using regex
* Example includes: `https://docs.example.com/*`
* Example excludes: `https://example.com/internal/*`
* **Query Selectors**
* Include specific HTML elements for targeted content extraction
* Exclude navigation, footers, and other non-content elements
* Common excludes: `navbar`, `footer`, `aside`, `nav`, `form`
* **Special Content Types**
* OpenAPI Spec: Toggle for API documentation crawling
* Shopify: Enable for e-commerce content
* YouTube Channel: Include video transcripts and descriptions
* **Advanced Options**
* Boost Titles: Increase weight of page titles in search results
* Allow External Links: Include content from linked domains
* Ignore Sitemap: Skip sitemap-based crawling
* Remove Strings: Clean up headers and body content
##### Best Practices for Crawling
1. **Start Small**
* Begin with a low page limit
* Test with specific sections of your site
* Gradually expand coverage
2. **Optimize Selectors**
* Remove navigation and UI elements
* Focus on main content areas
* Use browser inspector to identify key selectors
3. **Monitor Performance**
* Check crawl logs regularly
* Adjust patterns based on results
* Balance frequency with server load
### Step 2: Test and Refine
Use Trieve's search playground to:
* Test semantic search queries
* Adjust chunk sizes
* Edit chunks manually
* Visualize vector embeddings
* Fine-tune relevance scores
### Step 3: Import to Vapi
1. Create your Trieve API key from [Trieve's dashboard](https://dashboard.trieve.ai/org/keys)
2. Add your Trieve API key to Vapi [Provider Credentials](https://dashboard.vapi.ai/keys)
3. Once your dataset is optimized in Trieve, import it to Vapi via POST request to the [create knowledge base route](/api-reference/knowledge-bases/create):
```json
{
"name": "trieve-dataset",
"provider": "trieve",
"searchPlan": {
"scoreThreshold": 0.2,
"searchType": "semantic"
},
"createPlan": {
"type": "import",
"providerId": ""
}
}
```
## Best Practices
1. **Dataset Organization**
* Segment datasets by domain knowledge boundaries
* Use semantic-based dataset naming (e.g., "api-docs-v2", "user-guides-2024")
* Version control chunking configurations in your codebase
2. **Content Quality**
* Implement text normalization (Unicode normalization, whitespace standardization)
* Use regex patterns to clean formatting artifacts
* Validate chunk semantic coherence through embedding similarity scores
3. **Performance Optimization**
* Target chunk sizes: 200-1000 tokens (optimal for current embedding models)
* Configure hybrid search with BM25 boost = 0.3 for technical content
* Set score thresholds dynamically based on embedding model (0.2 for text-embedding-3-small, 0.25 for text-embedding-3-large)
4. **Maintenance**
* Implement automated content refresh cycles via Trieve's API
* Track search result relevance metrics (MRR, NDCG)
* Rotate API keys on 90-day cycles
## Troubleshooting
Common issues and solutions:
1. **Search Relevance Issues**
* Implement cross-encoder reranking for critical queries
* Fine-tune BM25 vs semantic weights (recommended ratio: 0.3:0.7)
* Analyze chunk boundary overlap percentage (aim for 15-20%)
2. **Integration Errors**
* Validate dataset permissions (READ\_DATASET scope required)
* Check for dataset ID format compliance (UUID v4)
* Monitor rate limits (default: 100 requests/min)
3. **Performance Optimization**
* Implement chunk size normalization (max variance: 20%)
* Enable query caching for frequent searches
* Use batch operations for bulk updates (max 100 chunks/request)
Need help? Contact [support@vapi.ai](mailto:support@vapi.ai) for assistance.
# Custom Keywords
> Enhanced transcription accuracy guide
Vapi allows you to improve the accuracy of your transcriptions by leveraging Deepgram's keyword boosting feature. This is particularly useful when dealing with specialized terminology or uncommon proper nouns. By providing specific keywords to the Deepgram model, you can enhance transcription quality directly through Vapi.
### Why Use Keyword Boosting?
Keyword boosting is beneficial for:
* Enhancing the recognition of specialized terms and proper nouns.
* Improving transcription accuracy without the need for a custom-trained model.
* Quickly updating the model's vocabulary with new or uncommon words.
### Important Notes
* Keywords should be uncommon words or proper nouns not frequently recognized by the model.
* Custom model training is the most effective way to ensure accurate keyword recognition.
* For more than 50 keywords, consider custom model training by contacting Deepgram.
## Enabling Keyword Boosting in Vapi
### API Call Integration
To enable keyword boosting, you need to add a `keywords` parameter to your Vapi assistant's transcriber section. This parameter should include the keywords and their respective intensifiers.
### Example of POST Request
To create an assistant with keyword boosting enabled, you can make the following POST request to Vapi:
```bash
bashCopy code
curl \
--request POST \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"name": "Emma",
"model": {
"model": "gpt-4o",
"provider": "openai"
},
"voice": {
"voiceId": "emma",
"provider": "azure"
},
"transcriber": {
"provider": "deepgram",
"model": "nova-2",
"language": "bg",
"smartFormat": true,
"keywords": [
"snuffleupagus:1"
]
},
"firstMessage": "Hi, I am Emma, what is your name?",
"firstMessageMode": "assistant-speaks-first"
}' \
https://api.vapi.ai/assistant
```
In this configuration:
* **name**: The name of the assistant.
* **model**: Specifies the model and provider for the assistant's conversational capabilities.
* **voice**: Specifies the voice and provider for the assistant's speech.
* **transcriber**: Specifies Deepgram as the transcription provider, along with the model, language, smart formatting, and keywords for boosting.
* **firstMessage**: The initial message the assistant will speak.
* **firstMessageMode**: Specifies that the assistant speaks first.
### Intensifiers
Intensifiers are exponential factors that boost or suppress the likelihood of the specified keyword being recognized. The default intensifier is `1`. Higher values increase the likelihood, while `0` is equivalent to not specifying a keyword.
* **Boosting Example:** `keywords=snuffleupagus:5`
* **Suppressing Example:** `keywords=kansas:-10`
### Best Practices for Keyword Boosting
1. **Send Uncommon Keywords:** Focus on keywords not successfully transcribed by the model.
2. **Send Keywords Once:** Avoid repeating keywords.
3. **Use Individual Keywords:** Prefer individual terms over phrases.
4. **Use Proper Spelling:** Spell proper nouns as you want them to appear in transcripts.
5. **Moderate Intensifiers:** Start with small increments to avoid false positives.
6. **Custom Model Training:** For extensive vocabulary needs, consider custom model training.
### Additional Resources
For more detailed information on Deepgram's keyword boosting feature, refer to the Deepgram Keyword Boosting Documentation.
By following these guidelines, you can effectively utilize Deepgram's keyword boosting feature within your Vapi assistant, ensuring enhanced transcription accuracy for specialized terminology and uncommon proper nouns.
# Custom voices
> Use a custom voice with your preferred provider
You can use your own custom voice with any supported provider by setting the `voice` property in your assistant configuration:
```json
{
"voice": {
"provider": "deepgram",
"voiceId": "your-voice-id"
}
}
```
# ElevenLabs
> Set up a custom ElevenLabs voice in Vapi
This guide outlines the procedure for integrating your cloned voice with ElevenLabs through the Vapi platform.
An API subscription is required for this process to work.
Visit the [ElevenLabs pricing page](https://elevenlabs.io/pricing) and subscribe to an API plan that suits your needs.
Go to the 'Profile + Keys' section on the ElevenLabs website to get your API key.
Navigate to the [Vapi Provider Key section](https://dashboard.vapi.ai/keys) and input your ElevenLabs API key under the ElevenLabs section.
Once you click save, your voice library will sync automatically.
After syncing, you can search for your cloned voice in the "voices" tab in the assistants page, use it with your assistant.
**Video Tutorial:**
# PlayHT
> Set up a custom PlayHT voice in Vapi
You can use your own custom PlayHT voice with Vapi by following these steps.
An API subscription is required for this process.
Visit the [PlayHT pricing page](https://play.ht/studio/pricing) and subscribe to an API plan.
Go to the [API Access section](https://play.ht/studio/api-access) on PlayHT to get your User ID and Secret Key.
Navigate to the [Vapi Provider Key section](https://dashboard.vapi.ai/keys) and add your PlayHT API keys under the PlayHT section.
From the [Voice Library](https://dashboard.vapi.ai/voice-library) in Vapi, select PlayHT as your voice provider and click on "Sync with PlayHT."
After syncing, you can search for your cloned voice within the voice library and use it with your assistant.
**Video tutorial:**
# Tavus
> Set up a custom Tavus replica in Vapi
You can use your own custom Tavus replica with Vapi by following these steps.
An API subscription is required for this process. These steps are only needed for custom Tavus replicas, not for stock replicas on the Vapi platform.
Visit the [Tavus pricing page](https://platform.tavus.io/billing) and subscribe to an API plan.
Go to the [API Keys section](https://platform.tavus.io/api-keys) on Tavus to get your API key.
Navigate to the [Vapi Provider Key section](https://dashboard.vapi.ai/keys) and add your Tavus API key under the Tavus section.
After adding your API key, select Tavus as your assistant's voice provider and add your Custom Replica ID manually through the dashboard. Alternatively, use the API and specify the replica ID in the `voiceId` field.
**Video tutorial:**
# Custom TTS integration
> Learn to integrate your own text-to-speech system with VAPI
## Overview
Integrate your own Text-to-Speech (TTS) system with VAPI Assistant for complete control over voice synthesis. Whether you need brand-specific voices, advanced audio quality, or cost optimization, custom TTS gives you the flexibility to use any TTS provider while maintaining real-time performance.
**In this guide, you'll learn to:**
* Set up webhook authentication between VAPI and your TTS endpoint
* Build a TTS server that handles VAPI's audio requirements
* Process text requests and return properly formatted audio
* Handle edge cases and troubleshoot common issues
Custom TTS maintains VAPI's real-time performance while giving you complete
flexibility over voice synthesis, language support, and audio quality.
## How custom TTS works
VAPI's custom TTS system operates through a webhook pattern:
During a conversation, VAPI needs to convert text to speech
VAPI sends a POST request to your TTS endpoint with text and audio
specifications
Your system generates audio and returns it as raw PCM data
VAPI streams the audio to the caller in real-time
### What you'll need
* **Web server** that can receive POST requests and return audio data
* **TTS system** (cloud API, local model, or custom solution)
* **VAPI account** with access to custom voice configuration
Your TTS system must generate audio in specific PCM format requirements to
ensure proper playback quality.
## Authentication setup
VAPI needs secure communication with your TTS endpoint. Choose from these authentication options:
### Secret header authentication
The most common approach uses a secret token in the `X-VAPI-SECRET` header:
```json title="Assistant Configuration"
{
"voice": {
"provider": "custom-voice",
"server": {
"url": "https://your-tts-api.com/synthesize",
"secret": "your-secret-token-here",
"timeoutSeconds": 30
}
}
}
```
### Enhanced authentication with custom headers
Add extra headers for API versioning or enhanced security:
```json title="Assistant Configuration with Custom Headers"
{
"voice": {
"provider": "custom-voice",
"server": {
"url": "https://your-tts-api.com/synthesize",
"secret": "your-secret-token",
"headers": {
"X-API-Version": "v1",
"X-Client-ID": "vapi-integration"
}
}
}
}
```
Enterprise customers can use OAuth2 authentication through webhook credentials
for larger deployments.
## Building your TTS integration
### Configure your VAPI assistant
Set up your assistant to use your custom TTS endpoint with fallback options:
```json title="Complete Assistant Configuration"
{
"name": "Custom Voice Assistant",
"voice": {
"provider": "custom-voice",
"server": {
"url": "https://your-tts-endpoint.com/api/synthesize",
"secret": "your-webhook-secret",
"timeoutSeconds": 45,
"headers": {
"Content-Type": "application/json",
"X-API-Version": "v1"
}
},
"fallbackPlan": {
"voices": [
{
"provider": "eleven-labs",
"voiceId": "21m00Tcm4TlvDq8ikWAM"
}
]
}
}
}
```
### Build your TTS server
Here's a complete Node.js implementation that handles all requirements:
```javascript title="tts-server.js"
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json({ limit: '50mb' }));
// Main TTS endpoint
app.post('/api/synthesize', async (req, res) => {
const requestId = crypto.randomUUID();
const startTime = Date.now();
// Set up timeout protection
const timeout = setTimeout(() => {
if (!res.headersSent) {
res.status(408).json({ error: 'Request timeout' });
}
}, 30000);
try {
console.log(`TTS request started: ${requestId}`);
// Extract and validate the request
const { message } = req.body;
if (!message) {
clearTimeout(timeout);
return res.status(400).json({ error: 'Missing message object' });
}
const { type, text, sampleRate } = message;
// Validate message type
if (type !== 'voice-request') {
clearTimeout(timeout);
return res.status(400).json({ error: 'Invalid message type' });
}
// Validate text content
if (!text || typeof text !== 'string' || text.trim().length === 0) {
clearTimeout(timeout);
return res.status(400).json({ error: 'Invalid or missing text' });
}
// Validate sample rate
const validSampleRates = [8000, 16000, 22050, 24000, 44100];
if (!validSampleRates.includes(sampleRate)) {
clearTimeout(timeout);
return res.status(400).json({
error: 'Unsupported sample rate',
supportedRates: validSampleRates,
});
}
console.log(
`Synthesizing: ${requestId}, length=${text.length}, rate=${sampleRate}Hz`
);
// Generate the audio (replace with your TTS implementation)
const audioBuffer = await synthesizeAudio(text, sampleRate);
if (!audioBuffer || audioBuffer.length === 0) {
throw new Error('TTS synthesis produced no audio');
}
clearTimeout(timeout);
// Return raw PCM audio to VAPI
res.setHeader('Content-Type', 'application/octet-stream');
res.setHeader('Content-Length', audioBuffer.length);
res.write(audioBuffer);
res.end();
const duration = Date.now() - startTime;
console.log(
`TTS completed: ${requestId}, ${duration}ms, ${audioBuffer.length} bytes`
);
} catch (error) {
clearTimeout(timeout);
const duration = Date.now() - startTime;
console.error(`TTS failed: ${requestId}, ${duration}ms, ${error.message}`);
if (!res.headersSent) {
res.status(500).json({ error: 'TTS synthesis failed', requestId });
}
}
});
// Replace with your actual TTS implementation
async function synthesizeAudio(text, sampleRate) {
// Example: Call your TTS API here
// const audioBuffer = await yourTTSProvider.synthesize(text, sampleRate);
// Demo implementation (replace with real TTS)
await new Promise(resolve => setTimeout(resolve, 100));
const duration = Math.min(text.length _ 0.1, 10); // Max 10 seconds
const samples = Math.floor(duration _ sampleRate);
const buffer = Buffer.alloc(samples \* 2); // 16-bit = 2 bytes per sample
for (let i = 0; i < samples; i++) {
const value = Math.sin((2 _ Math.PI _ 440 _ i) / sampleRate) _ 16000;
buffer.writeInt16LE(Math.round(value), i \* 2);
}
return buffer;
}
// Error handling middleware
app.use((error, req, res, next) => {
console.error('Unhandled error:', error.message);
res.status(500).json({ error: 'Internal server error' });
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`TTS server listening on port ${PORT}`);
});
module.exports = app;
```
### Handle text processing
Implement proper text validation and preprocessing:
```javascript title="Text Processing Functions"
function preprocessText(text) {
// Handle SSML tags if your TTS supports them
if (text.includes('')) {
return parseSSML(text);
}
// Clean up problematic characters
return text
.replace(/[^\w\s\.,!?-]/g, '') // Remove special characters
.replace(/\s+/g, ' ') // Normalize whitespace
.trim();
}
function validateText(text) {
if (!text || text.trim().length === 0) {
throw new Error('Empty text provided');
}
if (!/[a-zA-Z]/.test(text)) {
throw new Error('No readable text found');
}
return text.trim();
}
```
## Request and response formats
### VAPI request structure
Every TTS request from VAPI follows this format:
```json title="VAPI TTS Request"
{
"message": {
"type": "voice-request",
"text": "Hello, world! How can I help you today?",
"sampleRate": 24000,
"timestamp": 1677123456789,
"call": {
"id": "call-123",
"orgId": "org-456"
},
"assistant": {
"id": "assistant-789",
"name": "Customer Service Bot"
},
"customer": {
"number": "+1234567890"
}
}
}
```
### Required fields
| Field | Type | Description |
| ------------ | ------ | ---------------------------------------------------------- |
| `type` | string | Always "voice-request" |
| `text` | string | Text to synthesize |
| `sampleRate` | number | Target audio sample rate (8000, 16000, 22050, or 24000 Hz) |
| `timestamp` | number | Unix timestamp in milliseconds |
### Your response requirements
Your endpoint must respond with:
* **HTTP 200 status**
* **Content-Type: application/octet-stream**
* **Raw PCM audio data** in the response body
```http title="Correct Response Headers"
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
[Raw PCM audio bytes]
```
## Audio format requirements
### PCM specifications
Your TTS system must generate audio with these exact specifications:
* **Format:** Raw PCM (no headers or containers)
* **Channels:** 1 (mono only)
* **Bit Depth:** 16-bit signed integer
* **Byte Order:** Little-endian
* **Sample Rate:** Must exactly match the `sampleRate` in the request
Any deviation from these specifications will cause audio distortion, playback failures, or call quality issues. VAPI streams audio in real-time during phone calls.
## Testing your integration
### Create a test call
Use VAPI's API to create a test call that exercises your TTS system:
```javascript title="Test Call Creation"
async function testTTSWithVAPICall() {
const vapiApiKey = 'your-vapi-api-key';
const assistantId = 'your-assistant-id'; // Assistant with custom TTS
const callData = {
assistant: { id: assistantId },
phoneNumberId: 'your-phone-number-id',
customer: { number: '+1234567890' }, // Your test number
};
try {
const response = await fetch('https://api.vapi.ai/call', {
method: 'POST',
headers: {
Authorization: `Bearer ${vapiApiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(callData),
});
const call = await response.json();
console.log('Test call created:', call.id);
return call;
} catch (error) {
console.error('Failed to create test call:', error);
}
}
```
### Monitor TTS requests
Set up logging to see exactly what VAPI sends to your endpoint:
```javascript title="Request Monitoring Middleware"
app.use('/api/synthesize', (req, res, next) => {
console.log('=== Incoming TTS Request ===');
console.log('Headers:', req.headers);
console.log('Body:', JSON.stringify(req.body, null, 2));
console.log('==============================');
next();
});
```
### Quick endpoint test
Test your endpoint directly before full integration:
```javascript title="Direct Endpoint Test"
async function quickEndpointTest() {
const testPayload = {
message: {
type: 'voice-request',
text: 'Hello, this is a test of the custom TTS system.',
sampleRate: 24000,
timestamp: Date.now(),
},
};
try {
const response = await fetch('http://localhost:3000/api/synthesize', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-VAPI-SECRET': 'your-test-secret',
},
body: JSON.stringify(testPayload),
});
if (response.ok) {
const audioBuffer = await response.buffer();
console.log(`Audio generated: ${audioBuffer.length} bytes`);
require('fs').writeFileSync('test-output.pcm', audioBuffer);
} else {
console.error('Test failed:', await response.text());
}
} catch (error) {
console.error('Test error:', error);
}
}
```
## Troubleshooting
**Symptoms:** VAPI doesn't receive your audio response, calls may drop
**Common causes:**
* TTS processing takes longer than configured timeout
* Network connectivity issues between VAPI and your server
* Server overload or unresponsiveness
**Solutions:**
* Increase `timeoutSeconds` in your assistant configuration
* Optimize your TTS processing speed
* Implement proper error handling and timeout protection
**Symptoms:** No audio during calls, or distorted/garbled sound
**Common causes:**
* Wrong audio format (not raw PCM)
* Incorrect sample rate
* Sending stereo audio instead of mono
* Including audio file headers in response
**Solutions:**
* Ensure raw PCM format with no headers
* Match the exact sample rate from the request
* Generate mono audio only
* Verify 16-bit little-endian format
**Symptoms:** 401 Unauthorized responses in your server logs
**Common causes:**
* Secret token mismatch between VAPI config and server
* Missing X-VAPI-SECRET header validation
* Case sensitivity issues with header names
**Solutions:**
* Verify secret token matches exactly
* Implement proper header validation
* Check for case-sensitive header handling
**Symptoms:** Noticeable delays during conversations
**Common causes:**
* TTS model loading time on first request
* Complex text processing before synthesis
* Network latency between services
**Solutions:**
* Pre-load TTS models at startup
* Optimize text preprocessing
* Use faster TTS models for real-time performance
* Consider geographic proximity of services
## Next steps
Now that you have custom TTS integration working:
* **Advanced features:** Explore SSML support for enhanced voice control
* **Performance optimization:** Implement caching and model warming strategies
* **Voice cloning:** Integrate voice cloning APIs for personalized experiences
* **Multi-language support:** Add language detection and voice switching
Consider implementing a fallback voice provider in your assistant configuration to ensure call continuity if your custom TTS endpoint experiences issues.
```
```
# Fine-tuned OpenAI models
> Use Another LLM or Your Own Server
Vapi supports using any OpenAI-compatible endpoint as the LLM. This includes services like [OpenRouter](https://openrouter.ai/), [AnyScale](https://www.anyscale.com/), [Together AI](https://www.together.ai/), or your own server.
* For an open-source LLM, like Mixtral
* To update the context during the conversation
* To customize the messages before they're sent to an LLM
## Using an LLM provider
You'll first want to POST your API key via the `/credential` endpoint:
```json
{
"provider": "openrouter",
"apiKey": ""
}
```
Then, you can create an assistant with the model provider:
```json
{
"name": "My Assistant",
"model": {
"provider": "openrouter",
"model": "cognitivecomputations/dolphin-mixtral-8x7b",
"messages": [
{
"role": "system",
"content": "You are an assistant."
}
],
"temperature": 0.7
}
}
```
## Using Fine-Tuned OpenAI Models
To set up your OpenAI Fine-Tuned model, you need to follow these steps:
1. Set the custom llm URL to `https://api.openai.com/v1`.
2. Assign the custom llm key to the OpenAI key.
3. Update the model to their model.
4. Execute a PATCH request to the `/assistant` endpoint and ensure that `model.metadataSendMode` is set to off.
## Using your server
To set up your server to act as the LLM, you'll need to create an endpoint that is compatible with the [OpenAI Client](https://platform.openai.com/docs/api-reference/making-requests). For best results, your endpoint should also support streaming completions.
If your server is making calls to an OpenAI compatble API, you can pipe the requests directly back in your response to Vapi.
If you'd like your OpenAI-compatible endpoint to be authenticated, you can POST your server's API key and URL via the `/credential` endpoint:
```json
{
"provider": "custom-llm",
"apiKey": ""
}
```
If your server isn't authenticated, you can skip this step.
Then, you can create an assistant with the `custom-llm` model provider:
```json
{
"name": "My Assistant",
"model": {
"provider": "custom-llm",
"url": "",
"model": "my-cool-model",
"messages": [
{
"role": "system",
"content": "You are an assistant."
}
],
"temperature": 0.7
}
}
```
# Connecting Your Custom LLM to Vapi: A Comprehensive Guide
This guide provides a comprehensive walkthrough on integrating Vapi with OpenAI's gpt-4.1-mini model using a custom LLM configuration. We'll leverage Ngrok to expose a local development environment for testing and demonstrate the communication flow between Vapi and your LLM.
## Prerequisites
* **Vapi Account**: Access to the Vapi Dashboard for configuration.
* **OpenAI API Key**: With access to the gpt-4.1-mini model.
* **Python Environment**: Set up with the OpenAI library (`pip install openai`).
* **Ngrok**: For exposing your local server to the internet.
* **Code Reference**: Familiarize yourself with the `/openai-sse/chat/completions` endpoint function in the provided Github repository: [Server-Side Example Python Flask](https://github.com/VapiAI/server-side-example-python-flask/blob/main/app/api/custom_llm.py).
## Step 1: Setting Up Your Local Development Environment
**1. Create a Python Script (app.py):**
```python
from flask import Flask, request, jsonify
import openai
app = Flask(__name__)
openai.api_key = "YOUR_OPENAI_API_KEY" # Replace with your actual API key
@app.route("/chat/completions", methods=["POST"])
def chat_completions():
data = request.get_json()
# Extract relevant information from data (e.g., prompt, conversation history)
# ...
response = openai.ChatCompletion.create(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
# ... (Add messages from conversation history and current prompt)
]
)
# Format response according to Vapi's structure
# ...
return jsonify(formatted_response)
if __name__ == "__main__":
app.run(debug=True, port=5000) # You can adjust the port if needed
```
**2. Run the Script:**
Execute the Python script using python app.py in your terminal. This will start the Flask server on the specified port (5000 in this example).
**3. Expose with Ngrok:**
Open a new terminal window and run ngrok http 5000 (replace 5000 with your chosen port) to create a public URL that tunnels to your local server.
## Step 2: Configuring Vapi with Custom LLM
**1. Access Vapi Dashboard:**
Log in to your Vapi account and navigate to the "Model" section.
**2. Select Custom LLM:**
Choose the "Custom LLM" option to set up the integration.
**3. Enter Ngrok URL:**
Paste the public URL generated by ngrok (e.g., [https://your-unique-id.ngrok.io](https://your-unique-id.ngrok.io)) into the endpoint field. This will be the URL Vapi uses to communicate with your local server.
**4. Test the Connection:**
Send a test message through the Vapi interface to ensure it reaches your local server and receives a response from the OpenAI API. Verify that the response is displayed correctly in Vapi.
## Authentication (Optional)
For production deployments, you can secure your custom LLM endpoint using authentication. This ensures only authorized requests from Vapi can access your LLM server.
### Configuration Options
Vapi supports two authentication methods for custom LLMs:
1. **API Key**: Simple authentication where Vapi includes a static API key in request headers. Your server validates this key to authorize requests.
2. **OAuth2 Credentials**: More secure authentication using OAuth2 client credentials flow with automatic token refresh.
### API Key Authentication
When using API Key authentication:
* Vapi sends your API key in the Authorization header to your custom LLM endpoint
* Your server validates the API key before processing the request
* Simple to implement and suitable for basic security requirements
### OAuth2 Authentication
When configuring OAuth2 in the Vapi dashboard:
1. **OAuth2 URL**: Enter your OAuth2 token endpoint (e.g., `https://your-server.com/oauth/token`)
2. **OAuth2 Client ID**: Your OAuth2 client identifier
3. **OAuth2 Client Secret**: Your OAuth2 client secret
### How OAuth2 Works
1. Vapi requests an access token from your OAuth2 endpoint using client credentials
2. Your server validates the credentials and returns an access token
3. Vapi includes the token in the Authorization header for LLM requests
4. Your server validates the token before processing requests
5. Tokens automatically refresh when they expire
## Step 3: Understanding the Communication Flow
**1. Vapi Sends POST Request:**
When a user interacts with your Vapi application, Vapi sends a POST request containing conversation context and metadata to the configured endpoint (your ngrok URL).
**2. Local Server Processes Request:**
Your Python script receives the POST request and the chat\_completions function is invoked.
**3. Extract and Prepare Data:**
The script parses the JSON data, extracts relevant information (prompt, conversation history), and builds the prompt for the OpenAI API call.
**4. Call to OpenAI API:**
The constructed prompt is sent to the gpt-4.1-mini model using the openai.ChatCompletion.create method.
**5. Receive and Format Response:**
The response from OpenAI, containing the generated text, is received and formatted according to Vapi's expected structure.
**6. Send Response to Vapi:**
The formatted response is sent back to Vapi as a JSON object.
**7. Vapi Displays Response:**
Vapi receives the response and displays the generated text within the conversation interface to the user.
By following these detailed steps and understanding the communication flow, you can successfully connect Vapi to OpenAI's gpt-4.1-mini model and create powerful conversational experiences within your Vapi applications. The provided code example and reference serve as a starting point for you to build and customize your integration based on your specific needs.
**Video Tutorial:**
# Custom LLM Tool Calling Integration
## What Is a Custom LLM and Why Use It?
A **Custom LLM** is more than just a text generator—it’s a conversational assistant that can call external functions, trigger processes, and handle special logic, all while chatting with your users. Think of it as your smart helper that not only answers questions but also takes actions.
**Why use a Custom LLM?**
* **Enhanced Functionality:** It mixes natural language responses with actionable functions.
* **Flexibility:** You can combine built-in functions, attach external tools via Vapi, or even add custom endpoints.
* **Dynamic Interactions:** The assistant can return structured instructions—like transferring a call or running a custom process—when needed.
* **Seamless Integration:** Vapi lets you plug these custom endpoints into your assistant quickly and easily.
***
## Setting Up Your Custom LLM for Response Generation
Before adding tool calls, let’s start with the basics: setting up your Custom LLM to simply generate conversation responses. In this mode, your LLM receives conversation details, asks the model for a reply, and streams that text back.
### How It Works
* **Request Reception:** Your endpoint (e.g., `/chat/completions`) gets a payload with the model, messages, temperature, and (optionally) tools.
* **Content Generation:** The code builds an OpenAI API request that includes the conversation context.
* **Response Streaming:** The generated reply is sent back as Server-Sent Events (SSE).
### Sample Code Snippet
```typescript
app.post("/chat/completions", async (req: Request, res: Response) => {
// Log the incoming request.
logEvent("Request received at /chat/completions", req.body);
const payload = req.body;
// Prepare the API request to OpenAI.
const requestArgs: any = {
model: payload.model,
messages: payload.messages,
temperature: payload.temperature ?? 1.0,
stream: true,
tools: payload.tools || [],
tool_choice: "auto",
};
// Optionally merge in native tool definitions.
const modelTools = payload.tools || [];
requestArgs.tools = [...modelTools, ...ourTools];
logEvent("Calling OpenAI API for content generation");
const openAIResponse = await openai.chat.completions.create(requestArgs);
logEvent("OpenAI API call successful. Streaming response.");
// Set up streaming headers.
res.setHeader("Content-Type", "text/event-stream");
res.setHeader("Cache-Control", "no-cache");
res.setHeader("Connection", "keep-alive");
// Stream the response chunks back.
for await (const chunk of openAIResponse as unknown as AsyncIterable) {
res.write(`data: ${JSON.stringify(chunk)}\n\n`);
}
res.write("data: [DONE]\n\n");
res.end();
});
```
### Attaching Custom LLM Without Tools to an Existing Assistant in Vapi
If you just want response generation (without tool calls), update your Vapi model with a PATCH request like this:
```bash
curl -X PATCH https://api.vapi.ai/assistant/insert-your-assistant-id-here \
-H "Authorization: Bearer insert-your-private-key-here" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "custom-llm",
"model": "gpt-4o",
"url": "https://custom-llm-url/chat/completions",
"messages": [
{
"role": "system",
"content": "[TASK] Ask the user if they want to transfer the call; if not, continue the conversation."
}
]
},
"transcriber": {
"provider": "azure",
"language": "en-CA"
}
}'
```
***
## Adding Tools Calling with Your Custom LLM
Now that you’ve got response generation working, let’s expand your assistant’s abilities. Your Custom LLM can trigger external actions in three different ways.
### a. Native LLM Tools
These tools are built right into your LLM integration. For example, a native function like `get_payment_link` can return a payment URL.
**How It Works:**
1. **Detection:** The LLM’s streaming response includes a tool call for `get_payment_link`.
2. **Execution:** The integration parses the arguments and calls the native function.
3. **Response:** The result is packaged into a follow-up API call and streamed back.
**Code Snippet:**
```typescript
// Variables to accumulate tool call information.
let argumentsStr = "";
let toolCallInfo: { name?: string; id?: string } | null = null;
// Process streaming chunks.
for await (const chunk of openAIResponse as unknown as AsyncIterable) {
const choice = chunk.choices && chunk.choices[0];
const delta = choice?.delta || {};
const toolCalls = delta.tool_calls;
if (toolCalls && toolCalls.length > 0) {
for (const toolCall of toolCalls) {
const func = toolCall.function;
if (func && func.name) {
toolCallInfo = { name: func.name, id: toolCall.id };
}
if (func && func.arguments) {
argumentsStr += func.arguments;
}
}
}
const finishReason = choice?.finish_reason;
if (finishReason === "tool_calls" && toolCallInfo) {
let parsedArgs = {};
try {
parsedArgs = JSON.parse(argumentsStr);
} catch (err) {
console.error("Failed to parse arguments:", err);
}
if (tool_functions[toolCallInfo.name!]) {
const result = await tool_functions[toolCallInfo.name!](parsedArgs);
const functionMessage = {
role: "function",
name: toolCallInfo.name,
content: JSON.stringify(result)
};
const followUpResponse = await openai.chat.completions.create({
model: requestArgs.model,
messages: [...requestArgs.messages, functionMessage],
temperature: requestArgs.temperature,
stream: true,
tools: requestArgs.tools,
tool_choice: "auto"
});
for await (const followUpChunk of followUpResponse) {
res.write(`data: ${JSON.stringify(followUpChunk)}\n\n`);
}
argumentsStr = "";
toolCallInfo = null;
continue;
}
}
res.write(`data: ${JSON.stringify(chunk)}\n\n`);
}
```
### b. Vapi-Attached Tools
These tools come pre-attached via your Vapi configuration. For example, the `transferCall` tool:
**How It Works:**
1. **Detection:** When a tool call for `transferCall` appears with a destination in the payload, the function isn’t executed.
2. **Response:** The integration immediately sends a function call payload with the destination back to Vapi.
**Code Snippet:**
```typescript
if (functionName === "transferCall" && payload.destination) {
const functionCallPayload = {
function_call: {
name: "transferCall",
arguments: {
destination: payload.destination,
},
},
};
logEvent("Special handling for transferCall", { functionCallPayload });
res.write(`data: ${JSON.stringify(functionCallPayload)}\n\n`);
// Skip further processing for this chunk.
continue;
}
```
### c. Custom Tools
Custom tools are unique to your application and are handled by a dedicated endpoint. For example, a custom function named `processOrder`.
**How It Works:**
1. **Dedicated Endpoint:** Requests for custom tools go to `/chat/completions/custom-tool`.
2. **Detection:** The payload includes a tool call list. If the function name is `"processOrder"`, a hardcoded result is returned.
3. **Response:** A JSON response is sent back with the result.
**Code Snippet (Custom Endpoint):**
```typescript
app.post("/chat/completions/custom-tool", async (req: Request, res: Response) => {
logEvent("Received request at /chat/completions/custom-tool", req.body);
// Expect the payload to have a "message" with a "toolCallList" array.
const vapiPayload = req.body.message;
// Process tool call.
for (const toolCall of vapiPayload.toolCallList) {
if (toolCall.function?.name === "processOrder") {
const hardcodedResult = "CustomTool processOrder With CustomLLM Always Works";
logEvent("Returning hardcoded result for 'processOrder'", { toolCallId: toolCall.id });
return res.json({
results: [
{
toolCallId: toolCall.id,
result: hardcodedResult,
},
],
});
}
}
});
```
***
## Testing Tool Calling with cURL
Once your endpoints are set up, try testing them with these cURL commands.
### a. Native Tool Calling (`get_payment_link`)
```bash
curl -X POST https://custom-llm-url/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "user", "content": "I need a payment link."}
],
"temperature": 0.7,
"tools": [
{
"type": "function",
"function": {
"name": "get_payment_link",
"description": "Get a payment link",
"parameters": {}
}
}
]
}'
```
*Expected Response:*\
Streaming chunks eventually include the result (e.g., a payment link) returned by the native tool function.
### b. Vapi-Attached Tool Calling (`transferCall`)
```bash
curl -X POST https://custom-llm-url/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [
{"role": "user", "content": "Please transfer my call."}
],
"temperature": 0.7,
"tools": [
{
"type": "function",
"function": {
"name": "transferCall",
"description": "Transfer call to a specified destination",
"parameters": {}
}
}
],
"destination": "555-1234"
}'
```
*Expected Response:*\
Immediately returns a function call payload that instructs Vapi to transfer the call to the specified destination.
### c. Custom Tool Calling (`processOrder`)
```bash
curl -X POST https://custom-llm-url/chat/completions/custom-tool \
-H "Content-Type: application/json" \
-d '{
"message": {
"toolCallList": [
{
"id": "12345",
"function": {
"name": "processOrder",
"arguments": {
"param": "value"
}
}
}
]
}
}'
```
*Expected Response:*
```json
{
"results": [
{
"toolCallId": "12345",
"result": "CustomTools With CustomLLM Always Works"
}
]
}
```
***
## Integrating Tools with Vapi
After testing locally, integrate your Custom LLM with Vapi. Choose the configuration that fits your needs.
### a. Without Tools (Response Generation Only)
```bash
curl -X PATCH https://api.vapi.ai/assistant/insert-your-assistant-id-here \
-H "Authorization: Bearer insert-your-private-key-here" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "custom-llm",
"model": "gpt-4o",
"url": "https://custom-llm-url/chat/completions",
"messages": [
{
"role": "system",
"content": "[TASK] Ask the user if they want to transfer the call; if not, continue chatting."
}
]
},
"transcriber": {
"provider": "azure",
"language": "en-CA"
}
}'
```
### b. With Tools (Including `transferCall` and `processOrder`)
```bash
curl -X PATCH https://api.vapi.ai/assistant/insert-your-assistant-id-here \
-H "Authorization: Bearer insert-your-private-key-here" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "custom-llm",
"model": "gpt-4o",
"url": "https://custom-llm-url/chat/completions",
"messages": [
{
"role": "system",
"content": "[TASK] Ask the user if they want to transfer the call; if they agree, trigger the transferCall tool; if not, continue the conversation. Also, if the user asks about the custom function processOrder, trigger that tool."
}
],
"tools": [
{
"type": "transferCall",
"destinations": [
{
"type": "number",
"number": "+xxxxxx",
"numberE164CheckEnabled": false,
"message": "Transferring Call To Customer Service Department"
}
]
},
{
"type": "function",
"async": false,
"function": {
"name": "processOrder",
"description": "it's a custom tool function named processOrder according to vapi.ai custom tools guide"
},
"server": {
"url": "https://custom-llm-url/chat/completions/custom-tool"
}
}
]
},
"transcriber": {
"provider": "azure",
"language": "en-CA"
}
}'
```
***
## Conclusion
A Custom LLM turns a basic conversational assistant into an interactive helper that can:
* **Generate everyday language responses,**
* **Call native tools** (like fetching a payment link),
* **Use Vapi-attached tools** (like transferring a call), and
* **Leverage custom tools** (like processing orders).
By building each layer step by step and testing with cURL, you can fine-tune your integration before rolling it out in production.
***
## Complete Code
For your convenience, you can find the complete source code for this Custom LLM integration here:
**[Custom LLM with Vapi Integration – Complete Code](https://codesandbox.io/p/devbox/gfwztp)**
```
```
# Inbound customer support
> Build a voice AI banking support agent with tools for account lookup, balance and transaction retrieval.
## Overview
Build a banking support agent with function tools, CSV knowledge bases, and voice test suites. The agent handles account verification, balance inquiries, and transaction history via phone calls.
**Agent Capabilities:**
* Account lookup and verification via phone number
* Balance and transaction history retrieval
**What You'll Build:**
* Retrieval tools and CSV knowledge bases for account/transaction data
* Voice test suites for automated quality assurance
* Inbound phone number configuration for 24/7 availability
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
## Scenario
We will be creating a customer support agent for VapiBank, a bank that wants to provide 24/7 support to consumers.
***
## 1. Create a Knowledge Base
1. Navigate to **Files** in your [Vapi Dashboard](https://dashboard.vapi.ai/)
2. Click **Choose file** and upload both `accounts.csv` and `transactions.csv`
3. Note the file IDs for use in creating tools
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
import fs from 'fs';
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function uploadFile(filePath: string) {
try {
const file = await vapi.files.create({
file: fs.createReadStream(filePath)
});
console.log(`File ${filePath} uploaded with ID: ${file.id}`);
return file;
} catch (error) {
console.error(`Error uploading file ${filePath}:`, error);
throw error;
}
}
// Upload both files
const accountsFile = await uploadFile("accounts.csv");
const transactionsFile = await uploadFile("transactions.csv");
console.log(`Accounts file ID: ${accountsFile.id}`);
console.log(`Transactions file ID: ${transactionsFile.id}`);
```
```python
import requests
def upload_file(file_path):
url = "https://api.vapi.ai/file"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
return response.json()
# Upload both files
accounts_file = upload_file("accounts.csv")
transactions_file = upload_file("transactions.csv")
print(f"Accounts file ID: {accounts_file['id']}")
print(f"Transactions file ID: {transactions_file['id']}")
```
```bash
# Upload accounts.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@accounts.csv"
# Upload transactions.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@transactions.csv"
```
***
## 2. Create an Assistant
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and click `Assistants` in the left sidebar.
* Click `Create Assistant`.
* Select `Blank Template` as your starting point.
* Change assistant name to `Tom`.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const systemPrompt = `You are Tom, a friendly VapiBank customer support assistant. Help customers check balances and view recent transactions. Always verify identity with phone number first.`;
const assistant = await vapi.assistants.create({
name: "Tom",
firstMessage: "Hello, you've reached VapiBank customer support! My name is Tom, how may I assist you today?",
model: {
provider: "openai",
model: "gpt-4o",
messages: [
{
role: "system",
content: systemPrompt
}
]
},
voice: {
provider: "11labs",
voice_id: "burt"
}
});
console.log(`Assistant created with ID: ${assistant.id}`);
```
```python
import requests
url = "https://api.vapi.ai/assistant"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
system_prompt = "You are Tom, a friendly VapiBank customer support assistant. Help customers check balances and view recent transactions. Always verify identity with phone number first."
data = {
"name": "Tom",
"firstMessage": "Hello, you've reached VapiBank customer support! My name is Tom, how may I assist you today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": system_prompt
}
]
},
"voice": {
"provider": "11labs",
"voice_id": "burt"
}
}
response = requests.post(url, headers=headers, json=data)
assistant = response.json()
print(f"Assistant created with ID: {assistant['id']}")
```
```bash
curl -X POST https://api.vapi.ai/assistant \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Tom",
"firstMessage": "Hello, you'\''ve reached VapiBank customer support! My name is Tom, how may I assist you today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are Tom, a friendly VapiBank customer support assistant. Help customers check balances and view recent transactions. Always verify identity with phone number first."
}
]
},
"voice": {
"provider": "11labs",
"voice_id": "burt"
}
}'
```
***
## 3. Configure an Assistant
Update `First Message` to:
```txt title="First Message" wordWrap
Hello, you've reached VapiBank customer support! My name is Tom, how may I assist you today?
```
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const updatedAssistant = await vapi.assistants.update("YOUR_ASSISTANT_ID", {
firstMessage: "Hello, you've reached VapiBank customer support! My name is Tom, how may I assist you today?"
});
console.log("First message updated successfully");
```
```python
import requests
url = f"https://api.vapi.ai/assistant/{YOUR_ASSISTANT_ID}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"firstMessage": "Hello, you've reached VapiBank customer support! My name is Tom, how may I assist you today?"
}
response = requests.patch(url, headers=headers, json=data)
assistant = response.json()
print("First message updated successfully")
```
```bash
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstMessage": "Hello, you'\''ve reached VapiBank customer support! My name is Tom, how may I assist you today?"
}'
```
First, create this system prompt:
```txt title="System Prompt" maxLines=10
# VapiBank - Phone Support Agent Prompt
## Identity & Purpose
You are **Tom**, VapiBank's friendly, 24x7 phone-support voice assistant. Do not introduce yourself after the first message.
You help customers with account inquiries:
1. **Check balance**
2. **View recent transactions**
## Data Sources
You have access to CSV files with account and transaction data:
- **accounts.csv**: `account_id, name, phone_last4, balance, card_status, email`
- **transactions.csv**: transaction history for all accounts
## Available Tools
1. **lookup_account** → verify customer identity using phone number
2. **get_balance** → returns current balance for verified account
3. **get_recent_transactions** → returns recent transaction history
## Conversation Flow
1. **Greeting**
> "Hello, you've reached VapiBank customer support! My name is Tom, how may I assist you today?"
2. **Account Verification**
* After caller provides phone digits → call **lookup_account**
* Read back the returned `name` for confirmation
* If no match after 2 tries → apologize and offer to transfer
3. **Handle Request**
Ask: "How can I help you today—check your balance or review recent transactions?"
**Balance** → call **get_balance** → read current balance
**Transactions** → call **get_recent_transactions** → summarize recent activity
4. **Close**
> "Is there anything else I can help you with today?"
If no → thank the caller and end the call
## Style & Tone
* Warm, concise, ≤ 30 words per reply
* One question at a time
* Repeat important numbers slowly and clearly
* Professional but friendly tone
## Edge Cases
* **No account match** → offer to transfer to human agent
* **Multiple requests** → handle each request, then ask if anything else needed
* **Technical issues** → apologize and offer callback or transfer
(Remember: only share account information with verified account holders.)
```
Then update your assistant:
Copy the system prompt above and paste it into the `System Prompt` field in your assistant configuration.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Use the system prompt from above
const systemPrompt = `# VapiBank - Phone Support Agent Prompt...`;
const updatedAssistant = await vapi.assistants.update("YOUR_ASSISTANT_ID", {
model: {
messages: [
{
role: "system",
content: systemPrompt
}
]
}
});
console.log("System prompt updated successfully");
```
```python
import requests
url = f"https://api.vapi.ai/assistant/{YOUR_ASSISTANT_ID}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
# Use the system prompt from above
system_prompt = """# VapiBank - Phone Support Agent Prompt..."""
data = {
"model": {
"messages": [
{
"role": "system",
"content": system_prompt
}
]
}
}
response = requests.patch(url, headers=headers, json=data)
assistant = response.json()
print("System prompt updated successfully")
```
```bash
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"messages": [
{
"role": "system",
"content": "# VapiBank - Phone Support Agent Prompt\n\n## Identity & Purpose\nYou are **Tom**, VapiBank'\''s friendly, 24x7 phone-support voice assistant. Do not introduce yourself after the first message.\nYou help customers with account inquiries:\n\n1. **Check balance**\n2. **View recent transactions**\n\n## Data Sources\nYou have access to CSV files with account and transaction data:\n- **accounts.csv**: account_id, name, phone_last4, balance, card_status, email\n- **transactions.csv**: transaction history for all accounts\n\n## Available Tools\n1. **lookup_account** → verify customer identity using phone number\n2. **get_balance** → returns current balance for verified account\n3. **get_recent_transactions** → returns recent transaction history\n\n## Conversation Flow\n1. **Greeting**\n > \"Hello, you'\''ve reached VapiBank customer support! My name is Tom, how may I assist you today?\"\n\n2. **Account Verification**\n * After caller provides phone digits → call **lookup_account**\n * Read back the returned name for confirmation\n * If no match after 2 tries → apologize and offer to transfer\n\n3. **Handle Request**\n Ask: \"How can I help you today—check your balance or review recent transactions?\"\n\n **Balance** → call **get_balance** → read current balance\n **Transactions** → call **get_recent_transactions** → summarize recent activity\n\n4. **Close**\n > \"Is there anything else I can help you with today?\"\n If no → thank the caller and end the call\n\n## Style & Tone\n* Warm, concise, ≤ 30 words per reply\n* One question at a time\n* Repeat important numbers slowly and clearly\n* Professional but friendly tone\n\n## Edge Cases\n* **No account match** → offer to transfer to human agent\n* **Multiple requests** → handle each request, then ask if anything else needed\n* **Technical issues** → apologize and offer callback or transfer\n\n(Remember: only share account information with verified account holders.)"
}
]
}
}'
```
Configure the LLM settings to your liking.
* Select any provider and model you like (you will see cost and latency estimates).
* You can configure the files available to the LLM as knowledge base.
* You can specify the temperature and max tokens of the LLM.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function updateAssistantLLMSettings(assistantId: string) {
const updatedAssistant = await vapi.assistants.update(assistantId, {
model: {
provider: "openai",
model: "gpt-4o",
temperature: 0.7,
maxTokens: 150,
messages: [
{
role: "system",
content: "You are Tom, VapiBank's customer support assistant..."
}
]
}
});
return updatedAssistant;
}
// Update LLM settings
const assistant = await updateAssistantLLMSettings('YOUR_ASSISTANT_ID');
console.log('Assistant LLM settings updated');
```
```python
import requests
def update_assistant_llm_settings(assistant_id):
url = f"https://api.vapi.ai/assistant/{assistant_id}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"model": {
"provider": "openai",
"model": "gpt-4o",
"temperature": 0.7,
"maxTokens": 150,
"messages": [
{
"role": "system",
"content": "You are Tom, VapiBank's customer support assistant..."
}
]
}
}
response = requests.patch(url, headers=headers, json=data)
return response.json()
# Update LLM settings
assistant = update_assistant_llm_settings('YOUR_ASSISTANT_ID')
print("Assistant LLM settings updated")
```
```bash
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "openai",
"model": "gpt-4o",
"temperature": 0.7,
"maxTokens": 150,
"messages": [
{
"role": "system",
"content": "You are Tom, VapiBank'\''s customer support assistant..."
}
]
}
}'
```
**Dashboard only:** Click `Publish` to save your changes.
When using the Server SDKs, changes are applied immediately when you make API calls. There's no separate "publish" step required.
Click `Talk to Assistant` to test it out.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function testAssistantWithCall(assistantId: string) {
const call = await vapi.calls.create({
assistantId: assistantId,
customer: {
number: "+1234567890" // Your test number
}
});
console.log(`Test call created: ${call.id}`);
return call;
}
// Create a test call
const testCall = await testAssistantWithCall('YOUR_ASSISTANT_ID');
```
```python
import requests
def test_assistant_with_call(assistant_id):
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"assistantId": assistant_id,
"customer": {
"number": "+1234567890" # Your test number
}
}
response = requests.post(url, headers=headers, json=data)
call = response.json()
print(f"Test call created: {call['id']}")
return call
# Create a test call
test_call = test_assistant_with_call('YOUR_ASSISTANT_ID')
```
```bash
# Create a test call
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "YOUR_ASSISTANT_ID",
"customer": {
"number": "+1234567890"
}
}'
```
***
## 4. Add Tools to an Assistant
Open your [dashboard.vapi.ai](https://dashboard.vapi.ai) and click `Tools` in the left sidebar.
* Click `Create Tool`.
* Select `Function` as your tool type.
* Change tool name to `get_balance`.
* Add the following function description:
```txt title="Function Description" wordWrap
Retrieve the balance for an account based on provided account holder name and last 4 digits of the phone number.
```
* Scroll down to the `Knowledge Bases` section and add the following knowledge base:
* Name: `accounts`
Description: `Use this to retrieve account information`
File IDs: ``
* Click `Create Tool`.
* Select `Function` as your tool type.
* Change tool name to `get_recent_transactions`.
* Add the following function description:
```txt title="Function Description" wordWrap
Return the three most recent transactions for a specific account.
```
* Scroll down to the `Knowledge Bases` section and add the following knowledge bases:
* Name: `accounts`
Description: `Use this to retrieve account information`
File IDs: ``
* Name: `transactions`
Description: `Use this to retrieve transactions`
File IDs: ``
* Click `Create Tool`.
* Select `Function` as your tool type.
* Change tool name to `lookup_account`.
* Add the following function description:
```txt title="Function Description" wordWrap
Look up account based on provided name and last 4 digits of the phone number.
```
* Scroll down to the `Knowledge Bases` section and add the following knowledge bases:
* Name: `accounts`
Description: `Use this to retrieve account information`
File IDs: ``
* Click `Assistants` in the left sidebar.
* Make sure `Tom` is selected in the list of assistants.
* Scroll down until you see `Tools` accordion. Expand it.
* In the expanded accordion, add `get_balance` and `get_recent_transactions` tools.
* Click `Publish` to save your changes.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Step 1: Create the account lookup tool
const lookupAccountTool = await vapi.tools.create({
type: "function",
function: {
name: "lookup_account",
description: "Look up account based on provided name and last 4 digits of the phone number."
},
knowledgeBases: [
{
name: "accounts",
description: "Use this to retrieve account information",
fileIds: ["YOUR_ACCOUNTS_FILE_ID"]
}
]
});
console.log(`Created lookup_account tool: ${lookupAccountTool.id}`);
// Step 2: Create the balance retrieval tool
const getBalanceTool = await vapi.tools.create({
type: "function",
function: {
name: "get_balance",
description: "Retrieve the balance for an account based on provided account holder name and last 4 digits of the phone number."
},
knowledgeBases: [
{
name: "accounts",
description: "Use this to retrieve account information",
fileIds: ["YOUR_ACCOUNTS_FILE_ID"]
}
]
});
console.log(`Created get_balance tool: ${getBalanceTool.id}`);
// Step 3: Create the transactions retrieval tool
const getTransactionsTool = await vapi.tools.create({
type: "function",
function: {
name: "get_recent_transactions",
description: "Return the three most recent transactions for a specific account."
},
knowledgeBases: [
{
name: "accounts",
description: "Use this to retrieve account information",
fileIds: ["YOUR_ACCOUNTS_FILE_ID"]
},
{
name: "transactions",
description: "Use this to retrieve transactions",
fileIds: ["YOUR_TRANSACTIONS_FILE_ID"]
}
]
});
console.log(`Created get_recent_transactions tool: ${getTransactionsTool.id}`);
// Step 4: Add all tools to the assistant
const updatedAssistant = await vapi.assistants.update("YOUR_ASSISTANT_ID", {
model: {
toolIds: [
lookupAccountTool.id,
getBalanceTool.id,
getTransactionsTool.id
]
}
});
console.log("All tools added to assistant successfully!");
```
```python
import requests
# Helper function to create tools
def create_tool(name, description, knowledge_bases):
url = "https://api.vapi.ai/tool"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"type": "function",
"function": {
"name": name,
"description": description
},
"knowledgeBases": knowledge_bases
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Step 1: Create the account lookup tool
lookup_account_tool = create_tool(
"lookup_account",
"Look up account based on provided name and last 4 digits of the phone number.",
[{"name": "accounts", "description": "Use this to retrieve account information", "fileIds": ["YOUR_ACCOUNTS_FILE_ID"]}]
)
print(f"Created lookup_account tool: {lookup_account_tool['id']}")
# Step 2: Create the balance retrieval tool
get_balance_tool = create_tool(
"get_balance",
"Retrieve the balance for an account based on provided account holder name and last 4 digits of the phone number.",
[{"name": "accounts", "description": "Use this to retrieve account information", "fileIds": ["YOUR_ACCOUNTS_FILE_ID"]}]
)
print(f"Created get_balance tool: {get_balance_tool['id']}")
# Step 3: Create the transactions retrieval tool
get_transactions_tool = create_tool(
"get_recent_transactions",
"Return the three most recent transactions for a specific account.",
[
{"name": "accounts", "description": "Use this to retrieve account information", "fileIds": ["YOUR_ACCOUNTS_FILE_ID"]},
{"name": "transactions", "description": "Use this to retrieve transactions", "fileIds": ["YOUR_TRANSACTIONS_FILE_ID"]}
]
)
print(f"Created get_recent_transactions tool: {get_transactions_tool['id']}")
# Step 4: Add all tools to the assistant
def update_assistant_with_tools(assistant_id, tool_ids):
url = f"https://api.vapi.ai/assistant/{assistant_id}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"model": {
"toolIds": tool_ids
}
}
response = requests.patch(url, headers=headers, json=data)
return response.json()
tool_ids = [lookup_account_tool['id'], get_balance_tool['id'], get_transactions_tool['id']]
updated_assistant = update_assistant_with_tools("YOUR_ASSISTANT_ID", tool_ids)
print("All tools added to assistant successfully!")
```
```bash
# Step 1: Create the account lookup tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "lookup_account",
"description": "Look up account based on provided name and last 4 digits of the phone number."
},
"knowledgeBases": [
{
"name": "accounts",
"description": "Use this to retrieve account information",
"fileIds": ["YOUR_ACCOUNTS_FILE_ID"]
}
]
}'
# Step 2: Create the balance retrieval tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "get_balance",
"description": "Retrieve the balance for an account based on provided account holder name and last 4 digits of the phone number."
},
"knowledgeBases": [
{
"name": "accounts",
"description": "Use this to retrieve account information",
"fileIds": ["YOUR_ACCOUNTS_FILE_ID"]
}
]
}'
# Step 3: Create the transactions retrieval tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "get_recent_transactions",
"description": "Return the three most recent transactions for a specific account."
},
"knowledgeBases": [
{
"name": "accounts",
"description": "Use this to retrieve account information",
"fileIds": ["YOUR_ACCOUNTS_FILE_ID"]
},
{
"name": "transactions",
"description": "Use this to retrieve transactions",
"fileIds": ["YOUR_TRANSACTIONS_FILE_ID"]
}
]
}'
# Step 4: Add all tools to the assistant
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"toolIds": ["LOOKUP_ACCOUNT_TOOL_ID", "GET_BALANCE_TOOL_ID", "GET_TRANSACTIONS_TOOL_ID"]
}
}'
```
***
## 5. Assign a Phone Number to an Assistant
Open your [dashboard.vapi.ai](https://dashboard.vapi.ai) and click `Phone Numbers` in the left sidebar.
* Click `Create Phone Number`.
* Stick with `Free Vapi Number`.
* Enter your preferred area code (e.g. `530`).
* Set the `Phone Number Name` to `Vapi Support Hotline`.
* Under `Inbound Settings` find `Assistant` dropdown and select `Tom` from the list.
* Changes are saved automatically.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const phoneNumber = await vapi.phoneNumbers.create({
name: "Vapi Support Hotline",
assistantId: "YOUR_ASSISTANT_ID"
});
console.log(`Phone number created: ${phoneNumber.number}`);
```
```python
import requests
def create_phone_number(name, assistant_id):
url = "https://api.vapi.ai/phone-number"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": name,
"assistantId": assistant_id
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Create phone number for Tom
phone_number = create_phone_number("Vapi Support Hotline", assistant_id)
print(f"Phone number created: {phone_number['number']}")
```
```bash
# Create a phone number
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Vapi Support Hotline",
"assistantId": "YOUR_ASSISTANT_ID"
}'
```
***
## 6. Create a Test Suite for an Assistant
* Open your [dashboard.vapi.ai](https://dashboard.vapi.ai).
* Below the `Build` section, find and expand the `Test` section.
* In the expanded section, click `Voice Test Suites`.
* On the `Test Suites` page, click `Create Test Suite`.
* Click on `New Test Suite` and change the name to `Support Hotline Test Suite`.
* Set the `Assistant` to `Tom`.
* Set the `Phone Number` to `Vapi Support Hotline`.
* Under `Test Cases`, click `Generate Tests`.
* Use the following prompt to generate the test case:
```txt title="Test Case Prompt" wordWrap
Test that the assistant can verify a customer account using phone number, retrieve their current balance, and provide recent transaction history.
```
* Accept the generated test case.
* Click `Run Test Suite` to execute the tests.
Click `Run Tests` to execute the tests.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const testSuite = await vapi.testSuites.create({
name: "Support Hotline Test Suite",
assistantId: "YOUR_ASSISTANT_ID",
phoneNumberId: "YOUR_PHONE_NUMBER_ID",
testCases: [
{
name: "Account verification and balance check",
description: "Test that the assistant can verify a customer account using phone number, retrieve their current balance, and provide recent transaction history.",
steps: [
{
type: "userMessage",
content: "Hi, I need to check my account balance"
},
{
type: "assertion",
condition: "Assistant asks for phone number verification"
},
{
type: "userMessage",
content: "My phone number ends in 1234"
},
{
type: "assertion",
condition: "Assistant provides balance information"
}
]
}
]
});
console.log(`Test suite created with ID: ${testSuite.id}`);
```
**Next:** Go to your [Vapi Dashboard](https://dashboard.vapi.ai) → Test → Voice Test Suites to run the test suite and view results.
```python
import requests
def create_test_suite():
url = "https://api.vapi.ai/test-suite"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "Support Hotline Test Suite",
"assistantId": "YOUR_ASSISTANT_ID",
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"testCases": [
{
"name": "Account verification and balance check",
"description": "Test that the assistant can verify a customer account using phone number, retrieve their current balance, and provide recent transaction history.",
"steps": [
{
"type": "userMessage",
"content": "Hi, I need to check my account balance"
},
{
"type": "assertion",
"condition": "Assistant asks for phone number verification"
},
{
"type": "userMessage",
"content": "My phone number ends in 1234"
},
{
"type": "assertion",
"condition": "Assistant provides balance information"
}
]
}
]
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Create the test suite
test_suite = create_test_suite()
print(f"Test suite created with ID: {test_suite['id']}")
```
**Next:** Go to your [Vapi Dashboard](https://dashboard.vapi.ai) → Test → Voice Test Suites to run the test suite and view results.
```bash
# Create the test suite
curl -X POST https://api.vapi.ai/test-suite \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Hotline Test Suite",
"assistantId": "YOUR_ASSISTANT_ID",
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"testCases": [
{
"name": "Account verification and balance check",
"description": "Test that the assistant can verify a customer account using phone number, retrieve their current balance, and provide recent transaction history.",
"steps": [
{
"type": "userMessage",
"content": "Hi, I need to check my account balance"
},
{
"type": "assertion",
"condition": "Assistant asks for phone number verification"
},
{
"type": "userMessage",
"content": "My phone number ends in 1234"
},
{
"type": "assertion",
"condition": "Assistant provides balance information"
}
]
}
]
}'
```
**Next:** Go to your [Vapi Dashboard](https://dashboard.vapi.ai) → Test → Voice Test Suites to run the test suite and view results.
## Next Steps
Just like that, you've built a 24/7 customer support hotline that can handle inbound calls, create support tickets, and run automated tests to ensure it's working as expected.
Consider the reading the following guides to further enhance your assistant:
* [**Knowledge Bases**](../knowledge-base/) - Learn more about knowledge bases to build knowledge-based agents.
* [**External Integrations**](../tools/) - Configure integrations with [Google Calendar](../tools/google-calendar), [Google Sheets](../tools/google-sheets), [Slack](../tools/slack), etc.
* [**Workflows**](../workflows/) - Learn about workflows to build voice agents for more complex use cases.
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Web Snippet
> Easily integrate the Vapi Voice Widget into your website for enhanced user interaction.
Improve your website's user interaction with the Vapi Voice Widget. This robust tool enables your visitors to engage with a voice assistant for support and interaction, offering a smooth and contemporary way to connect with your services.
## Quick Implementation
Choose your preferred implementation method:
The fastest way to get started. Copy this snippet into your website:
```html
```
Install the SDK and create a React component:
```bash title="npm"
npm install @vapi-ai/web
```
```bash title="yarn"
yarn add @vapi-ai/web
```
```bash title="pnpm"
pnpm add @vapi-ai/web
```
```bash title="bun"
bun add @vapi-ai/web
```
```tsx
import React, { useState, useEffect } from 'react';
import Vapi from '@vapi-ai/web';
interface VapiWidgetProps {
apiKey: string;
assistantId: string;
config?: Record;
}
const VapiWidget: React.FC = ({
apiKey,
assistantId,
config = {}
}) => {
const [vapi, setVapi] = useState(null);
const [isConnected, setIsConnected] = useState(false);
const [isSpeaking, setIsSpeaking] = useState(false);
const [transcript, setTranscript] = useState>([]);
useEffect(() => {
const vapiInstance = new Vapi(apiKey);
setVapi(vapiInstance);
// Event listeners
vapiInstance.on('call-start', () => {
console.log('Call started');
setIsConnected(true);
});
vapiInstance.on('call-end', () => {
console.log('Call ended');
setIsConnected(false);
setIsSpeaking(false);
});
vapiInstance.on('speech-start', () => {
console.log('Assistant started speaking');
setIsSpeaking(true);
});
vapiInstance.on('speech-end', () => {
console.log('Assistant stopped speaking');
setIsSpeaking(false);
});
vapiInstance.on('message', (message) => {
if (message.type === 'transcript') {
setTranscript(prev => [...prev, {
role: message.role,
text: message.transcript
}]);
}
});
vapiInstance.on('error', (error) => {
console.error('Vapi error:', error);
});
return () => {
vapiInstance?.stop();
};
}, [apiKey]);
const startCall = () => {
if (vapi) {
vapi.start(assistantId);
}
};
const endCall = () => {
if (vapi) {
vapi.stop();
}
};
return (
);
};
export default VapiWidget;
// Usage in your app:
//
```
### Custom Styling
You can customize the widget appearance by modifying the styles in the React component:
```tsx
// Custom button styles
const customButtonStyle = {
background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
borderRadius: '25px',
padding: '12px 30px',
fontSize: '14px',
fontWeight: '600',
boxShadow: '0 4px 15px rgba(102, 126, 234, 0.4)',
};
// Custom panel styles
const customPanelStyle = {
background: 'linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%)',
borderRadius: '16px',
border: '2px solid #e1e8ed',
backdropFilter: 'blur(10px)',
};
```
### Event Handling
Listen to various events for custom functionality:
```tsx
import Vapi from '@vapi-ai/web';
function setupAdvancedVoiceWidget(apiKey: string, assistantId: string) {
const vapi = new Vapi(apiKey);
// Call lifecycle events
vapi.on('call-start', () => {
console.log('Voice conversation started');
// Track analytics, show notifications, etc.
});
vapi.on('call-end', () => {
console.log('Voice conversation ended');
// Save conversation data, show feedback form, etc.
});
// Real-time conversation events
vapi.on('speech-start', () => {
console.log('User started speaking');
});
vapi.on('speech-end', () => {
console.log('User stopped speaking');
});
vapi.on('message', (message) => {
if (message.type === 'transcript') {
console.log(`${message.role}: ${message.transcript}`);
// Update UI with real-time transcription
} else if (message.type === 'function-call') {
console.log('Function called:', message.functionCall.name);
// Handle custom function calls
}
});
// Error handling
vapi.on('error', (error) => {
console.error('Voice widget error:', error);
// Show user-friendly error messages
});
return {
start: () => vapi.start(assistantId),
stop: () => vapi.stop(),
send: (message: string) => vapi.send({
type: 'add-message',
message: {
role: 'user',
content: message
}
})
};
}
```
### Integration Examples
**E-commerce Support Widget:**
```tsx
const EcommerceSupportWidget = () => {
return (
);
};
```
**Healthcare Appointment Widget:**
```tsx
const HealthcareWidget = () => {
return (
);
};
```
# Documentation agent
> Build a voice assistant that answers questions about your docs
Try our live implementation using the voice widget in the bottom-right corner of this page.
## Overview
Build a voice-powered documentation assistant step by step. Choose between using the Dashboard interface or programmatic APIs to suit your workflow.
You'll learn to:
* Index your docs with LlamaCloud
* Create a RAG tool for document retrieval
* Create an assistant with Claude 3.5 Sonnet and attach the tool
* Use the Web SDK to create a widget
* Analyze user sessions and improve the quality of your agent overtime
## Prerequisites
* [Vapi account](https://dashboard.vapi.ai/) with API access
* Documentation content - `llms.txt` file ([example](https://docs.vapi.ai/llms.txt)) could work great; it could be available out-of-box with your documentation framework (e.g. [Fern](https://buildwithfern.com/learn/docs/developer-tools/llms-txt), [Mintlify](https://mintlify.com/docs/ai-ingestion#%2Fllms-full-txt))
* [LlamaCloud account](https://cloud.llamaindex.ai/) for indexing
## Get started
Upload and index your documentation in LlamaCloud using `text-embedding-3-small`.
1. Create a new project in LlamaCloud
2. Upload your documentation files (you can use a single consolidated file like [llms-full.txt](https://docs.vapi.ai/llms-full.txt))
3. Configure embedding model to `text-embedding-3-small`
4. Set chunking to 512 tokens with 50 token overlap
5. Note your index ID and API credentials
Consolidate your documentation into a single text file for better RAG performance. You can see our example at [docs.vapi.ai/llms-full.txt](https://docs.vapi.ai/llms-full.txt).
Create a tool that connects your assistant to your LlamaCloud index.
1. Navigate to **Tools** in your [Vapi Dashboard](https://dashboard.vapi.ai/)
2. Click **Create Tool**
3. Select **API Request** as the tool type
4. Configure the tool:
* **Name**: `docsquery`
* **Function Name**: `docsquery`
* **Description**: `Search through documentation to find relevant information`
* **URL**: `https://api.cloud.llamaindex.ai/api/v1/pipelines/YOUR_PIPELINE_ID/retrieve`
* **Method**: `POST`
* **Headers**: Add `Authorization: Bearer YOUR_LLAMACLOUD_API_KEY`
* **Body**: Configure to send the query parameter
5. Save the tool and note the tool ID
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
// Initialize Vapi server SDK
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Create the documentation query tool
const tool = await vapi.tools.create({
type: "function",
function: {
name: "docsquery",
parameters: {
type: "object",
properties: {
query: {
type: "string",
description: "The search query to find relevant documentation"
}
},
required: ["query"]
}
},
server: {
// LlamaCloud API endpoint for your pipeline
url: `https://api.cloud.llamaindex.ai/api/v1/pipelines/${YOUR_PIPELINE_ID}/retrieve`,
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${YOUR_LLAMACLOUD_API_KEY}`
},
// Send user query to LlamaCloud
body: {
query: "{{query}}"
}
}
});
console.log(`Tool created with ID: ${tool.id}`);
```
```python
from vapi import Vapi
# Initialize Vapi server SDK
client = Vapi(token="YOUR_VAPI_API_KEY")
# Define system prompt for documentation assistant
system_prompt = """You are a helpful documentation assistant. Use the docsquery tool to find relevant information when users ask questions about the documentation.
Guidelines:
- Always be helpful, friendly, and concise
- Provide accurate information based on the documentation
- When you don't know something, say so clearly
- Keep responses conversational for voice interaction
- Use the docsquery tool whenever users ask specific questions about features, setup, or implementation
- Summarize complex information in an easy-to-understand way
- Ask clarifying questions if the user's request is unclear
- Provide step-by-step guidance when explaining processes"""
# Create the documentation assistant
assistant = client.assistants.create(
name="Docs agent",
model={
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022", # Valid Claude model
"maxTokens": 400,
"messages": [
{
"role": "system",
"content": system_prompt
}
],
"toolIds": [YOUR_TOOL_ID_FROM_STEP_2] # Replace with actual tool ID
},
// Configure voice settings
voice={
"provider": "vapi",
"voice_id": "Harry"
},
// Configure transcription
transcriber={
"provider": "deepgram",
"model": "nova-2",
"language": "en"
},
// Set greeting message
first_message="Hey I'm Harry, a support agent. How can I help you today? You can ask me questions about Vapi, how to get started or our documentation.",
end_call_message="Goodbye.",
background_sound="off",
// Enable call analysis for continuous improvement
analysis_plan={
"summaryPlan": {
"enabled": True,
"prompt": "Summarize this documentation support call, focusing on the user's questions and how well they were answered."
},
"successEvaluationPlan": {
"enabled": True,
"prompt": "Evaluate if this documentation support call was successful. Did the user get helpful answers to their questions?",
"rubric": "NumericScale"
}
}
)
print(f"Assistant created with ID: {assistant.id}")
```
```bash
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "apiRequest",
"name": "docsquery",
"function": {
"name": "docsquery",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query to find relevant documentation"
}
},
"required": ["query"]
}
},
"url": "https://api.cloud.llamaindex.ai/api/v1/pipelines/YOUR_PIPELINE_ID/retrieve",
"method": "POST",
"headers": {
"type": "object",
"properties": {
"Content-Type": {
"type": "string",
"value": "application/json"
},
"Authorization": {
"type": "string",
"value": "Bearer YOUR_LLAMACLOUD_API_KEY"
}
}
},
"body": {
"type": "object",
"properties": {
"query": {
"type": "string",
"value": "{{query}}"
}
}
}
}'
```
Replace `YOUR_PIPELINE_ID` with your LlamaCloud pipeline ID and `YOUR_LLAMACLOUD_API_KEY` with your API key. Save the tool ID from the response for the next step.
Create an assistant with the RAG tool attached.
1. Navigate to **Assistants** in your [Vapi Dashboard](https://dashboard.vapi.ai/)
2. Click **Create Assistant**
3. Configure the assistant:
* **Name**: `Docs agent`
* **Model**: Claude Sonnet 4 (Anthropic)
* **Voice**: Harry (Vapi)
* **First Message**: `Hey I'm Harry, a support agent. How can I help you today? You can ask me questions about Vapi, how to get started or our documentation.`
* **System Prompt**: Use a helpful documentation assistant prompt with guidelines for using the docsquery tool
4. Add the `docsquery` tool in the Tools section
5. Configure analysis plan for call monitoring
6. Publish the assistant
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
// Initialize Vapi server SDK
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Define system prompt for documentation assistant
const systemPrompt = `You are a helpful documentation assistant. Use the docsquery tool to find relevant information when users ask questions about the documentation.
Guidelines:
- Always be helpful, friendly, and concise
- Provide accurate information based on the documentation
- When you don't know something, say so clearly
- Keep responses conversational for voice interaction
- Use the docsquery tool whenever users ask specific questions about features, setup, or implementation
- Summarize complex information in an easy-to-understand way
- Ask clarifying questions if the user's request is unclear
- Provide step-by-step guidance when explaining processes`;
// Create the documentation assistant
const assistant = await vapi.assistants.create({
name: "Docs agent",
model: {
provider: "anthropic",
model: "claude-3-5-sonnet-20241022", # Valid Claude model
maxTokens: 400,
messages: [
{
role: "system",
content: systemPrompt
}
],
toolIds: [YOUR_TOOL_ID_FROM_STEP_2] // Replace with actual tool ID
},
// Configure voice settings
voice: {
provider: "vapi",
voice_id: "Harry"
},
// Configure transcription
transcriber: {
provider: "deepgram",
model: "nova-2",
language: "en"
},
// Set greeting message
firstMessage: "Hey I'm Harry, a support agent. How can I help you today? You can ask me questions about Vapi, how to get started or our documentation.",
endCallMessage: "Goodbye.",
backgroundSound: "off",
// Enable call analysis for continuous improvement
analysisPlan: {
summaryPlan: {
enabled: true,
prompt: "Summarize this documentation support call, focusing on the user's questions and how well they were answered."
},
successEvaluationPlan: {
enabled: true,
prompt: "Evaluate if this documentation support call was successful. Did the user get helpful answers to their questions?",
rubric: "NumericScale"
}
}
});
console.log(`Assistant created with ID: ${assistant.id}`);
```
```python
from vapi import Vapi
# Initialize Vapi server SDK
client = Vapi(token="YOUR_VAPI_API_KEY")
# Define system prompt for documentation assistant
system_prompt = """You are a helpful documentation assistant. Use the docsquery tool to find relevant information when users ask questions about the documentation.
Guidelines:
- Always be helpful, friendly, and concise
- Provide accurate information based on the documentation
- When you don't know something, say so clearly
- Keep responses conversational for voice interaction
- Use the docsquery tool whenever users ask specific questions about features, setup, or implementation
- Summarize complex information in an easy-to-understand way
- Ask clarifying questions if the user's request is unclear
- Provide step-by-step guidance when explaining processes"""
# Create the documentation assistant
assistant = client.assistants.create(
name="Docs agent",
model={
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022", # Valid Claude model
"maxTokens": 400,
"messages": [
{
"role": "system",
"content": system_prompt
}
],
"toolIds": [YOUR_TOOL_ID_FROM_STEP_2] # Replace with actual tool ID
},
// Configure voice settings
voice={
"provider": "vapi",
"voice_id": "Harry"
},
// Configure transcription
transcriber={
"provider": "deepgram",
"model": "nova-2",
"language": "en"
},
// Set greeting message
first_message="Hey I'm Harry, a support agent. How can I help you today? You can ask me questions about Vapi, how to get started or our documentation.",
end_call_message="Goodbye.",
background_sound="off",
// Enable call analysis for continuous improvement
analysis_plan={
"summaryPlan": {
"enabled": True,
"prompt": "Summarize this documentation support call, focusing on the user's questions and how well they were answered."
},
"successEvaluationPlan": {
"enabled": True,
"prompt": "Evaluate if this documentation support call was successful. Did the user get helpful answers to their questions?",
"rubric": "NumericScale"
}
}
)
print(f"Assistant created with ID: {assistant.id}")
```
```bash
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "apiRequest",
"name": "docsquery",
"function": {
"name": "docsquery",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query to find relevant documentation"
}
},
"required": ["query"]
}
},
"url": "https://api.cloud.llamaindex.ai/api/v1/pipelines/YOUR_PIPELINE_ID/retrieve",
"method": "POST",
"headers": {
"type": "object",
"properties": {
"Content-Type": {
"type": "string",
"value": "application/json"
},
"Authorization": {
"type": "string",
"value": "Bearer YOUR_LLAMACLOUD_API_KEY"
}
}
},
"body": {
"type": "object",
"properties": {
"query": {
"type": "string",
"value": "{{query}}"
}
}
}
}'
```
Replace `YOUR_PIPELINE_ID` with your LlamaCloud pipeline ID and `YOUR_LLAMACLOUD_API_KEY` with your API key. Save the tool ID from the response for the next step.
Customize your assistant's behavior and responses after creation.
1. Navigate to your assistant in the [Vapi Dashboard](https://dashboard.vapi.ai/)
2. Edit any properties like system prompt, first message, or voice settings
3. Changes apply immediately - no republishing needed
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Update the assistant's first message
const updatedAssistant = await vapi.assistants.update("YOUR_ASSISTANT_ID", {
firstMessage: "Hello! I'm your documentation assistant. What would you like to know about our platform?",
// Update system prompt for better responses
model: {
provider: "anthropic",
model: "claude-3-5-sonnet-20241022",
messages: [
{
role: "system",
content: "Enhanced system prompt with more specific guidelines for documentation assistance"
}
]
}
});
console.log("Assistant updated successfully");
```
```python
import requests
# Update assistant properties
url = f"https://api.vapi.ai/assistant/{YOUR_ASSISTANT_ID}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
# Update first message and system prompt
data = {
"firstMessage": "Hello! I'\''m your documentation assistant. What would you like to know about our platform?",
"model": {
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "system",
"content": "Enhanced system prompt with more specific guidelines for documentation assistance"
}
]
}
}
response = requests.patch(url, headers=headers, json=data)
print("Assistant updated successfully")
```
```bash
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"firstMessage": "Hello! I'\''m your documentation assistant. What would you like to know about our platform?",
"model": {
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "system",
"content": "Enhanced system prompt with more specific guidelines for documentation assistance"
}
]
}
}'
```
SDK changes apply immediately. Unlike Dashboard publishing, programmatic updates take effect right away.
Create test scenarios to validate your documentation assistant's responses.
1. Navigate to **Test** > **Voice Test Suites** in your dashboard
2. Click **Create Test Suite**
3. Add test scenarios with expected behaviors
4. Run tests to validate assistant performance
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Create test suite for documentation assistant
const testSuite = await vapi.testSuites.create({
name: "Documentation Assistant Tests",
assistantId: "YOUR_ASSISTANT_ID",
testCases: [
{
name: "Basic greeting test",
scenario: "User says hello",
expectedBehavior: "Assistant responds with greeting and asks how to help"
},
{
name: "Documentation query test",
scenario: "User asks about API endpoints",
expectedBehavior: "Assistant uses docsquery tool and provides relevant information"
},
{
name: "Unknown topic test",
scenario: "User asks about unrelated topic",
expectedBehavior: "Assistant politely redirects to documentation topics"
}
]
});
console.log(`Test suite created with ID: ${testSuite.id}`);
console.log("Next: Go to Dashboard to run the test suite");
```
```python
import requests
# Create test suite for documentation assistant
url = "https://api.vapi.ai/test-suite"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "Documentation Assistant Tests",
"assistantId": "YOUR_ASSISTANT_ID",
"testCases": [
{
"name": "Basic greeting test",
"scenario": "User says hello",
"expectedBehavior": "Assistant responds with greeting and asks how to help"
},
{
"name": "Documentation query test",
"scenario": "User asks about API endpoints",
"expectedBehavior": "Assistant uses docsquery tool and provides relevant information"
},
{
"name": "Unknown topic test",
"scenario": "User asks about unrelated topic",
"expectedBehavior": "Assistant politely redirects to documentation topics"
}
]
}
response = requests.post(url, headers=headers, json=data)
test_suite = response.json()
print(f"Test suite created with ID: {test_suite['id']}")
print("Next: Go to Dashboard to run the test suite")
```
```bash
curl -X POST https://api.vapi.ai/test-suite \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Documentation Assistant Tests",
"assistantId": "YOUR_ASSISTANT_ID",
"testCases": [
{
"name": "Basic greeting test",
"scenario": "User says hello",
"expectedBehavior": "Assistant responds with greeting and asks how to help"
},
{
"name": "Documentation query test",
"scenario": "User asks about API endpoints",
"expectedBehavior": "Assistant uses docsquery tool and provides relevant information"
},
{
"name": "Unknown topic test",
"scenario": "User asks about unrelated topic",
"expectedBehavior": "Assistant politely redirects to documentation topics"
}
]
}'
```
Test suites can only be executed through the Dashboard. Navigate to **Test** > **Voice Test Suites** to run your created tests.
Use the Vapi Web SDK to create a voice widget for your documentation assistant.
```bash title="npm"
npm install @vapi-ai/web
```
```bash title="yarn"
yarn add @vapi-ai/web
```
```bash title="pnpm"
pnpm add @vapi-ai/web
```
```bash title="bun"
bun add @vapi-ai/web
```
Replace `YOUR_PUBLIC_API_KEY` and `YOUR_ASSISTANT_ID` with your actual values:
```typescript
import { useState, useEffect } from 'react';
import Vapi from '@vapi-ai/web';
export default function VoiceWidget() {
const [vapi, setVapi] = useState(null);
const [isConnected, setIsConnected] = useState(false);
const [transcript, setTranscript] = useState([]);
useEffect(() => {
// Initialize Vapi Web SDK for client-side voice interactions
const vapiInstance = new Vapi('YOUR_PUBLIC_API_KEY');
setVapi(vapiInstance);
// Handle call lifecycle events
vapiInstance.on('call-start', () => setIsConnected(true));
vapiInstance.on('call-end', () => setIsConnected(false));
// Handle real-time conversation messages
vapiInstance.on('message', (msg) => {
if (msg.type === 'transcript') {
setTranscript(prev => [...prev, { role: msg.role, text: msg.transcript }]);
}
});
// Cleanup on component unmount
return () => vapiInstance?.stop();
}, []);
// Start voice conversation with documentation assistant
const startCall = () => vapi?.start('YOUR_ASSISTANT_ID');
const endCall = () => vapi?.stop();
return (
{!isConnected ? (
) : (
{transcript.map((msg, i) => (
{msg.text}
))}
)}
);
}
```
For a complete implementation with waveform visualization, real-time transcripts, and responsive design, check out our [voice widget component](https://github.com/VapiAI/docs/blob/7879817ad2789d5929842cecff4ef3f4ec82acae/fern/widget/voice-widget.tsx) on GitHub.
Vapi automatically analyzes every call. The assistant above includes an [`analysisPlan`](/api-reference/assistants/create#request.body.analysisPlan) with summary and success evaluation configured.
1. Navigate to **Logs** > **Calls** in your dashboard
2. Click on any completed call to view analysis
3. Review summary and success evaluation
4. Use insights to improve your assistant's prompts and responses
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Retrieve call analysis for continuous improvement
async function getCallAnalysis(callId: string) {
try {
const call = await vapi.calls.get(callId);
if (call.analysis) {
console.log("Call Summary:", call.analysis.summary);
console.log("Success Score:", call.analysis.successEvaluation);
// Use analysis data to improve prompts
return {
summary: call.analysis.summary,
successScore: call.analysis.successEvaluation,
improvements: extractImprovements(call.analysis)
};
}
} catch (error) {
console.error("Error fetching call analysis:", error);
}
return call;
}
// Extract improvement suggestions from analysis
function extractImprovements(analysis: any) {
// Analyze patterns to suggest prompt improvements
return {
promptSuggestions: "Based on call analysis...",
commonQueries: "Users frequently ask about...",
successFactors: "Successful calls typically..."
};
}
// Get analysis for a specific call
const analysis = await getCallAnalysis("CALL_ID");
```
```python
import requests
def get_call_analysis(call_id):
"""Retrieve and analyze call data for continuous improvement"""
url = f"https://api.vapi.ai/call/{call_id}"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
try:
response = requests.get(url, headers=headers)
call_data = response.json()
if 'analysis' in call_data:
print("Call Summary:", call_data['analysis']['summary'])
print("Success Score:", call_data['analysis']['successEvaluation'])
# Extract insights for improvement
return {
'summary': call_data['analysis']['summary'],
'success_score': call_data['analysis']['successEvaluation'],
'improvements': extract_improvements(call_data['analysis'])
}
except Exception as error:
print(f"Error fetching call analysis: {error}")
return call_data
def extract_improvements(analysis):
"""Extract improvement suggestions from analysis data"""
return {
'prompt_suggestions': "Based on call analysis...",
'common_queries': "Users frequently ask about...",
'success_factors': "Successful calls typically..."
}
# Get analysis for a specific call
analysis = get_call_analysis("CALL_ID")
```
Retrieve analysis results using the Get Call API:
```bash
curl https://api.vapi.ai/call/CALL_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY"
```
**Iterative improvements:**
* Review analysis summaries to identify common user questions
* Use structured data to track conversation patterns
* Monitor success evaluations to optimize assistant performance
* Update your system prompt based on recurring issues
* Refine RAG retrieval based on query success patterns
Learn advanced prompting techniques to optimize your documentation agent's responses and behavior.
# Customer support escalation system
> Build a voice AI customer support system with dynamic escalation that routes calls based on customer data, issue type, and real-time agent availability using transfer tools and webhooks.
## Overview
Build an intelligent customer support escalation system that determines transfer destinations dynamically using customer tier analysis, issue complexity assessment, and real-time agent availability. This approach uses transfer tools with empty destinations and webhook servers for maximum escalation flexibility.
**Agent Capabilities:**
* Customer tier-based prioritization and routing
* Issue complexity analysis for specialist routing
* Real-time agent availability and expertise matching
* Intelligent escalation with context preservation
**What You'll Build:**
* Transfer tool with dynamic escalation logic
* Assistant with intelligent support conversation flow
* Webhook server for escalation destination logic
* CRM integration for customer tier-based routing
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/)
* Node.js or Python server environment
* (Optional) CRM or customer database for tier lookup
## Scenario
We will build a customer support escalation system for TechCorp that intelligently routes support calls based on customer tier, issue complexity, and agent expertise in real-time.
***
## 1. Create a Dynamic Escalation Tool
In your Vapi dashboard, click **Tools** in the left sidebar.
* Click **Create Tool**
* Select **Transfer Call** as the tool type
* Set tool name: `Smart Support Escalation`
* **Important**: Leave the destinations array empty - this creates a dynamic transfer tool
* Set function name: `escalateToSupport`
* Add description: `Escalate calls to appropriate support specialists based on customer tier and issue complexity`
Add these parameters to help the assistant provide context:
* `issue_category` (string): Category of customer issue (technical, billing, account, product)
* `complexity_level` (string): Issue complexity (basic, intermediate, advanced, critical)
* `customer_context` (string): Relevant customer information for routing
* `escalation_reason` (string): Why this needs escalation vs self-service
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: process.env.VAPI_API_KEY });
async function createSupportEscalationTool() {
try {
const tool = await vapi.tools.create({
type: "transferCall",
// Empty destinations array makes this a dynamic transfer tool
destinations: [],
function: {
name: "escalateToSupport",
description: "Escalate calls to appropriate support specialists based on customer tier and issue complexity",
parameters: {
type: "object",
properties: {
issue_category: {
type: "string",
description: "Category of customer issue",
enum: ["technical", "billing", "account", "product"]
},
complexity_level: {
type: "string",
description: "Issue complexity level",
enum: ["basic", "intermediate", "advanced", "critical"]
},
customer_context: {
type: "string",
description: "Relevant customer information for routing"
},
escalation_reason: {
type: "string",
description: "Why this needs escalation vs self-service"
}
},
required: ["issue_category", "complexity_level"]
}
}
});
console.log(`Support escalation tool created: ${tool.id}`);
return tool;
} catch (error) {
console.error('Error creating support escalation tool:', error);
throw error;
}
}
// Create the support escalation tool
const escalationTool = await createSupportEscalationTool();
```
```python
import os
import requests
def create_support_escalation_tool():
"""Create a dynamic support escalation tool with empty destinations"""
url = "https://api.vapi.ai/tool"
headers = {
"Authorization": f"Bearer {os.getenv('VAPI_API_KEY')}",
"Content-Type": "application/json"
}
data = {
"type": "transferCall",
# Empty destinations array makes this a dynamic transfer tool
"destinations": [],
"function": {
"name": "escalateToSupport",
"description": "Escalate calls to appropriate support specialists based on customer tier and issue complexity",
"parameters": {
"type": "object",
"properties": {
"issue_category": {
"type": "string",
"description": "Category of customer issue",
"enum": ["technical", "billing", "account", "product"]
},
"complexity_level": {
"type": "string",
"description": "Issue complexity level",
"enum": ["basic", "intermediate", "advanced", "critical"]
},
"customer_context": {
"type": "string",
"description": "Relevant customer information for routing"
},
"escalation_reason": {
"type": "string",
"description": "Why this needs escalation vs self-service"
}
},
"required": ["issue_category", "complexity_level"]
}
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
tool = response.json()
print(f"Support escalation tool created: {tool['id']}")
return tool
except requests.exceptions.RequestException as error:
print(f"Error creating support escalation tool: {error}")
raise
# Create the support escalation tool
escalation_tool = create_support_escalation_tool()
```
```bash
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "transferCall",
"destinations": [],
"function": {
"name": "escalateToSupport",
"description": "Escalate calls to appropriate support specialists based on customer tier and issue complexity",
"parameters": {
"type": "object",
"properties": {
"issue_category": {
"type": "string",
"description": "Category of customer issue",
"enum": ["technical", "billing", "account", "product"]
},
"complexity_level": {
"type": "string",
"description": "Issue complexity level",
"enum": ["basic", "intermediate", "advanced", "critical"]
},
"customer_context": {
"type": "string",
"description": "Relevant customer information for routing"
},
"escalation_reason": {
"type": "string",
"description": "Why this needs escalation vs self-service"
}
},
"required": ["issue_category", "complexity_level"]
}
}
}'
```
***
## 2. Create an Assistant with Smart Escalation
* Navigate to **Assistants** in your dashboard
* Click **Create Assistant**
* Name: `TechCorp Support Assistant`
* Add your dynamic escalation tool to the assistant's tools
```txt title="System Prompt" maxLines=15
You are TechCorp's intelligent customer support assistant. Your job is to:
1. Help customers resolve issues when possible
2. Assess issue complexity and customer needs
3. Escalate to human specialists when appropriate using the escalateToSupport function
Try to resolve simple issues first. For complex issues or when customers request human help, escalate intelligently based on:
- Issue category (technical, billing, account, product)
- Complexity level (basic, intermediate, advanced, critical)
- Customer context and history
Always be professional and efficient in your support.
```
In assistant settings, enable the **transfer-destination-request** server event. This sends webhooks to your server when escalations are triggered.
Configure your server URL to handle escalation requests (e.g., `https://your-app.com/webhook/escalation`)
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: process.env.VAPI_API_KEY });
async function createSupportAssistant(escalationToolId: string) {
try {
const assistant = await vapi.assistants.create({
name: "TechCorp Support Assistant",
firstMessage: "Hello! I'm here to help with your TechCorp support needs. I can assist with account questions, technical issues, billing inquiries, and more. What can I help you with today?",
model: {
provider: "openai",
model: "gpt-4o",
messages: [
{
role: "system",
content: `You are TechCorp's intelligent customer support assistant. Your job is to:
1. Help customers resolve issues when possible
2. Assess issue complexity and customer needs
3. Escalate to human specialists when appropriate using the escalateToSupport function
Try to resolve simple issues first. For complex issues or when customers request human help, escalate intelligently based on:
- Issue category (technical, billing, account, product)
- Complexity level (basic, intermediate, advanced, critical)
- Customer context and history
Always be professional and efficient in your support.`
}
],
toolIds: [escalationToolId]
},
voice: {
provider: "11labs",
voiceId: "burt"
},
serverUrl: "https://your-app.com/webhook/escalation",
serverUrlSecret: process.env.WEBHOOK_SECRET
});
console.log(`Support assistant created: ${assistant.id}`);
return assistant;
} catch (error) {
console.error('Error creating support assistant:', error);
throw error;
}
}
// Create assistant with escalation capabilities
const supportAssistant = await createSupportAssistant("YOUR_ESCALATION_TOOL_ID");
```
```python
import os
import requests
def create_support_assistant(escalation_tool_id):
"""Create assistant with dynamic escalation capabilities"""
url = "https://api.vapi.ai/assistant"
headers = {
"Authorization": f"Bearer {os.getenv('VAPI_API_KEY')}",
"Content-Type": "application/json"
}
data = {
"name": "TechCorp Support Assistant",
"firstMessage": "Hello! I'\''m here to help with your TechCorp support needs. I can assist with account questions, technical issues, billing inquiries, and more. What can I help you with today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": """You are TechCorp's intelligent customer support assistant. Your job is to:
1. Help customers resolve issues when possible
2. Assess issue complexity and customer needs
3. Escalate to human specialists when appropriate using the escalateToSupport function
Try to resolve simple issues first. For complex issues or when customers request human help, escalate intelligently based on:
- Issue category (technical, billing, account, product)
- Complexity level (basic, intermediate, advanced, critical)
- Customer context and history
Always be professional and efficient in your support."""
}
],
"toolIds": [escalation_tool_id]
},
"voice": {
"provider": "11labs",
"voiceId": "burt"
},
"serverUrl": "https://your-app.com/webhook/escalation",
"serverUrlSecret": os.getenv("WEBHOOK_SECRET")
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
assistant = response.json()
print(f"Support assistant created: {assistant['id']}")
return assistant
except requests.exceptions.RequestException as error:
print(f"Error creating support assistant: {error}")
raise
# Create assistant with escalation capabilities
support_assistant = create_support_assistant("YOUR_ESCALATION_TOOL_ID")
```
```bash
curl -X POST https://api.vapi.ai/assistant \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "TechCorp Support Assistant",
"firstMessage": "Hello! I'\''m here to help with your TechCorp support needs. I can assist with account questions, technical issues, billing inquiries, and more. What can I help you with today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are TechCorp'\''s intelligent customer support assistant. Your job is to:\n\n1. Help customers resolve issues when possible\n2. Assess issue complexity and customer needs\n3. Escalate to human specialists when appropriate using the escalateToSupport function\n\nTry to resolve simple issues first. For complex issues or when customers request human help, escalate intelligently based on:\n- Issue category (technical, billing, account, product)\n- Complexity level (basic, intermediate, advanced, critical)\n- Customer context and history\n\nAlways be professional and efficient in your support."
}
],
"toolIds": ["YOUR_ESCALATION_TOOL_ID"]
},
"voice": {
"provider": "11labs",
"voiceId": "burt"
},
"serverUrl": "https://your-app.com/webhook/escalation",
"serverUrlSecret": "your-webhook-secret"
}'
```
***
## 3. Build Escalation Logic Server
```typescript
import express from 'express';
import crypto from 'crypto';
const app = express();
app.use(express.json());
// Webhook secret verification
function verifyWebhookSignature(payload: string, signature: string) {
const expectedSignature = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET!)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// Support escalation logic
function determineSupportDestination(request: any) {
const { functionCall, call, customer } = request;
const { issue_category, complexity_level, customer_context, escalation_reason } = functionCall.parameters;
// Simulate customer tier lookup
const customerData = lookupCustomerTier(customer.number);
// Enterprise customer escalation
if (customerData?.tier === 'enterprise' || complexity_level === 'critical') {
return {
type: "number",
number: "+1-555-ENTERPRISE-SUPPORT",
message: "Connecting you to our enterprise support specialist.",
transferPlan: {
mode: "warm-transfer-say-summary",
summaryPlan: {
enabled: true,
messages: [
{
role: "system",
content: "Provide a summary for the enterprise support specialist."
},
{
role: "user",
content: `Enterprise customer with ${issue_category} issue. Complexity: ${complexity_level}. Reason: ${escalation_reason}. Context: ${customer_context}`
}
]
}
}
};
}
// Advanced technical issues
if (issue_category === 'technical' && (complexity_level === 'advanced' || complexity_level === 'intermediate')) {
return {
type: "number",
number: "+1-555-TECH-SPECIALISTS",
message: "Transferring you to our technical support specialists.",
transferPlan: {
mode: "warm-transfer-say-message",
message: `Technical ${complexity_level} issue. Customer context: ${customer_context}. Escalation reason: ${escalation_reason}`
}
};
}
// Billing and account specialists
if (issue_category === 'billing' || issue_category === 'account') {
return {
type: "number",
number: "+1-555-BILLING-TEAM",
message: "Connecting you with our billing and account specialists.",
transferPlan: {
mode: "warm-transfer-say-message",
message: `${issue_category} issue, complexity ${complexity_level}. Context: ${customer_context}`
}
};
}
// Product and feature questions
if (issue_category === 'product') {
return {
type: "number",
number: "+1-555-PRODUCT-SUPPORT",
message: "Transferring you to our product specialists.",
transferPlan: {
mode: "warm-transfer-say-message",
message: `Product ${complexity_level} inquiry. Context: ${customer_context}`
}
};
}
// Default to general support
return {
type: "number",
number: "+1-555-GENERAL-SUPPORT",
message: "Connecting you with our support team.",
transferPlan: {
mode: "warm-transfer-say-message",
message: `General ${issue_category} support needed. Level: ${complexity_level}`
}
};
}
// Simulate customer tier lookup
function lookupCustomerTier(phoneNumber: string) {
// In production, integrate with your actual CRM
const mockCustomerData = {
"+1234567890": { tier: "enterprise", account: "TechCorp Enterprise" },
"+0987654321": { tier: "standard", account: "Basic Plan" },
"+1111111111": { tier: "premium", account: "Premium Support" }
};
return mockCustomerData[phoneNumber];
}
// Support escalation webhook
app.post('/webhook/escalation', (req, res) => {
try {
const signature = req.headers['x-vapi-signature'] as string;
const payload = JSON.stringify(req.body);
// Verify webhook signature
if (!verifyWebhookSignature(payload, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const request = req.body;
// Only handle transfer destination requests
if (request.type !== 'transfer-destination-request') {
return res.status(200).json({ received: true });
}
// Determine destination based on escalation context
const destination = determineSupportDestination(request);
res.json({ destination });
} catch (error) {
console.error('Escalation webhook error:', error);
res.status(500).json({
error: 'Unable to determine escalation destination. Please try again.'
});
}
});
app.listen(3000, () => {
console.log('Support escalation server running on port 3000');
});
```
```python
import os
import hmac
import hashlib
from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel
from typing import Optional, Dict, Any
app = FastAPI()
def verify_webhook_signature(payload: bytes, signature: str) -> bool:
"""Verify webhook signature"""
webhook_secret = os.getenv('WEBHOOK_SECRET', '').encode()
expected_signature = hmac.new(
webhook_secret,
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)
def lookup_customer_tier(phone_number: str) -> Optional[Dict[str, Any]]:
"""Simulate customer tier lookup"""
mock_customer_data = {
"+1234567890": {"tier": "enterprise", "account": "TechCorp Enterprise"},
"+0987654321": {"tier": "standard", "account": "Basic Plan"},
"+1111111111": {"tier": "premium", "account": "Premium Support"}
}
return mock_customer_data.get(phone_number)
def determine_support_destination(request_data: Dict[str, Any]) -> Dict[str, Any]:
"""Determine support escalation destination based on request context"""
function_call = request_data.get('functionCall', {})
parameters = function_call.get('parameters', {})
customer = request_data.get('customer', {})
issue_category = parameters.get('issue_category', 'general')
complexity_level = parameters.get('complexity_level', 'basic')
customer_context = parameters.get('customer_context', '')
escalation_reason = parameters.get('escalation_reason', '')
# Simulate customer tier lookup
customer_data = lookup_customer_tier(customer.get('number', ''))
# Enterprise customer escalation
if (customer_data and customer_data.get('tier') == 'enterprise') or complexity_level == 'critical':
return {
"type": "number",
"number": "+1-555-ENTERPRISE-SUPPORT",
"message": "Connecting you to our enterprise support specialist.",
"transferPlan": {
"mode": "warm-transfer-say-summary",
"summaryPlan": {
"enabled": True,
"messages": [
{
"role": "system",
"content": "Provide a summary for the enterprise support specialist."
},
{
"role": "user",
"content": f"Enterprise customer with {issue_category} issue. Complexity: {complexity_level}. Reason: {escalation_reason}. Context: {customer_context}"
}
]
}
}
}
# Advanced technical issues
if issue_category == 'technical' and complexity_level in ['advanced', 'intermediate']:
return {
"type": "number",
"number": "+1-555-TECH-SPECIALISTS",
"message": "Transferring you to our technical support specialists.",
"transferPlan": {
"mode": "warm-transfer-say-message",
"message": f"Technical {complexity_level} issue. Customer context: {customer_context}. Escalation reason: {escalation_reason}"
}
}
# Billing and account specialists
if issue_category in ['billing', 'account']:
return {
"type": "number",
"number": "+1-555-BILLING-TEAM",
"message": "Connecting you with our billing and account specialists.",
"transferPlan": {
"mode": "warm-transfer-say-message",
"message": f"{issue_category} issue, complexity {complexity_level}. Context: {customer_context}"
}
}
# Product and feature questions
if issue_category == 'product':
return {
"type": "number",
"number": "+1-555-PRODUCT-SUPPORT",
"message": "Transferring you to our product specialists.",
"transferPlan": {
"mode": "warm-transfer-say-message",
"message": f"Product {complexity_level} inquiry. Context: {customer_context}"
}
}
# Default to general support
return {
"type": "number",
"number": "+1-555-GENERAL-SUPPORT",
"message": "Connecting you with our support team.",
"transferPlan": {
"mode": "warm-transfer-say-message",
"message": f"General {issue_category} support needed. Level: {complexity_level}"
}
}
@app.post("/webhook/escalation")
async def handle_escalation_webhook(request: Request):
try:
# Get raw body for signature verification
body = await request.body()
signature = request.headers.get('x-vapi-signature', '')
# Verify webhook signature
if not verify_webhook_signature(body, signature):
raise HTTPException(status_code=401, detail="Invalid signature")
# Parse request body
request_data = await request.json()
# Only handle transfer destination requests
if request_data.get('type') != 'transfer-destination-request':
return {"received": True}
# Determine destination based on escalation context
destination = determine_support_destination(request_data)
return {"destination": destination}
except Exception as error:
print(f"Escalation webhook error: {error}")
raise HTTPException(
status_code=500,
detail="Unable to determine escalation destination. Please try again."
)
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=3000)
```
***
## 4. Test Your Support Escalation System
* Navigate to **Phone Numbers** in your dashboard
* Click **Create Phone Number**
* Assign your support assistant to the number
* Configure any additional settings
Call your number and test various scenarios:
* Basic technical questions (should try to resolve first)
* Complex billing issues from enterprise customers
* Advanced technical problems requiring specialists
* Critical issues requiring immediate escalation
Check your server logs to see:
* Escalation requests received
* Customer tier classifications
* Destination routing decisions
* Any errors or routing issues
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: process.env.VAPI_API_KEY });
async function testSupportEscalation(assistantId: string) {
try {
// Test enterprise customer with complex issue
const enterpriseCall = await vapi.calls.create({
assistantId: assistantId,
customer: {
number: "+1234567890", // Enterprise customer in your lookup
name: "Enterprise Customer - Technical Issue"
}
});
console.log(`Enterprise test call created: ${enterpriseCall.id}`);
// Test standard customer with billing question
const standardCall = await vapi.calls.create({
assistantId: assistantId,
customer: {
number: "+0987654321", // Standard customer in your lookup
name: "Standard Customer - Billing Question"
}
});
console.log(`Standard test call created: ${standardCall.id}`);
return { enterpriseCall, standardCall };
} catch (error) {
console.error('Error creating test calls:', error);
throw error;
}
}
// Test the support escalation system
const testCalls = await testSupportEscalation('YOUR_ASSISTANT_ID');
```
```python
import requests
import os
def test_support_escalation(assistant_id):
"""Test support escalation with different customer scenarios"""
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {os.getenv('VAPI_API_KEY')}",
"Content-Type": "application/json"
}
test_scenarios = [
{
"name": "Enterprise Technical Issue",
"customer": {
"number": "+1234567890", # Enterprise customer
"name": "Enterprise Customer - Technical Issue"
}
},
{
"name": "Standard Billing Question",
"customer": {
"number": "+0987654321", # Standard customer
"name": "Standard Customer - Billing Question"
}
}
]
results = []
for scenario in test_scenarios:
try:
data = {
"assistantId": assistant_id,
**scenario
}
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
call = response.json()
print(f"{scenario['name']} call created: {call['id']}")
results.append(call)
except requests.exceptions.RequestException as error:
print(f"Error creating {scenario['name']}: {error}")
return results
# Test the support escalation system
test_calls = test_support_escalation('YOUR_ASSISTANT_ID')
```
## Advanced Integration Examples
### CRM Integration (Salesforce)
```typescript
// Example: Salesforce CRM integration for customer tier lookup
async function lookupCustomerInSalesforce(phoneNumber: string) {
const salesforce = new SalesforceAPI({
clientId: process.env.SALESFORCE_CLIENT_ID,
clientSecret: process.env.SALESFORCE_CLIENT_SECRET,
redirectUri: process.env.SALESFORCE_REDIRECT_URI
});
try {
const customer = await salesforce.query(`
SELECT Id, Account.Type, Support_Tier__c, Case_Count__c, Contract_Level__c
FROM Contact
WHERE Phone = '${phoneNumber}'
`);
return customer.records[0];
} catch (error) {
console.error('Salesforce lookup failed:', error);
return null;
}
}
```
### Issue Complexity Assessment
```typescript
function assessIssueComplexity(issueDescription: string, customerHistory: any) {
const complexKeywords = ['api', 'integration', 'custom', 'enterprise', 'migration'];
const criticalKeywords = ['down', 'outage', 'critical', 'urgent', 'emergency'];
const hasComplexKeywords = complexKeywords.some(keyword =>
issueDescription.toLowerCase().includes(keyword)
);
const hasCriticalKeywords = criticalKeywords.some(keyword =>
issueDescription.toLowerCase().includes(keyword)
);
if (hasCriticalKeywords || customerHistory.previousEscalations > 2) {
return 'critical';
}
if (hasComplexKeywords || customerHistory.tier === 'enterprise') {
return 'advanced';
}
return 'basic';
}
```
### Agent Availability Checking
```typescript
function getAvailableSpecialist(category: string, complexity: string) {
const specialists = getSpecialistsByCategory(category);
const qualifiedAgents = specialists.filter(agent =>
agent.complexityLevel >= complexity && agent.isAvailable
);
if (qualifiedAgents.length === 0) {
return {
type: "number",
number: "+1-555-QUEUE-CALLBACK",
message: "All specialists are busy. You'll be added to our priority queue.",
transferPlan: {
mode: "warm-transfer-say-message",
message: `${category} ${complexity} issue - customer needs callback when specialist available`
}
};
}
// Return least busy qualified agent
const bestAgent = qualifiedAgents.sort(
(a, b) => a.activeCallCount - b.activeCallCount
)[0];
return {
type: "number",
number: bestAgent.phoneNumber,
message: `Connecting you to ${bestAgent.name}, our ${category} specialist.`,
transferPlan: {
mode: "warm-transfer-say-summary",
summaryPlan: {
enabled: true,
messages: [
{
role: "system",
content: `Provide a summary for ${bestAgent.name}`
}
]
}
}
};
}
```
## Error Handling Best Practices
### Comprehensive Error Handling
```typescript
function handleEscalationError(error: any, context: any) {
console.error('Support escalation error:', error);
// Log escalation details for debugging
console.error('Escalation context:', {
phoneNumber: context.customer?.number,
issueCategory: context.functionCall?.parameters?.issue_category,
complexityLevel: context.functionCall?.parameters?.complexity_level,
timestamp: new Date().toISOString()
});
// Return fallback destination
return {
type: "number",
number: process.env.FALLBACK_SUPPORT_NUMBER,
message: "I'll connect you with our general support team who can help you.",
transferPlan: {
mode: "warm-transfer-say-message",
message: "Escalation routing error - connecting to general support team"
}
};
}
```
### Queue Management
```typescript
async function getEscalationWithQueueManagement(context: any) {
try {
const queueStatus = await checkSupportQueueStatus();
const destination = await determineEscalationDestination(context);
// Add queue time estimate if available
if (queueStatus.estimatedWaitTime > 5) {
destination.message += ` Current wait time is approximately ${queueStatus.estimatedWaitTime} minutes.`;
}
return destination;
} catch (error) {
return handleEscalationError(error, context);
}
}
```
## Next Steps
You've built a sophisticated customer support escalation system using assistants! Consider these enhancements:
* **[Property management call routing](/workflows/examples/property-management)** - Explore the visual workflow approach
* **[Call Analysis](/assistants/call-analysis)** - Analyze escalation patterns and optimize routing
* **[Custom Tools](/tools/custom-tools)** - Build additional tools for advanced support logic
* **[Webhooks](/server-url)** - Learn more about webhook security and advanced event handling
# Multilingual support agent
> Build a multilingual voice AI customer support agent with automatic language detection, native voices, and comprehensive tools for international customer service
## Overview
Build a dynamic customer support agent for GlobalTech International that automatically detects and responds in the customer's language (English, Spanish, or French) during conversation, with seamless language switching and real-time adaptation.
**What You'll Build:**
* Assistant with automatic multilingual transcription
* Dynamic voice adaptation for detected languages
* Real-time language switching during conversations
* Phone number setup for seamless international support
* Advanced prompting for cultural context awareness
**Alternative Approach**: For a more structured multilingual experience with explicit language selection, see our [Workflow-based multilingual support](../../workflows/examples/multilingual-support) that guides customers through language selection and dedicated conversation paths.
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
## Scenario
We will be creating a dynamic multilingual customer support agent for GlobalTech International, a technology company serving customers across North America, Europe, and Latin America. Unlike structured language selection, this agent automatically detects the customer's language from their speech and can switch languages mid-conversation, providing a truly seamless multilingual experience.
***
## 1. Create a Multilingual Knowledge Base
1. Navigate to **Files** in your [Vapi Dashboard](https://dashboard.vapi.ai/)
2. Click **Choose file** and upload all three CSV files
3. Note the file IDs for use in creating multilingual tools
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
import fs from 'fs';
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function uploadMultilingualFiles() {
try {
// Upload customers file
const customersFile = await vapi.files.create({
file: fs.createReadStream("customers.csv")
});
// Upload products file
const productsFile = await vapi.files.create({
file: fs.createReadStream("products.csv")
});
// Upload support articles file
const supportFile = await vapi.files.create({
file: fs.createReadStream("support_articles.csv")
});
console.log(`Customers file ID: ${customersFile.id}`);
console.log(`Products file ID: ${productsFile.id}`);
console.log(`Support articles file ID: ${supportFile.id}`);
return {
customersFileId: customersFile.id,
productsFileId: productsFile.id,
supportFileId: supportFile.id
};
} catch (error) {
console.error('Error uploading files:', error);
throw error;
}
}
// Upload all multilingual support files
const fileIds = await uploadMultilingualFiles();
```
```python
import requests
def upload_multilingual_file(file_path):
"""Upload a CSV file for multilingual support data"""
url = "https://api.vapi.ai/file"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
try:
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error uploading {file_path}: {error}")
raise
# Upload all required files
customers_file = upload_multilingual_file("customers.csv")
products_file = upload_multilingual_file("products.csv")
support_file = upload_multilingual_file("support_articles.csv")
print(f"Customers file ID: {customers_file['id']}")
print(f"Products file ID: {products_file['id']}")
print(f"Support articles file ID: {support_file['id']}")
```
```bash
# Upload customers.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@customers.csv"
# Upload products.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@products.csv"
# Upload support_articles.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@support_articles.csv"
```
***
## 2. Create a Multilingual Assistant
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and click `Assistants` in the left sidebar.
* Click `Create Assistant`.
* Select `Blank Template` as your starting point.
* Change assistant name to `GlobalTech Support Agent`.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const systemPrompt = `You are Maria, a multilingual customer support representative for GlobalTech International. You help customers in English, Spanish, and French with product information, account support, and technical troubleshooting.
LANGUAGE CAPABILITIES:
- English: Primary language for North American customers
- Spanish: For customers in Spain, Mexico, and Latin America
- French: For customers in France, Canada, and francophone regions
CULTURAL GUIDELINES:
- English: Direct, friendly, professional tone
- Spanish: Warm, respectful, use formal "usted" initially, then adapt to customer preference
- French: Polite, formal, use proper greeting conventions ("Bonjour/Bonsoir")
Always respond in the same language the customer is using. If they switch languages, switch with them seamlessly.`;
const assistant = await vapi.assistants.create({
name: "GlobalTech Support Agent",
firstMessage: "Hello! I'm Maria from GlobalTech International. I can help you in English, Spanish, or French. How may I assist you today?",
model: {
provider: "openai",
model: "gpt-4o",
messages: [
{
role: "system",
content: systemPrompt
}
]
}
});
console.log(`Assistant created with ID: ${assistant.id}`);
```
```python
import requests
url = "https://api.vapi.ai/assistant"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
system_prompt = """You are Maria, a multilingual customer support representative for GlobalTech International. You help customers in English, Spanish, and French with product information, account support, and technical troubleshooting.
LANGUAGE CAPABILITIES:
- English: Primary language for North American customers
- Spanish: For customers in Spain, Mexico, and Latin America
- French: For customers in France, Canada, and francophone regions
CULTURAL GUIDELINES:
- English: Direct, friendly, professional tone
- Spanish: Warm, respectful, use formal "usted" initially, then adapt to customer preference
- French: Polite, formal, use proper greeting conventions ("Bonjour/Bonsoir")
Always respond in the same language the customer is using. If they switch languages, switch with them seamlessly."""
data = {
"name": "GlobalTech Support Agent",
"firstMessage": "Hello! I'm Maria from GlobalTech International. I can help you in English, Spanish, or French. How may I assist you today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": system_prompt
}
]
}
}
response = requests.post(url, headers=headers, json=data)
assistant = response.json()
print(f"Assistant created with ID: {assistant['id']}")
```
```bash
curl -X POST https://api.vapi.ai/assistant \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "GlobalTech Support Agent",
"firstMessage": "Hello! I'\''m Maria from GlobalTech International. I can help you in English, Spanish, or French. How may I assist you today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are Maria, a multilingual customer support representative for GlobalTech International..."
}
]
}
}'
```
***
## 3. Configure Multilingual Transcription
1. In your assistant configuration, find the **Transcriber** section
2. **Provider**: Select `Deepgram` (recommended for speed and accuracy)
3. **Model**: Choose `Nova 2` or `Nova 3`
4. **Language**: Select `Multi` (enables automatic language detection)
5. **Alternative**: Use `Google` provider with `Multilingual` language setting
```typescript
// Option 1: Deepgram Multi (recommended)
const deepgramTranscriber = {
provider: "deepgram",
model: "nova-2", // or "nova-3"
language: "multi"
};
// Option 2: Google Multilingual
const googleTranscriber = {
provider: "google",
model: "latest",
language: "multilingual"
};
// Update assistant with transcriber
await vapi.assistants.update("YOUR_ASSISTANT_ID", {
transcriber: deepgramTranscriber
});
```
```python
# Option 1: Deepgram Multi (recommended)
deepgram_transcriber = {
"provider": "deepgram",
"model": "nova-2", # or "nova-3"
"language": "multi"
}
# Option 2: Google Multilingual
google_transcriber = {
"provider": "google",
"model": "latest",
"language": "multilingual"
}
# Update assistant with transcriber
url = f"https://api.vapi.ai/assistant/{YOUR_ASSISTANT_ID}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {"transcriber": deepgram_transcriber}
response = requests.patch(url, headers=headers, json=data)
```
```bash
# Option 1: Deepgram Multi
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transcriber": {
"provider": "deepgram",
"model": "nova-2",
"language": "multi"
}
}'
# Option 2: Google Multilingual
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"transcriber": {
"provider": "google",
"model": "latest",
"language": "multilingual"
}
}'
```
***
## 4. Configure Multilingual Voice Synthesis
1. In the **Voice** section of your assistant:
2. **Provider**: Select `Azure` (best multilingual coverage)
3. **Voice**: Choose primary voice `en-US-AriaNeural` (English)
4. **Add fallback voices**:
* Spanish: `es-ES-ElviraNeural` (Spain) or `es-MX-DaliaNeural` (Mexico)
* French: `fr-FR-DeniseNeural` (France) or `fr-CA-SylvieNeural` (Canada)
5. **Alternative providers**: ElevenLabs, OpenAI, or PlayHT all support multiple languages
```typescript
// Multi-language voice configuration
const multilingualVoice = {
provider: "azure",
voiceId: "en-US-AriaNeural", // Primary English voice
fallbackPlan: {
voices: [
{
provider: "azure",
voiceId: "es-ES-ElviraNeural" // Spanish (Spain)
},
{
provider: "azure",
voiceId: "fr-FR-DeniseNeural" // French (France)
},
{
provider: "azure",
voiceId: "es-MX-DaliaNeural" // Spanish (Mexico)
},
{
provider: "azure",
voiceId: "fr-CA-SylvieNeural" // French (Canada)
}
]
}
};
// Alternative: ElevenLabs multilingual
const elevenLabsVoice = {
provider: "11labs",
voiceId: "multilingual-v2" // Supports multiple languages
};
await vapi.assistants.update("YOUR_ASSISTANT_ID", {
voice: multilingualVoice
});
```
```python
# Multi-language voice configuration
multilingual_voice = {
"provider": "azure",
"voiceId": "en-US-AriaNeural", # Primary English voice
"fallbackPlan": {
"voices": [
{
"provider": "azure",
"voiceId": "es-ES-ElviraNeural" # Spanish (Spain)
},
{
"provider": "azure",
"voiceId": "fr-FR-DeniseNeural" # French (France)
},
{
"provider": "azure",
"voiceId": "es-MX-DaliaNeural" # Spanish (Mexico)
},
{
"provider": "azure",
"voiceId": "fr-CA-SylvieNeural" # French (Canada)
}
]
}
}
# Update assistant with voice configuration
url = f"https://api.vapi.ai/assistant/{YOUR_ASSISTANT_ID}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {"voice": multilingual_voice}
response = requests.patch(url, headers=headers, json=data)
```
```bash
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"voice": {
"provider": "azure",
"voiceId": "en-US-AriaNeural",
"fallbackPlan": {
"voices": [
{
"provider": "azure",
"voiceId": "es-ES-ElviraNeural"
},
{
"provider": "azure",
"voiceId": "fr-FR-DeniseNeural"
}
]
}
}
}'
```
***
## 5. Configure System Prompt
First, create this comprehensive system prompt:
```txt title="System Prompt" maxLines=15
# GlobalTech International - Multilingual Support Agent
## Identity & Role
You are **Maria**, a multilingual customer support representative for GlobalTech International. You are fluent in English, Spanish, and French, and you help customers with product information, account support, and technical troubleshooting.
## Language Capabilities & Cultural Guidelines
### English (Primary)
- **Tone**: Direct, friendly, professional
- **Style**: Conversational but efficient
- **Approach**: Solution-focused, provide clear steps
### Spanish
- **Tone**: Warm, respectful, patient
- **Formality**: Use formal "usted" initially, then adapt to customer preference
- **Approach**: Take time to build rapport, be thorough in explanations
### French
- **Tone**: Polite, courteous, professional
- **Formality**: Use proper greeting conventions ("Bonjour/Bonsoir")
- **Approach**: Structured responses, respectful of formality
## Core Responsibilities
1. **Product Information**: Help customers understand our technology solutions
2. **Account Support**: Assist with account access, billing, and subscription questions
3. **Technical Troubleshooting**: Guide customers through technical issues step-by-step
4. **Escalation**: Transfer to specialized teams when needed
## Language Behavior
- **Auto-detect**: Automatically respond in the customer's language
- **Language Switching**: If customer switches languages, switch with them seamlessly
- **Mixed Languages**: If customer uses multiple languages, respond in their primary language
- **Unsupported Languages**: If customer speaks another language, politely explain you support English, Spanish, and French
## Available Tools
- **Customer Lookup**: Search customer database by email, phone, or account ID
- **Product Information**: Access product catalog and specifications
- **Support Articles**: Find relevant troubleshooting guides in customer's language
Keep responses concise (under 50 words) while being thorough and helpful.
```
Then update your assistant:
Copy the system prompt above and paste it into the `System Prompt` field in your assistant configuration.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const systemPrompt = `# GlobalTech International - Multilingual Support Agent
## Identity & Role
You are **Maria**, a multilingual customer support representative for GlobalTech International. You are fluent in English, Spanish, and French, and you help customers with product information, account support, and technical troubleshooting.
## Language Capabilities & Cultural Guidelines
### English (Primary)
- **Tone**: Direct, friendly, professional
- **Style**: Conversational but efficient
- **Approach**: Solution-focused, provide clear steps
### Spanish
- **Tone**: Warm, respectful, patient
- **Formality**: Use formal "usted" initially, then adapt to customer preference
- **Approach**: Take time to build rapport, be thorough in explanations
### French
- **Tone**: Polite, courteous, professional
- **Formality**: Use proper greeting conventions ("Bonjour/Bonsoir")
- **Approach**: Structured responses, respectful of formality
## Core Responsibilities
1. **Product Information**: Help customers understand our technology solutions
2. **Account Support**: Assist with account access, billing, and subscription questions
3. **Technical Troubleshooting**: Guide customers through technical issues step-by-step
4. **Escalation**: Transfer to specialized teams when needed
## Language Behavior
- **Auto-detect**: Automatically respond in the customer's language
- **Language Switching**: If customer switches languages, switch with them seamlessly
- **Mixed Languages**: If customer uses multiple languages, respond in their primary language
- **Unsupported Languages**: If customer speaks another language, politely explain you support English, Spanish, and French
## Available Tools
- **Customer Lookup**: Search customer database by email, phone, or account ID
- **Product Information**: Access product catalog and specifications
- **Support Articles**: Find relevant troubleshooting guides in customer's language
Keep responses concise (under 50 words) while being thorough and helpful.`;
const updatedAssistant = await vapi.assistants.update("YOUR_ASSISTANT_ID", {
model: {
provider: "openai",
model: "gpt-4o",
messages: [
{
role: "system",
content: systemPrompt
}
]
}
});
console.log("System prompt updated successfully");
```
```python
import requests
url = f"https://api.vapi.ai/assistant/{YOUR_ASSISTANT_ID}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
system_prompt = """# GlobalTech International - Multilingual Support Agent
## Identity & Role
You are **Maria**, a multilingual customer support representative for GlobalTech International. You are fluent in English, Spanish, and French, and you help customers with product information, account support, and technical troubleshooting.
## Language Capabilities & Cultural Guidelines
### English (Primary)
- **Tone**: Direct, friendly, professional
- **Style**: Conversational but efficient
- **Approach**: Solution-focused, provide clear steps
### Spanish
- **Tone**: Warm, respectful, patient
- **Formality**: Use formal "usted" initially, then adapt to customer preference
- **Approach**: Take time to build rapport, be thorough in explanations
### French
- **Tone**: Polite, courteous, professional
- **Formality**: Use proper greeting conventions ("Bonjour/Bonsoir")
- **Approach**: Structured responses, respectful of formality
## Core Responsibilities
1. **Product Information**: Help customers understand our technology solutions
2. **Account Support**: Assist with account access, billing, and subscription questions
3. **Technical Troubleshooting**: Guide customers through technical issues step-by-step
4. **Escalation**: Transfer to specialized teams when needed
## Language Behavior
- **Auto-detect**: Automatically respond in the customer's language
- **Language Switching**: If customer switches languages, switch with them seamlessly
- **Mixed Languages**: If customer uses multiple languages, respond in their primary language
- **Unsupported Languages**: If customer speaks another language, politely explain you support English, Spanish, and French
## Available Tools
- **Customer Lookup**: Search customer database by email, phone, or account ID
- **Product Information**: Access product catalog and specifications
- **Support Articles**: Find relevant troubleshooting guides in customer's language
Keep responses concise (under 50 words) while being thorough and helpful."""
data = {
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": system_prompt
}
]
}
}
response = requests.patch(url, headers=headers, json=data)
assistant = response.json()
print("System prompt updated successfully")
```
```bash
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "# GlobalTech International - Multilingual Support Agent..."
}
]
}
}'
```
***
## 6. Add Multilingual Tools
Open your [dashboard.vapi.ai](https://dashboard.vapi.ai) and click `Tools` in the left sidebar.
* Click `Create Tool`.
* Select `Function` as your tool type.
* Change tool name to `lookup_customer`.
* Add function description:
```txt title="Function Description" wordWrap
Look up customer information by email, phone number, or account ID. Returns customer details including preferred language, account status, and support history.
```
* Add knowledge base:
* Name: `customers`
* Description: `Customer database with multilingual support preferences`
* File IDs: ``
* Click `Create Tool`.
* Select `Function` as your tool type.
* Change tool name to `get_product_info`.
* Add function description:
```txt title="Function Description" wordWrap
Get detailed product information including specifications, pricing, and availability. Supports queries in English, Spanish, and French.
```
* Add knowledge base:
* Name: `products`
* Description: `Product catalog with multilingual descriptions`
* File IDs: ``
* Click `Create Tool`.
* Select `Function` as your tool type.
* Change tool name to `search_support_articles`.
* Add function description:
```txt title="Function Description" wordWrap
Search technical support articles and troubleshooting guides. Returns relevant articles in the customer's preferred language.
```
* Add knowledge base:
* Name: `support_articles`
* Description: `Multilingual support documentation and troubleshooting guides`
* File IDs: ``
* Click `Assistants` in the left sidebar.
* Select your `GlobalTech Support Agent`.
* Scroll down to the `Tools` section and expand it.
* Add all three tools: `lookup_customer`, `get_product_info`, and `search_support_articles`.
* Click `Publish` to save your changes.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// Create customer lookup tool
const customerLookupTool = await vapi.tools.create({
type: "function",
function: {
name: "lookup_customer",
description: "Look up customer information by email, phone number, or account ID. Returns customer details including preferred language, account status, and support history."
},
knowledgeBases: [
{
name: "customers",
description: "Customer database with multilingual support preferences",
fileIds: ["YOUR_CUSTOMERS_FILE_ID"]
}
]
});
// Create product information tool
const productInfoTool = await vapi.tools.create({
type: "function",
function: {
name: "get_product_info",
description: "Get detailed product information including specifications, pricing, and availability. Supports queries in English, Spanish, and French."
},
knowledgeBases: [
{
name: "products",
description: "Product catalog with multilingual descriptions",
fileIds: ["YOUR_PRODUCTS_FILE_ID"]
}
]
});
// Create support articles tool
const supportArticlesTool = await vapi.tools.create({
type: "function",
function: {
name: "search_support_articles",
description: "Search technical support articles and troubleshooting guides. Returns relevant articles in the customer's preferred language."
},
knowledgeBases: [
{
name: "support_articles",
description: "Multilingual support documentation and troubleshooting guides",
fileIds: ["YOUR_SUPPORT_ARTICLES_FILE_ID"]
}
]
});
// Add all tools to the assistant
const updatedAssistant = await vapi.assistants.update("YOUR_ASSISTANT_ID", {
model: {
toolIds: [
customerLookupTool.id,
productInfoTool.id,
supportArticlesTool.id
]
}
});
console.log("All multilingual tools added to assistant successfully!");
```
```python
import requests
def create_multilingual_tool(name, description, knowledge_base_name, knowledge_base_description, file_id):
"""Create a multilingual tool with knowledge base"""
url = "https://api.vapi.ai/tool"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"type": "function",
"function": {
"name": name,
"description": description
},
"knowledgeBases": [
{
"name": knowledge_base_name,
"description": knowledge_base_description,
"fileIds": [file_id]
}
]
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Create customer lookup tool
customer_lookup_tool = create_multilingual_tool(
"lookup_customer",
"Look up customer information by email, phone number, or account ID. Returns customer details including preferred language, account status, and support history.",
"customers",
"Customer database with multilingual support preferences",
"YOUR_CUSTOMERS_FILE_ID"
)
# Create product information tool
product_info_tool = create_multilingual_tool(
"get_product_info",
"Get detailed product information including specifications, pricing, and availability. Supports queries in English, Spanish, and French.",
"products",
"Product catalog with multilingual descriptions",
"YOUR_PRODUCTS_FILE_ID"
)
# Create support articles tool
support_articles_tool = create_multilingual_tool(
"search_support_articles",
"Search technical support articles and troubleshooting guides. Returns relevant articles in the customer'\''s preferred language.",
"support_articles",
"Multilingual support documentation and troubleshooting guides",
"YOUR_SUPPORT_ARTICLES_FILE_ID"
)
# Add all tools to the assistant
def update_assistant_with_tools(assistant_id, tool_ids):
url = f"https://api.vapi.ai/assistant/{assistant_id}"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"model": {
"toolIds": tool_ids
}
}
response = requests.patch(url, headers=headers, json=data)
return response.json()
tool_ids = [
customer_lookup_tool['id'],
product_info_tool['id'],
support_articles_tool['id']
]
updated_assistant = update_assistant_with_tools("YOUR_ASSISTANT_ID", tool_ids)
print("All multilingual tools added to assistant successfully!")
```
```bash
# Create customer lookup tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "lookup_customer",
"description": "Look up customer information by email, phone number, or account ID. Returns customer details including preferred language, account status, and support history."
},
"knowledgeBases": [
{
"name": "customers",
"description": "Customer database with multilingual support preferences",
"fileIds": ["YOUR_CUSTOMERS_FILE_ID"]
}
]
}'
# Create product information tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "get_product_info",
"description": "Get detailed product information including specifications, pricing, and availability. Supports queries in English, Spanish, and French."
},
"knowledgeBases": [
{
"name": "products",
"description": "Product catalog with multilingual descriptions",
"fileIds": ["YOUR_PRODUCTS_FILE_ID"]
}
]
}'
# Create support articles tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "search_support_articles",
"description": "Search technical support articles and troubleshooting guides. Returns relevant articles in the customer'\''s preferred language."
},
"knowledgeBases": [
{
"name": "support_articles",
"description": "Multilingual support documentation and troubleshooting guides",
"fileIds": ["YOUR_SUPPORT_ARTICLES_FILE_ID"]
}
]
}'
# Add all tools to the assistant
curl -X PATCH https://api.vapi.ai/assistant/YOUR_ASSISTANT_ID \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": {
"toolIds": ["CUSTOMER_LOOKUP_TOOL_ID", "PRODUCT_INFO_TOOL_ID", "SUPPORT_ARTICLES_TOOL_ID"]
}
}'
```
***
## 7. Set Up Phone Number
Open your [dashboard.vapi.ai](https://dashboard.vapi.ai) and click `Phone Numbers` in the left sidebar.
* Click `Create Phone Number`.
* Choose `Free Vapi Number` to get started.
* Select your preferred area code (e.g., `212` for New York).
* Set the `Phone Number Name` to `GlobalTech International Support`.
* Under `Inbound Settings`, find `Assistant` dropdown and select `GlobalTech Support Agent`.
* **Optional**: Configure advanced settings:
* Enable call recording for quality assurance
* Set up voicemail detection
* Configure business hours if needed
* Changes are saved automatically.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
const phoneNumber = await vapi.phoneNumbers.create({
name: "GlobalTech International Support",
assistantId: "YOUR_ASSISTANT_ID",
inboundSettings: {
recordingEnabled: true,
voicemailDetectionEnabled: true,
maxCallDurationMinutes: 30
}
});
console.log(`Multilingual support phone number created: ${phoneNumber.number}`);
```
```python
import requests
def create_multilingual_phone_number(assistant_id):
"""Create phone number for multilingual support"""
url = "https://api.vapi.ai/phone-number"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "GlobalTech International Support",
"assistantId": assistant_id,
"inboundSettings": {
"recordingEnabled": True,
"voicemailDetectionEnabled": True,
"maxCallDurationMinutes": 30
}
}
response = requests.post(url, headers=headers, json=data)
return response.json()
# Create multilingual support phone number
phone_number = create_multilingual_phone_number("YOUR_ASSISTANT_ID")
print(f"Multilingual support phone number created: {phone_number['number']}")
```
```bash
# Create multilingual support phone number
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "GlobalTech International Support",
"assistantId": "YOUR_ASSISTANT_ID",
"inboundSettings": {
"recordingEnabled": true,
"voicemailDetectionEnabled": true,
"maxCallDurationMinutes": 30
}
}'
```
***
## Alternative: Workflow-Based Language Selection
For a more structured approach with explicit language selection, see our comprehensive [Workflow-based multilingual support](../../workflows/examples/multilingual-support) guide. This approach lets customers choose their language at the start of the call, then routes them to dedicated conversation paths optimized for each language.
```typescript
const languageSelectionWorkflow = await vapi.workflows.create({
name: "GlobalTech Multilingual Workflow",
nodes: [
{
id: "language_selection",
type: "conversation",
firstMessage: "Hello! Hola! Bonjour! Welcome to GlobalTech International. Please say 'English', 'Español', or 'Français' to continue in your preferred language.",
systemPrompt: "Listen for the customer's language preference and extract it.",
extractVariables: [
{
name: "preferred_language",
type: "string",
description: "Customer's preferred language",
enum: ["english", "spanish", "french"]
}
]
},
{
id: "english_support",
type: "conversation",
condition: "preferred_language == 'english'",
firstMessage: "Thank you for choosing English. I'm Maria, your support representative. How can I help you today?",
systemPrompt: "You are Maria, GlobalTech's English support agent. Be direct, friendly, and professional.",
voice: {
provider: "azure",
voiceId: "en-US-AriaNeural"
}
},
{
id: "spanish_support",
type: "conversation",
condition: "preferred_language == 'spanish'",
firstMessage: "Gracias por elegir español. Soy María, su representante de soporte. ¿Cómo puedo ayudarle hoy?",
systemPrompt: "Eres María, agente de soporte en español de GlobalTech. Sé cálida, respetuosa y usa 'usted' inicialmente.",
voice: {
provider: "azure",
voiceId: "es-ES-ElviraNeural"
}
},
{
id: "french_support",
type: "conversation",
condition: "preferred_language == 'french'",
firstMessage: "Merci d'avoir choisi le français. Je suis Maria, votre représentante du support. Comment puis-je vous aider aujourd'hui?",
systemPrompt: "Vous êtes Maria, agent de support français de GlobalTech. Soyez polie, courtoise et formelle.",
voice: {
provider: "azure",
voiceId: "fr-FR-DeniseNeural"
}
}
]
});
```
* **Clearer language selection**: Customers explicitly choose their language
* **Dedicated language paths**: Each language has its own conversation flow
* **Optimized voices**: Language-specific voices for better quality
* **Easier maintenance**: Separate prompts and logic for each language
* **Better analytics**: Track language preferences and usage patterns
## Provider Support Summary
**Speech-to-Text (Transcription):**
* **Deepgram**: Nova 2, Nova 3 with "Multi" language setting
* **Google**: Latest models with "Multilingual" language setting
* **All other providers**: Single language only, no automatic detection
**Text-to-Speech (Voice Synthesis):**
* **Azure**: 400+ voices across 140+ languages (recommended for coverage)
* **ElevenLabs**: 30+ languages with premium quality
* **OpenAI**: 50+ languages with consistent quality
* **PlayHT**: 80+ languages, cost-effective
* **All providers**: Support multiple languages natively
**Language Models:**
* **All major LLMs** (GPT-4o, Claude, Gemini, Llama, etc.): Native multilingual support
## Next Steps
Just like that, you've built a dynamic multilingual customer support agent that automatically detects and responds in the customer's language with seamless mid-conversation language switching.
Consider reading the following guides to further enhance your multilingual implementation:
* [**Workflow-based Multilingual Support**](../../workflows/examples/multilingual-support) - Compare with structured language selection approach
* [**Multilingual Configuration Guide**](../../../customization/multilingual) - Learn about all multilingual configuration options
* [**Custom Tools**](../../../tools/custom-tools) - Build advanced multilingual tools and integrations
Need help with multilingual implementation? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Workflows quickstart
> Build a simple agent that greets users and gathers basic information using Vapi workflows.
## Overview
Build a simple voice agent using Vapi's visual workflow builder that greets users, collects their information, and demonstrates core workflow concepts like variable extraction, conditional routing, and global nodes.
**Agent Capabilities:**
* Greet users and ask about their voice agent needs
* Extract and store user information (name and city)
* Use variables in dynamic responses
* Handle escalation to human agents at any point
**What You'll Build:**
* Multi-node conversation flow with branching logic
* Variable extraction and liquid template usage
* Global escalation nodes for human transfer
* End-call automation with natural conversation termination
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai)
* For SDK usage: API key from the Dashboard
**Developing with the Vapi CLI?** You can manage workflows and test webhook integrations from your terminal:
```bash
# List all workflows
vapi workflow list
# Test workflow webhooks locally
vapi listen --forward-to localhost:3000/webhook
```
[Learn more about the Vapi CLI →](/cli)
## Scenario
We will create a simple information-gathering workflow that demonstrates the core features of Vapi's workflow builder. This workflow will showcase conversation flow, variable extraction, and escalation patterns that form the foundation of more complex workflows.
**Workflows vs Assistants**: Workflows are visual conversation flows with branching logic and variable extraction. Assistants are single AI agents with tools and continuous conversation. This guide covers workflows specifically.
***
## 1. Create a Workflow
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Workflows` in the left sidebar.
* Click `Create Workflow`.
* Enter workflow name: `Information Gathering Demo`.
* Select the blank template.
* Click **Create Workflow**.
```bash title="npm"
npm install @vapi-ai/server-sdk
```
```bash title="yarn"
yarn add @vapi-ai/server-sdk
```
```bash title="pnpm"
pnpm add @vapi-ai/server-sdk
```
```bash title="bun"
bun add @vapi-ai/server-sdk
```
```typescript
import { VapiClient } from '@vapi-ai/server-sdk';
// Initialize the Vapi client
const vapi = new VapiClient({
token: 'YOUR_API_KEY'
});
async function createWorkflow() {
try {
const workflow = await vapi.workflows.create({
name: 'Information Gathering Demo',
// Start with a basic conversation node
nodes: [
{
id: 'start',
type: 'conversation',
firstMessage: 'Hey there!',
systemPrompt: 'Ask users what kind of voice agent they want to build. Be friendly and conversational.',
}
],
edges: []
});
console.log('Workflow created:', workflow.id);
return workflow;
} catch (error) {
console.error('Error creating workflow:', error);
throw error;
}
}
// Create the workflow
createWorkflow();
```
```bash
pip install vapi_server_sdk
```
```python
from vapi import Vapi
# Initialize the Vapi client
client = Vapi(token="YOUR_API_KEY") # Replace with your actual API key
def create_workflow():
try:
workflow = client.workflows.create(
name="Information Gathering Demo",
// Start with a basic conversation node
nodes=[
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational.",
}
],
edges=[]
)
print(f"Workflow created: {workflow.id}")
return workflow
except Exception as error:
print(f"Error creating workflow: {error}")
raise error
// Create the workflow
create_workflow()
```
```bash
curl -X POST "https://api.vapi.ai/workflow" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Information Gathering Demo",
"nodes": [
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational."
}
],
"edges": []
}'
```
***
## 2. Configure the Start Node
The blank template includes a conversation node. Click on it and configure:
**First Message**:
```txt
Hey there!
```
**Prompt**:
```txt
Ask users what kind of voice agent they want to build. Be friendly and conversational.
```
Click **Call** in the top right to test your initial setup. The agent should greet you and ask about voice agents.
```typescript
async function updateStartNode(workflowId: string) {
try {
const updatedWorkflow = await vapi.workflows.update(workflowId, {
nodes: [
{
id: 'start',
type: 'conversation',
firstMessage: 'Hey there!',
systemPrompt: 'Ask users what kind of voice agent they want to build. Be friendly and conversational.',
}
]
});
console.log('Start node configured successfully');
return updatedWorkflow;
} catch (error) {
console.error('Error updating start node:', error);
throw error;
}
}
// Update the start node
updateStartNode('your-workflow-id');
```
```python
def update_start_node(workflow_id: str):
try:
updated_workflow = client.workflows.update(
workflow_id,
nodes=[
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational.",
}
]
)
print("Start node configured successfully")
return updated_workflow
except Exception as error:
print(f"Error updating start node: {error}")
raise error
// Update the start node
update_start_node("your-workflow-id")
```
```bash
curl -X PATCH "https://api.vapi.ai/workflow/your-workflow-id" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational."
}
]
}'
```
You can change the node type by selecting a different type from the dropdown at the top of the node configuration panel. For example, you can change the start node type to API Request to trigger an HTTP request as soon as the call is connected.
***
## 3. Add Information Collection Flow
* Click the **+** button below the first node
* Select **Conversation Node**
* Configure the new node:
**Prompt**:
```txt
Acknowledge the user's voice agent use case, then ask for information about the user. Ask for their first name and what city they're in.
```
**Extract Variables** (expand this section):
* Variable 1:
* Name: `first_name`
* Type: `string`
* Description: `the user's first name`
* Variable 2:
* Name: `city`
* Type: `string`
* Description: `the user's city`
Click on the edge between the two nodes and configure:
* **Condition**: `User describes their voice agent`
* Click **Save**
```typescript
async function addInformationCollectionNode(workflowId: string) {
try {
// Get current workflow to preserve existing nodes
const currentWorkflow = await vapi.workflows.get(workflowId);
// Add information collection node
const updatedNodes = [
...currentWorkflow.nodes,
{
id: 'collect_info',
type: 'conversation',
systemPrompt: 'Acknowledge the user\'s voice agent use case, then ask for information about the user. Ask for their first name and what city they\'re in.',
extractVariables: [
{
name: 'first_name',
type: 'string',
description: 'the user\'s first name'
},
{
name: 'city',
type: 'string',
description: 'the user\'s city'
}
]
}
];
// Add connecting edge
const updatedEdges = [
...currentWorkflow.edges,
{
from: 'start',
to: 'collect_info',
condition: 'User describes their voice agent'
}
];
const updatedWorkflow = await vapi.workflows.update(workflowId, {
nodes: updatedNodes,
edges: updatedEdges
});
console.log('Information collection node added successfully');
return updatedWorkflow;
} catch (error) {
console.error('Error adding information collection node:', error);
throw error;
}
}
// Add information collection flow
addInformationCollectionNode('your-workflow-id');
```
```python
def add_information_collection_node(workflow_id: str):
try:
# Get current workflow to preserve existing nodes
current_workflow = client.workflows.get(workflow_id)
# Add information collection node
updated_nodes = current_workflow.nodes + [
{
"id": "collect_info",
"type": "conversation",
"systemPrompt": "Acknowledge the user's voice agent use case, then ask for information about the user. Ask for their first name and what city they're in.",
"extractVariables": [
{
"name": "first_name",
"type": "string",
"description": "the user's first name"
},
{
"name": "city",
"type": "string",
"description": "the user's city"
}
]
}
]
# Add connecting edge
updated_edges = current_workflow.edges + [
{
"from": "start",
"to": "collect_info",
"condition": "User describes their voice agent"
}
]
updated_workflow = client.workflows.update(
workflow_id,
nodes=updated_nodes,
edges=updated_edges
)
print("Information collection node added successfully")
return updated_workflow
except Exception as error:
print(f"Error adding information collection node: {error}")
raise error
# Add information collection flow
add_information_collection_node("your-workflow-id")
```
```bash
# Get current workflow structure first
WORKFLOW_ID="your-workflow-id"
# Update workflow with information collection node
curl -X PATCH "https://api.vapi.ai/workflow/$WORKFLOW_ID" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational."
},
{
"id": "collect_info",
"type": "conversation",
"systemPrompt": "Acknowledge the user'\''s voice agent use case, then ask for information about the user. Ask for their first name and what city they'\''re in.",
"extractVariables": [
{
"name": "first_name",
"type": "string",
"description": "the user'\''s first name"
},
{
"name": "city",
"type": "string",
"description": "the user'\''s city"
}
]
}
],
"edges": [
{
"from": "start",
"to": "collect_info",
"condition": "User describes their voice agent"
}
]
}'
```
***
## 4. Add Dynamic Response Node
Add another **Conversation Node** with this prompt:
```txt
Say "Thanks {{first_name}}, {{city}} is great!"
Then say a few nice words about the {{city}}. Keep it brief. After that, ask the user if there's anything you can help with and help them, unless they no longer need help.
```
Click on the edge leading to this node and:
* Remove any condition text (leave it blank)
* Click **Save**
This allows automatic flow after the variables are extracted.
```typescript
async function addDynamicResponseNode(workflowId: string) {
try {
// Get current workflow
const currentWorkflow = await vapi.workflows.get(workflowId);
// Add dynamic response node
const updatedNodes = [
...currentWorkflow.nodes,
{
id: 'dynamic_response',
type: 'conversation',
systemPrompt: 'Say "Thanks {{first_name}}, {{city}} is great!" Then say a few nice words about the {{city}}. Keep it brief. After that, ask the user if there\'s anything you can help with and help them, unless they no longer need help.'
}
];
// Add edge without condition for automatic flow
const updatedEdges = [
...currentWorkflow.edges,
{
from: 'collect_info',
to: 'dynamic_response'
}
];
const updatedWorkflow = await vapi.workflows.update(workflowId, {
nodes: updatedNodes,
edges: updatedEdges
});
console.log('Dynamic response node added successfully');
return updatedWorkflow;
} catch (error) {
console.error('Error adding dynamic response node:', error);
throw error;
}
}
// Add dynamic response node
addDynamicResponseNode('your-workflow-id');
```
```python
def add_dynamic_response_node(workflow_id: str):
try:
# Get current workflow
current_workflow = client.workflows.get(workflow_id)
# Add dynamic response node
updated_nodes = current_workflow.nodes + [
{
"id": "dynamic_response",
"type": "conversation",
"systemPrompt": "Say \"Thanks {{first_name}}, {{city}} is great!\" Then say a few nice words about the {{city}}. Keep it brief. After that, ask the user if there's anything you can help with and help them, unless they no longer need help."
}
]
# Add edge without condition for automatic flow
updated_edges = current_workflow.edges + [
{
"from": "collect_info",
"to": "dynamic_response"
}
]
updated_workflow = client.workflows.update(
workflow_id,
nodes=updated_nodes,
edges=updated_edges
)
print("Dynamic response node added successfully")
return updated_workflow
except Exception as error:
print(f"Error adding dynamic response node: {error}")
raise error
# Add dynamic response node
add_dynamic_response_node("your-workflow-id")
```
```bash
curl -X PATCH "https://api.vapi.ai/workflow/your-workflow-id" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational."
},
{
"id": "collect_info",
"type": "conversation",
"systemPrompt": "Acknowledge the user'\''s voice agent use case, then ask for information about the user. Ask for their first name and what city they'\''re in.",
"extractVariables": [
{
"name": "first_name",
"type": "string",
"description": "the user'\''s first name"
},
{
"name": "city",
"type": "string",
"description": "the user'\''s city"
}
]
},
{
"id": "dynamic_response",
"type": "conversation",
"systemPrompt": "Say \"Thanks {{first_name}}, {{city}} is great!\" Then say a few nice words about the {{city}}. Keep it brief. After that, ask the user if there'\''s anything you can help with and help them, unless they no longer need help."
}
],
"edges": [
{
"from": "start",
"to": "collect_info",
"condition": "User describes their voice agent"
},
{
"from": "collect_info",
"to": "dynamic_response"
}
]
}'
```
***
## 5. Add Global Escalation Node
Add a new **Conversation Node** and configure:
**Global Node**: Toggle this **ON**
**Conversation Prompt**:
```txt
Confirm that the user wants to speak to a human and ask them what would they like to talk to the human about.
```
**Condition Prompt**:
```txt
User wants to speak to a human
```
Add a **Transfer Call Node** below the global node:
* **Destination**: Enter your phone number or `+1-555-DEMO-123`
* Configure **Transfer Plan** with a brief summary message
```typescript
async function addEscalationNodes(workflowId: string) {
try {
// Get current workflow
const currentWorkflow = await vapi.workflows.get(workflowId);
// Add escalation and transfer nodes
const updatedNodes = [
...currentWorkflow.nodes,
{
id: 'escalation',
type: 'conversation',
isGlobal: true,
systemPrompt: 'Confirm that the user wants to speak to a human and ask them what would they like to talk to the human about.',
condition: 'User wants to speak to a human'
},
{
id: 'transfer',
type: 'transferCall',
destination: '+1-555-DEMO-123', // Replace with your number
transferPlan: {
message: 'The user wants to speak with a human agent.'
}
}
];
// Add edge from escalation to transfer
const updatedEdges = [
...currentWorkflow.edges,
{
from: 'escalation',
to: 'transfer'
}
];
const updatedWorkflow = await vapi.workflows.update(workflowId, {
nodes: updatedNodes,
edges: updatedEdges
});
console.log('Escalation nodes added successfully');
return updatedWorkflow;
} catch (error) {
console.error('Error adding escalation nodes:', error);
throw error;
}
}
// Add escalation functionality
addEscalationNodes('your-workflow-id');
```
```python
def add_escalation_nodes(workflow_id: str):
try:
# Get current workflow
current_workflow = client.workflows.get(workflow_id)
# Add escalation and transfer nodes
updated_nodes = current_workflow.nodes + [
{
"id": "escalation",
"type": "conversation",
"isGlobal": True,
"systemPrompt": "Confirm that the user wants to speak to a human and ask them what would they like to talk to the human about.",
"condition": "User wants to speak to a human"
},
{
"id": "transfer",
"type": "transferCall",
"destination": "+1-555-DEMO-123", # Replace with your number
"transferPlan": {
"message": "The user wants to speak with a human agent."
}
}
]
# Add edge from escalation to transfer
updated_edges = current_workflow.edges + [
{
"from": "escalation",
"to": "transfer"
}
]
updated_workflow = client.workflows.update(
workflow_id,
nodes=updated_nodes,
edges=updated_edges
)
print("Escalation nodes added successfully")
return updated_workflow
except Exception as error:
print(f"Error adding escalation nodes: {error}")
raise error
# Add escalation functionality
add_escalation_nodes("your-workflow-id")
```
```bash
curl -X PATCH "https://api.vapi.ai/workflow/your-workflow-id" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational."
},
{
"id": "collect_info",
"type": "conversation",
"systemPrompt": "Acknowledge the user'\''s voice agent use case, then ask for information about the user. Ask for their first name and what city they'\''re in.",
"extractVariables": [
{
"name": "first_name",
"type": "string",
"description": "the user'\''s first name"
},
{
"name": "city",
"type": "string",
"description": "the user'\''s city"
}
]
},
{
"id": "dynamic_response",
"type": "conversation",
"systemPrompt": "Say \"Thanks {{first_name}}, {{city}} is great!\" Then say a few nice words about the {{city}}. Keep it brief. After that, ask the user if there'\''s anything you can help with and help them, unless they no longer need help."
},
{
"id": "escalation",
"type": "conversation",
"isGlobal": true,
"systemPrompt": "Confirm that the user wants to speak to a human and ask them what would they like to talk to the human about.",
"condition": "User wants to speak to a human"
},
{
"id": "transfer",
"type": "transferCall",
"destination": "+1-555-DEMO-123",
"transferPlan": {
"message": "The user wants to speak with a human agent."
}
}
],
"edges": [
{
"from": "start",
"to": "collect_info",
"condition": "User describes their voice agent"
},
{
"from": "collect_info",
"to": "dynamic_response"
},
{
"from": "escalation",
"to": "transfer"
}
]
}'
```
Developers can specify a phone number destination and a [transfer plan](/call-forwarding#call-transfers-mode), which lets them specify a message or a summary of the call to the person or agent picking up in the destination number before actually connecting the call.
***
## 6. Add Call Termination
Add an **End Call Node** at the end of your main flow:
**First Message**:
```txt
Alright, have a nice day!
```
Update the edge leading to the End Call node:
* **Condition**: `User does not need any help`
* Click **Save**
```typescript
async function addEndCallNode(workflowId: string) {
try {
// Get current workflow
const currentWorkflow = await vapi.workflows.get(workflowId);
// Add end call node
const updatedNodes = [
...currentWorkflow.nodes,
{
id: 'end_call',
type: 'endCall',
firstMessage: 'Alright, have a nice day!'
}
];
// Add edge with condition
const updatedEdges = [
...currentWorkflow.edges,
{
from: 'dynamic_response',
to: 'end_call',
condition: 'User does not need any help'
}
];
const updatedWorkflow = await vapi.workflows.update(workflowId, {
nodes: updatedNodes,
edges: updatedEdges
});
console.log('End call node added successfully');
return updatedWorkflow;
} catch (error) {
console.error('Error adding end call node:', error);
throw error;
}
}
// Add call termination
addEndCallNode('your-workflow-id');
```
```python
def add_end_call_node(workflow_id: str):
try:
# Get current workflow
current_workflow = client.workflows.get(workflow_id)
# Add end call node
updated_nodes = current_workflow.nodes + [
{
"id": "end_call",
"type": "endCall",
"firstMessage": "Alright, have a nice day!"
}
]
# Add edge with condition
updated_edges = current_workflow.edges + [
{
"from": "dynamic_response",
"to": "end_call",
"condition": "User does not need any help"
}
]
updated_workflow = client.workflows.update(
workflow_id,
nodes=updated_nodes,
edges=updated_edges
)
print("End call node added successfully")
return updated_workflow
except Exception as error:
print(f"Error adding end call node: {error}")
raise error
# Add call termination
add_end_call_node("your-workflow-id")
```
```bash
curl -X PATCH "https://api.vapi.ai/workflow/your-workflow-id" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"id": "start",
"type": "conversation",
"firstMessage": "Hey there!",
"systemPrompt": "Ask users what kind of voice agent they want to build. Be friendly and conversational."
},
{
"id": "collect_info",
"type": "conversation",
"systemPrompt": "Acknowledge the user'\''s voice agent use case, then ask for information about the user. Ask for their first name and what city they'\''re in.",
"extractVariables": [
{
"name": "first_name",
"type": "string",
"description": "the user'\''s first name"
},
{
"name": "city",
"type": "string",
"description": "the user'\''s city"
}
]
},
{
"id": "dynamic_response",
"type": "conversation",
"systemPrompt": "Say \"Thanks {{first_name}}, {{city}} is great!\" Then say a few nice words about the {{city}}. Keep it brief. After that, ask the user if there'\''s anything you can help with and help them, unless they no longer need help."
},
{
"id": "escalation",
"type": "conversation",
"isGlobal": true,
"systemPrompt": "Confirm that the user wants to speak to a human and ask them what would they like to talk to the human about.",
"condition": "User wants to speak to a human"
},
{
"id": "transfer",
"type": "transferCall",
"destination": "+1-555-DEMO-123",
"transferPlan": {
"message": "The user wants to speak with a human agent."
}
},
{
"id": "end_call",
"type": "endCall",
"firstMessage": "Alright, have a nice day!"
}
],
"edges": [
{
"from": "start",
"to": "collect_info",
"condition": "User describes their voice agent"
},
{
"from": "collect_info",
"to": "dynamic_response"
},
{
"from": "dynamic_response",
"to": "end_call",
"condition": "User does not need any help"
},
{
"from": "escalation",
"to": "transfer"
}
]
}'
```
***
## 7. Test Your Workflow
Click **Call** in the top right to test your workflow:
* Verify the greeting works
* Test variable extraction by providing your name and city
* Confirm the dynamic response uses your information
* Test the global escalation by saying "I want to speak to a human"
Your final workflow should have:
* **Start Node**: Greeting and use case inquiry
* **Collection Node**: Information gathering with variable extraction
* **Response Node**: Dynamic response using extracted variables
* **Global Node**: Human escalation available from anywhere
* **Transfer Node**: Routes to human agent when needed
* **End Node**: Natural conversation termination
```typescript
async function testWorkflow(workflowId: string) {
try {
// Create phone number for workflow testing
const phoneNumber = await vapi.phoneNumbers.create({
name: 'Workflow Test Number',
workflowId: workflowId,
});
console.log('Phone number created:', phoneNumber.number);
// Make an outbound test call
const testCall = await vapi.calls.create({
workflowId: workflowId,
customer: {
number: '+1234567890', // Replace with your test number
},
});
console.log('Test call initiated:', testCall.id);
return { phoneNumber, testCall };
} catch (error) {
console.error('Error testing workflow:', error);
throw error;
}
}
// Test your workflow
testWorkflow('your-workflow-id');
```
```python
def test_workflow(workflow_id: str):
try:
# Create phone number for workflow testing
phone_number = client.phone_numbers.create(
name="Workflow Test Number",
workflow_id=workflow_id,
)
print(f"Phone number created: {phone_number.number}")
# Make an outbound test call
test_call = client.calls.create(
workflow_id=workflow_id,
customer={
"number": "+1234567890", # Replace with your test number
},
)
print(f"Test call initiated: {test_call.id}")
return {"phone_number": phone_number, "test_call": test_call}
except Exception as error:
print(f"Error testing workflow: {error}")
raise error
# Test your workflow
test_workflow("your-workflow-id")
```
```bash
# Create phone number with workflow
curl -X POST "https://api.vapi.ai/phone-number" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Workflow Test Number",
"workflowId": "your-workflow-id"
}'
# Make an outbound test call
curl -X POST "https://api.vapi.ai/call" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "your-workflow-id",
"customer": {
"number": "+1234567890"
}
}'
```
## Next Steps
* [**Workflows overview**](/workflows/overview) - Learn about all node types and advanced configuration options
* [**Workflow examples**](/workflows/examples) - Explore pre-built workflows for common business use cases
* [**Custom Tools**](/tools/custom-tools) - Integrate external APIs and services into your workflows
* [**Dynamic Variables**](/assistants/dynamic-variables) - Advanced variable usage and personalization techniques
# Workflows overview
> Learn to create robust, deterministic conversation flows with a visual builder.
## Introduction
Workflows is a visual builder designed for creating robust, deterministic conversation flows. It empowers developers and low-code builders to design agents through an intuitive interface representing interactions via nodes and edges.
**Key Benefits:**
* **Visual Conversation Builder:** Easily prototype and demonstrate conversation flows visually.
* **Complex Flow Management:** Ideal for scenarios with numerous interaction paths, such as call centers, customer support, appointment scheduling, and onboarding processes.
* **Reliable Determinism:** Offers stronger control compared to single-prompt Assistants, ensuring predictable conversational paths even in highly complex flows.
* **Developer-Focused Flexibility:** Fully configurable via API, enabling selection of models, transcribers, and voices available throughout the Vapi platform.
* **Multilingual Support:** Seamlessly build multilingual conversation flows with language-specific nodes and prompts.
**Common Use Patterns:**
* **User Intent Manager:** Route user interactions based on specific intents.
* **Human Escalation Paths:** Allow users to transfer to human agents at any workflow stage.
* **Multilingual Flows:** Create dedicated conversation branches for different languages.
* **Customer-Specific Flows:** Differentiate workflows based on user profiles, such as new versus existing customers.
## Workflow structure
Workflows consists of node and edges. There are multiple types of nodes and a Workflow must have a start node, which is the main entry point for the conversation flow.
By default a Conversation Node is the start node, but it can be changed to a different type of note. Start nodes cannot be deleted and a Workflow must have exactly one.
## Node Types and Configuration
### Conversation Node
The Conversation Node is the default type of node. It's highly configurable and it's the main building block for conversation flows.
**Configuration options**
* **First Message**: Specify the initial spoken message when entering the node. This configuration is helpful if developers want the agent to speak first without waiting for user to say something.
* **Prompt**: Provide detailed instructions guiding agent responses and conversation direction, including response style and content. The prompt is the most important part of the Conversation Node. Building reliable and high-quality voice agents heavily depend on the quality of the prompt supplied.
* **Model/Voice/Transcriber Settings**: Individually configure the AI model, voice, and transcription services per node. This is similar to configuring Single Prompt Assistants.
* **Extract Variables**: Extract Variables lets users gather/extract variables from a conversation. These variables can be used as dynamic variables for the rest of the workflow via liquid syntax `{{ variable_name }}`. Variables can be configured by defining variable name and data type (String, Number, Boolean, Integer), writing a clear extraction prompt, and setting enums for String-type variables to constrain values.
### API Request Node
The API Request Node allows developers to make HTTP Requests to their API, custom endpoints, or automation services like Make, n8n, or Zapier. Developers can configure it to perform GET and POST requests. Request bodies must be formatted in [JSON Schema](https://json-schema.org/) (the body UI builder automatically does this).
### Transfer Call Node
Transfer calls to another phone number, including human agents or specialized voice agents.
Developers can specify a phone number destination and a [transfer plan](/call-forwarding#call-transfers-mode), which lets them specify a message or a summary of the call to the person or agent picking up in the destination number before actually connecting the caller.
### End Call Node
Terminal node to end calls explicitly. Configure with an optional closing message (via the first message field) to users before termination.
Workflows without a defined End Call Node risk unintended minutes usage. Ensure all workflows have clear termination points to ensure the call eventually ends.
### Tool Node
Integrate existing Tools library functionalities. Select tools previously created for use within Workflows, maintaining consistency with Assistant configurations.
### Global Node
Allows routing to this node from any point in the workflow, commonly used for escalation purposes e.g. when user wants to jump from the pre-determined conversation flow to speaking to a human to address specific needs. This feature can be enabled via the Global toggle; developers must specify an Enter Condition that defines the condition for routing to the Global Node.
## Edges
A node is connected to another node via an edge. Developers can specify a condition (within the edge) that must be true (satisfied) for the conversation to flow from one node to the next.
#### AI-based conditions
Written in plain language and evaluated by LLMs:
```txt
User wanted to talk about voice agents
```
#### Logical conditions
For precise control using variables:
```txt
{{ city == "San Francisco" }}
```
#### Combined conditions
Mix logical operators with variables:
```txt
{{ customer_tier == "VIP" or total_orders > 50 }}
```
**Best practices for conditions:**
* Use descriptive, natural language for AI-based conditions
* Format conditions as: "User \[verb] \[rest of condition]"
* Extract variables as enums to enable reliable branching
* Test all conditional paths thoroughly
* Keep conditions simple and specific
A useful combination of features is to extract variables as enums and use them to branch conversation flows based on a specific set of tasks that the agent can help users with.
## Best practices
### Planning and design
* **Map conversation flows first** - Plan all possible user journeys before building
* **Use descriptive node names** - Make workflows easier to understand and maintain
* **Handle edge cases** - Add global nodes for common scenarios like user confusion
### Implementation
* **Keep prompts focused** - Each node should have a single, clear purpose
* **Test thoroughly** - Use the built-in calling feature to test all conversation paths
* **Use variables strategically** - Extract only necessary information and use it to personalize conversations
### Optimization
* **Monitor performance** - Review call logs and analytics to optimize workflows over time
* **Plan for scale** - Consider how workflows will perform with high call volumes
* **Version control** - Keep track of workflow changes and test before deploying
## Next steps
Ready to start building? Check out these resources:
* [**Workflows quickstart**](/workflows/quickstart) - Build your first workflow step-by-step
* [**Workflow examples**](/workflows/examples/appointment-scheduling) - Explore pre-built workflows for common use cases
* [**Custom Tools**](/tools/custom-tools) - Integrate external APIs and services into your workflows
* [**Dynamic Variables**](/assistants/dynamic-variables) - Advanced variable usage and personalization techniques
# Appointment scheduling workflow
> Build a voice AI appointment scheduling workflow with calendar integration, availability checking, and automated confirmations using Vapi's workflow builder.
## Overview
Build an AI-powered appointment scheduling workflow that handles inbound calls for booking, rescheduling, and canceling appointments. The workflow uses visual nodes to create branching logic, integrates with calendar systems, checks availability in real-time, and sends confirmation messages.
**What You'll Build:**
* Visual workflow with branching appointment logic
* Real-time calendar integration and availability checking
* Customer database with automated confirmations
* Global nodes for error handling and validation
* 24/7 phone booking with conditional routing
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
* A Google Calendar account (or other calendar service).
## Scenario
We will be creating an appointment scheduling workflow for Tony's Barbershop, a traditional barbershop that wants to automate their phone booking process with sophisticated branching logic to handle different appointment scenarios.
## Final Workflow
***
## 1. Create a Knowledge Base
In your Vapi dashboard, click `Files` in the left sidebar.
* Click `Choose file`. Upload all three CSV files: `services.csv`, `customers.csv`, and `appointments.csv`.
* Note the file IDs. We'll need them later to create tools.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
import fs from 'fs';
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function uploadAppointmentFiles() {
try {
// Upload services file
const servicesFile = await vapi.files.create({
file: fs.createReadStream("services.csv")
});
// Upload customers file
const customersFile = await vapi.files.create({
file: fs.createReadStream("customers.csv")
});
// Upload appointments file
const appointmentsFile = await vapi.files.create({
file: fs.createReadStream("appointments.csv")
});
console.log(`Services file ID: ${servicesFile.id}`);
console.log(`Customers file ID: ${customersFile.id}`);
console.log(`Appointments file ID: ${appointmentsFile.id}`);
return {
servicesFileId: servicesFile.id,
customersFileId: customersFile.id,
appointmentsFileId: appointmentsFile.id
};
} catch (error) {
console.error('Error uploading files:', error);
throw error;
}
}
// Upload all files for appointment workflow
const fileIds = await uploadAppointmentFiles();
```
```python
import requests
def upload_appointment_file(file_path):
"""Upload a CSV file for appointment workflow data"""
url = "https://api.vapi.ai/file"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
try:
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error uploading {file_path}: {error}")
raise
# Upload all required files for appointment workflow
services_file = upload_appointment_file("services.csv")
customers_file = upload_appointment_file("customers.csv")
appointments_file = upload_appointment_file("appointments.csv")
print(f"Services file ID: {services_file['id']}")
print(f"Customers file ID: {customers_file['id']}")
print(f"Appointments file ID: {appointments_file['id']}")
```
```bash
# Upload services.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@services.csv"
# Upload customers.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@customers.csv"
# Upload appointments.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@appointments.csv"
```
***
## 2. Create a Workflow
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Workflows` in the left sidebar.
* Click `Create Workflow`.
* Enter workflow name: `Barbershop Appointment Workflow`.
* Select the default template (includes Call Start node).
* Click "Create Workflow".
* Configure workflow variables for customer data and appointment information
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createAppointmentWorkflow() {
try {
// Create workflow with initial greeting node
const workflow = await vapi.workflows.create({
name: "Barbershop Appointment Workflow",
nodes: [
{
id: "greeting",
type: "conversation",
firstMessage: "Hello! Thank you for calling Tony's Barbershop. This is Sarah, your booking assistant. I can help you schedule, reschedule, or cancel appointments. How can I help you today?",
systemPrompt: "You are Sarah, the friendly booking assistant for Tony's Barbershop. Listen to the customer's response and determine their intent: schedule, reschedule, cancel, status, or other. Keep responses under 35 words.",
extractVariables: [
{
name: "intent",
type: "string",
description: "The customer's primary intent",
enum: ["schedule", "reschedule", "cancel", "status", "other"]
}
]
}
],
edges: []
});
console.log(`Workflow created with ID: ${workflow.id}`);
return workflow;
} catch (error) {
console.error('Error creating workflow:', error);
throw error;
}
}
// Create the appointment workflow
const workflow = await createAppointmentWorkflow();
```
```python
import requests
def create_appointment_workflow():
"""Create a new appointment scheduling workflow"""
url = "https://api.vapi.ai/workflow"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "Barbershop Appointment Workflow",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"firstMessage": "Hello! Thank you for calling Tony's Barbershop. This is Sarah, your booking assistant. I can help you schedule, reschedule, or cancel appointments. How can I help you today?",
"systemPrompt": "You are Sarah, the friendly booking assistant for Tony's Barbershop. Listen to the customer's response and determine their intent: schedule, reschedule, cancel, status, or other. Keep responses under 35 words.",
"extractVariables": [
{
"name": "intent",
"type": "string",
"description": "The customer's primary intent",
"enum": ["schedule", "reschedule", "cancel", "status", "other"]
}
]
}
],
"edges": []
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error creating workflow: {error}")
raise
# Create the appointment workflow
workflow = create_appointment_workflow()
print(f"Workflow created with ID: {workflow['id']}")
```
```bash
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Barbershop Appointment Workflow",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"firstMessage": "Hello! Thank you for calling Tony'\''s Barbershop. This is Sarah, your booking assistant. I can help you schedule, reschedule, or cancel appointments. How can I help you today?",
"systemPrompt": "You are Sarah, the friendly booking assistant for Tony'\''s Barbershop. Listen to the customer'\''s response and determine their intent: schedule, reschedule, cancel, status, or other. Keep responses under 35 words.",
"extractVariables": [
{
"name": "intent",
"type": "string",
"description": "The customer'\''s primary intent",
"enum": ["schedule", "reschedule", "cancel", "status", "other"]
}
]
}
],
"edges": []
}'
```
***
## 3. Build the Workflow
You'll start with a default template that includes a "Call Start" node. We'll modify the existing nodes and add new ones to create our appointment scheduling workflow.
The default template includes a conversation node. Click on it and configure:
```txt title="First Message"
Hello! Thank you for calling Tony's Barbershop. This is Sarah, your booking assistant. I can help you schedule, reschedule, or cancel appointments. How can I help you today?
```
```txt title="Prompt"
You are Sarah, the friendly booking assistant for Tony's Barbershop.
Listen to the customer's response and determine their intent:
- "schedule" for new appointments
- "reschedule" for changing existing appointments
- "cancel" for canceling appointments
- "status" for checking appointment details
- "other" for anything else
Keep responses under 35 words. Ask clarifying questions if intent is unclear.
```
**Extract Variables**:
* Variable: `intent`
* Type: `String`
* Description: `The customer's primary intent`
* Enum Values: `schedule`, `reschedule`, `cancel`, `status`, `other`
Click the + button below the greeting node and add a new **Conversation** node:
```txt title="Condition"
Intent identified
```
```txt title="First Message"
Now I need to verify your information. Can you please provide your phone number or full name so I can look up your account?
```
```txt title="Prompt"
You are collecting customer identification information to look them up in the system.
If they provide a phone number, extract it in a clean format (numbers only).
If they provide a name, extract their full name.
Be friendly and reassuring about privacy. Keep responses under 25 words.
```
**Extract Variables**:
* Variable: `phone_number`
* Type: `String`
* Description: `Customer's phone number if provided`
* Variable: `customer_name`
* Type: `String`
* Description: `Customer's full name if provided`
Add a **Tool** node:
```txt title="Condition"
Customer information collected
```
**Select Tool**: Choose your pre-configured customer lookup tool from the dropdown. This tool will use the extracted `phone_number` and `customer_name` variables to find the customer in your database.
Create branching paths based on the customer's intent. Add multiple conversation nodes:
**Schedule New Appointment Node**:
```txt title="Condition"
Customer verified and intent is schedule
```
```txt title="First Message"
Great! I can help you schedule a new appointment. What type of service would you like? We offer haircuts, beard trims, shampoo and styling, and full grooming packages.
```
```txt title="Prompt"
You are helping the customer schedule a new appointment.
Listen for the service they want and any preferred dates/times they mention.
Be enthusiastic and helpful. Keep responses under 30 words.
If they're unsure about services, briefly describe each option.
```
**Reschedule Appointment Node**:
```txt title="Condition"
Customer verified and intent is reschedule
```
```txt title="First Message"
I can help you reschedule your appointment. Let me first look up your current booking details.
```
```txt title="Prompt"
You are helping the customer reschedule an existing appointment.
Be understanding and accommodating. Look up their current appointment first.
Keep responses under 25 words while being empathetic.
```
**Cancel Appointment Node**:
```txt title="Condition"
Customer verified and intent is cancel
```
```txt title="First Message"
I can help you cancel your appointment. Let me look up your current booking to confirm the details.
```
```txt title="Prompt"
You are helping the customer cancel their appointment.
Be understanding and offer to reschedule instead if appropriate.
Confirm cancellation details before proceeding. Keep responses under 25 words.
```
Create a global conversation node that checks for errors after every step:
```txt title="Condition"
Customer confused or error detected
```
```txt title="First Message"
I apologize for any confusion. Let me transfer you to one of our human staff members who can better assist you. Please hold for just a moment.
```
```txt title="Prompt"
You are handling an error or confused customer situation.
Be apologetic and professional. Prepare them for transfer to human staff.
Keep the message brief and reassuring.
```
This global node will activate whenever there's an error or the customer becomes frustrated, regardless of where they are in the workflow.
For the schedule appointment flow, add these nodes:
**Service Selection Node** (Conversation):
```txt title="Condition"
Service type mentioned or requested
```
```txt title="First Message"
Perfect! And when would you prefer to come in? What date and time work best for you?
```
```txt title="Prompt"
You are collecting appointment preferences for scheduling.
Listen for specific dates, times, or general preferences like "morning" or "next week".
Be flexible and offer to check availability. Keep responses under 25 words.
```
**Extract Variables**:
* Variable: `service_type`
* Type: `String`
* Description: `Type of service requested`
* Variable: `preferred_date`
* Type: `String`
* Description: `Customer's preferred date`
* Variable: `preferred_time`
* Type: `String`
* Description: `Customer's preferred time`
**Availability Check Tool Node**:
```txt title="Condition"
Preferences collected
```
**Select Tool**: Choose "Check Availability" from the pre-defined calendar tools
* This will automatically check available slots based on the extracted preferences
**Availability Results Node** (Conversation):
```txt title="Condition"
Availability checked
```
```txt title="First Message"
Based on your preferences, here are the available time slots. Which one works best for you?
```
```txt title="Prompt"
You are presenting available appointment times to the customer.
Present 2-3 options clearly with dates and times.
If their preferred time isn't available, offer the closest alternatives.
Be helpful and accommodating. Keep responses under 35 words.
```
**Booking Confirmation Node** (Conversation):
```txt title="Condition"
Time slot selected
```
```txt title="First Message"
Perfect! Let me confirm your appointment details: [service] on [date] at [time]. Is this correct?
```
```txt title="Prompt"
You are confirming appointment details before booking.
Read back the service type, date, and time clearly.
Wait for their confirmation before proceeding.
Be thorough but concise. Keep responses under 30 words.
```
**Extract Variables**:
* Variable: `confirmation_status`
* Type: `String`
* Description: `Whether customer confirms the appointment details`
**Create Appointment Tool Node**:
```txt title="Condition"
Appointment details confirmed
```
**Select Tool**: Choose "Schedule Event" from the pre-defined calendar tools
* This will book the appointment in your calendar system
**Send Confirmation Node** (Tool):
```txt title="Condition"
Appointment created successfully
```
**Select Tool**: Choose your pre-configured SMS/email confirmation tool
**Completion Node** (Conversation):
```txt title="Condition"
Confirmation sent
```
```txt title="First Message"
Great! Your appointment is confirmed. You'll receive a confirmation message shortly. Is there anything else I can help you with today?
```
```txt title="Prompt"
You are wrapping up a successful appointment booking.
Be friendly and offer additional assistance.
If they say no, prepare to end the call politely.
Keep responses under 25 words.
```
**Transfer to Human Node**:
```txt title="Condition"
Customer requests human assistance
```
**Node Type**: `Transfer Call`
**Phone to transfer to**: `+1-555-BARBER-1` (your barbershop number)
**End Call Node**:
```txt title="Condition"
Customer satisfied and no further assistance needed
```
**Node Type**: `End Call`
**First Message**: `Thank you for calling Tony's Barbershop. Have a great day!`
* Use when customer is satisfied and no further assistance needed
## 4. Configure Phone Number
Click `Phone Numbers` in the left sidebar of your dashboard.
* Click `Create Phone Number` for a new Vapi number, or
* Click `Import Phone Number` to use your existing number from Twilio/Telnyx
**Workflow**: Select your `Barbershop Appointment Workflow`
**Advanced Settings**:
* Enable call recording for quality assurance
* Set maximum call duration (e.g., 15 minutes)
* Configure voicemail detection if needed
Call your Vapi phone number to test the complete workflow:
* Test different appointment scenarios
* Verify branching logic works correctly
* Ensure global nodes trigger appropriately
* Test error handling and recovery flows
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createAppointmentPhoneNumber(workflowId: string) {
try {
// Create phone number for appointment workflow
const phoneNumber = await vapi.phoneNumbers.create({
name: "Barbershop Booking Line",
workflowId: workflowId,
inboundSettings: {
maxCallDurationMinutes: 15,
recordingEnabled: true,
voicemailDetectionEnabled: true
}
});
console.log(`Appointment phone number created: ${phoneNumber.number}`);
return phoneNumber;
} catch (error) {
console.error('Error creating phone number:', error);
throw error;
}
}
async function testAppointmentWorkflow(workflowId: string, testNumber: string) {
try {
// Test the appointment workflow with an outbound call
const call = await vapi.calls.create({
workflowId: workflowId,
customer: {
number: testNumber
}
});
console.log(`Appointment workflow test call created: ${call.id}`);
return call;
} catch (error) {
console.error('Error testing workflow:', error);
throw error;
}
}
// Create phone number and test workflow
const phoneNumber = await createAppointmentPhoneNumber('YOUR_WORKFLOW_ID');
const testCall = await testAppointmentWorkflow('YOUR_WORKFLOW_ID', '+1234567890');
```
```python
import requests
def create_appointment_phone_number(workflow_id):
"""Create phone number for appointment workflow"""
url = "https://api.vapi.ai/phone-number"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "Barbershop Booking Line",
"workflowId": workflow_id,
"inboundSettings": {
"maxCallDurationMinutes": 15,
"recordingEnabled": True,
"voicemailDetectionEnabled": True
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error creating phone number: {error}")
raise
def test_appointment_workflow(workflow_id, test_number):
"""Test appointment workflow with outbound call"""
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"workflowId": workflow_id,
"customer": {
"number": test_number
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error testing workflow: {error}")
raise
# Create phone number and test
phone_number = create_appointment_phone_number('YOUR_WORKFLOW_ID')
test_call = test_appointment_workflow('YOUR_WORKFLOW_ID', '+1234567890')
print(f"Phone number: {phone_number['number']}")
print(f"Test call ID: {test_call['id']}")
```
```bash
# Create phone number with workflow
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Barbershop Booking Line",
"workflowId": "YOUR_WORKFLOW_ID",
"inboundSettings": {
"maxCallDurationMinutes": 15,
"recordingEnabled": true,
"voicemailDetectionEnabled": true
}
}'
# Test the workflow with an outbound call
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567890"
}
}'
```
## Next Steps
Just like that, you've built an automated appointment scheduling workflow that can handle inbound calls, manage bookings, and provide 24/7 availability for your barbershop.
Consider reading the following guides to further enhance your workflow:
* [**Custom Tools**](/tools/custom-tools) - Create custom tools for calendar integration and customer management.
* [**Voice Formatting Plan**](/assistants/voice-formatting-plan) - Configure speech formatting for clear appointment communication.
* [**Dynamic Variables**](/assistants/dynamic-variables) - Use variables to personalize appointment confirmations.
# Lead qualification workflow
> Build a voice AI outbound sales workflow with lead qualification, CRM integration, and automated follow-up using Vapi's visual workflow builder.
## Overview
Build an AI-powered outbound sales workflow that qualifies leads, handles objections, and schedules appointments using Vapi workflows with sophisticated branching logic and CRM integration.
**What You'll Build:**
* Lead qualification with BANT scoring and conditional routing
* Objection handling with global nodes and sentiment analysis
* Appointment scheduling with calendar integration
* CRM updates with automated follow-up sequences
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
* A CRM system or customer database.
* A calendar system for appointment scheduling.
## Scenario
We will be creating an outbound sales workflow for TechFlow Solutions, a B2B software company that wants to automate their lead qualification process with sophisticated branching logic to handle different prospect scenarios and increase appointment booking rates.
## Final Workflow
***
## 1. Create a Knowledge Base
In your Vapi dashboard, click `Files` in the left sidebar.
* Click `Choose file`. Upload all three CSV files: `leads.csv`, `products.csv`, and `call_outcomes.csv`.
* Note the file IDs. We'll need them later to create tools.
***
## 2. Create Required Tools
Before building the workflow, create the necessary tools in your dashboard:
In your Vapi dashboard, click `Tools` in the left sidebar.
Click `Create Tool` and configure:
* **Tool Name**: "Lead Lookup"
* **Tool Type**: "Function"
* **Function Name**: `lookup_lead`
* **Description**: "Retrieve lead information and call history"
* **Parameters**:
* `lead_id` (string): Lead ID to lookup
* **Server URL**: `https://jsonplaceholder.typicode.com/users`
This example uses JSONPlaceholder for demonstration. In production, replace with your CRM API (Salesforce, HubSpot, etc.).
Create another tool:
* **Tool Name**: "Lead Scoring"
* **Function Name**: `score_lead`
* **Description**: "Score leads based on qualification responses"
* **Parameters**:
* `budget` (string): Budget information
* `authority` (string): Decision-making authority
* `need` (string): Business need assessment
* `timeline` (string): Purchase timeline
* **Server URL**: `https://jsonplaceholder.typicode.com/posts`
This example uses JSONPlaceholder for demonstration. Replace with your lead scoring system in production.
Create a third tool:
* **Tool Name**: "CRM Update"
* **Function Name**: `update_crm`
* **Description**: "Update CRM with call outcomes and next steps"
* **Parameters**:
* `lead_id` (string): Lead identifier
* `call_outcome` (string): Result of the call
* `next_steps` (string): Planned follow-up actions
* **Server URL**: `https://jsonplaceholder.typicode.com/posts`
This example uses JSONPlaceholder for demonstration. In production, integrate with your CRM system.
***
## 3. Create a Workflow
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Workflows` in the left sidebar.
* Click `Create Workflow`.
* Enter workflow name: `TechFlow Sales Qualification Workflow`.
* Select the default template (includes Call Start node).
* Click `Create Workflow`.
***
## 4. Build the Workflow
You'll start with a default template that includes a "Call Start" node. We'll modify the existing nodes and add new ones to create our outbound sales workflow.
The default template includes a conversation node. Click on it and configure:
**Node Name**: `opening_and_permission`
```txt title="First Message"
Hi, this is Alex calling from TechFlow Solutions. I hope I'm catching you at a good time. I'm reaching out because I noticed your company might benefit from our workflow automation platform. Do you have just 2 minutes to chat?
```
```txt title="Prompt"
You are Alex, a professional outbound sales representative for TechFlow Solutions.
Listen for their response and determine:
- "permission_granted" if they agree to talk
- "busy_reschedule" if they're busy but open to rescheduling
- "not_interested" if they decline
- "gatekeeper" if you're speaking to someone who isn't the decision maker
Keep responses under 30 words and be respectful of their time.
```
**Extract Variables**:
* Variable: `permission_status`
* Type: `String`
* Description: `The prospect's response to the initial request`
* Enum Values: `permission_granted`, `busy_reschedule`, `not_interested`, `gatekeeper`
Add a **Tool** node that runs before the opening:
```txt title="Condition"
Call initiated
```
**Tool**: Select your pre-configured "Lead Lookup" tool from the dropdown. This tool should be created in the **Tools** section of your dashboard with:
* **Function Name**: `lookup_lead`
* **Description**: "Retrieve lead information and call history"
* **Parameters**:
* `lead_id` (string): Lead ID to lookup
* **Server URL**: `https://jsonplaceholder.typicode.com/users`
Create branching paths based on the prospect's response. Add multiple conversation nodes:
**Discovery Questions Node**:
```txt title="Condition"
Permission granted to continue conversation
```
**Node Name**: `discovery_questions`
```txt title="First Message"
Great! I appreciate your time. To better understand how we might help, can you tell me about your current workflow challenges? Specifically, what manual processes are taking up most of your team's time?
```
```txt title="Prompt"
You are conducting discovery to understand their business challenges.
Ask open-ended questions about their pain points and workflows.
Listen for automation opportunities and budget indicators.
Keep responses under 35 words and be genuinely curious.
```
**Reschedule Node**:
```txt title="Condition"
Prospect is busy but willing to reschedule
```
**Node Name**: `schedule_callback`
```txt title="First Message"
I completely understand. When would be a better time for a quick 5-minute conversation? I have availability tomorrow morning or afternoon.
```
```txt title="Prompt"
You are scheduling a callback with a busy prospect.
Be flexible with their schedule and offer specific time options.
Confirm the callback time and set a reminder.
Keep responses under 25 words.
```
**Objection Handling Node**:
```txt title="Condition"
Prospect shows initial resistance or not interested
```
**Node Name**: `handle_initial_objection`
```txt title="First Message"
I understand you might not be looking for new solutions right now. Can I ask what you're currently using for workflow automation? I might have some insights that could be valuable.
```
```txt title="Prompt"
You are handling initial objections with curiosity and value.
Don't be pushy. Ask questions to understand their current situation.
Offer insights rather than pushing for a sale.
Keep responses under 30 words.
```
**Gatekeeper Node**:
```txt title="Condition"
Speaking with gatekeeper or non-decision maker
```
**Node Name**: `gatekeeper_routing`
```txt title="First Message"
I appreciate you taking the call. I'm looking to speak with whoever handles software decisions or operations. Would that be you, or could you point me in the right direction?
```
```txt title="Prompt"
You are working with a gatekeeper to reach the decision maker.
Be respectful and professional. Get the right contact or decision maker.
Build rapport with the gatekeeper as they can help or hinder.
Keep responses under 30 words.
```
Connect the nodes with conditions for the LLM to interpret:
**To Discovery Questions Node**:
* Condition: `Permission granted to continue conversation`
**To Reschedule Node**:
* Condition: `Prospect is busy but willing to reschedule`
**To Objection Handling Node**:
* Condition: `Prospect shows initial resistance or not interested`
**To Gatekeeper Node**:
* Condition: `Speaking with gatekeeper or non-decision maker`
Create a global node that handles objections throughout the call:
```txt title="Condition"
Objection detected or negative sentiment
```
**Node Name**: `objection_handler`
**Global Node**: `enabled = true`
**Enter Condition**: `{{ objection_detected == true or negative_sentiment == true }}`
```txt title="First Message"
I hear your concern, and that's completely valid. Many of our clients had similar thoughts initially. Let me address that specific point and see if we can find a solution that makes sense for your situation.
```
```txt title="Prompt"
You are handling an objection with empathy and understanding.
Acknowledge their concern as valid. Use social proof.
Address the specific objection with relevant information.
Keep responses under 35 words.
```
This global node will activate whenever an objection is detected, regardless of where they are in the sales conversation.
For prospects who engage, add these qualification nodes:
**BANT Qualification Node**:
```txt title="Condition"
Prospect engaged and willing to discuss needs
```
**Node Name**: `bant_qualification`
```txt title="First Message"
That's helpful context. To better understand if we're a fit, can you tell me about your budget range for workflow automation tools? Also, who typically makes software purchasing decisions at your company?
```
```txt title="Prompt"
You are qualifying the prospect using BANT criteria (Budget, Authority, Need, Timeline).
Ask about budget, decision-making process, specific needs, and timeline.
Be natural - don't make it feel like an interrogation.
Keep responses under 35 words.
```
**Extract Variables**:
* Variable: `budget_range`
* Type: `String`
* Description: `Budget information provided`
* Variable: `decision_authority`
* Type: `String`
* Description: `Decision-making authority level`
* Variable: `timeline`
* Type: `String`
* Description: `Purchase timeline or urgency`
**Lead Scoring Tool Node**:
```txt title="Condition"
BANT qualification completed
```
* Add a **Tool** node that calls lead scoring API based on qualification responses
**Qualification Results Node**:
```txt title="Condition"
Lead score calculated
```
**Node Name**: `route_by_score`
```txt title="First Message"
Based on what you've shared, it sounds like there could be a great fit here. Let me show you how we've helped similar companies in your industry.
```
```txt title="Prompt"
You are routing the conversation based on lead qualification score.
High scores get immediate demo offers.
Medium scores get value proposition and nurturing.
Low scores get educational content and future follow-up.
Keep responses under 30 words.
```
* Route based on lead score (hot, warm, cold)
**Industry-Specific Pitch Node**:
```txt title="Condition"
Qualified prospect ready for value proposition
```
**Node Name**: `tailored_pitch`
```txt title="First Message"
Given your challenges with [specific pain point], let me share how we helped [similar company] reduce their manual processes by 60% and save 15 hours per week.
```
```txt title="Prompt"
You are presenting a tailored value proposition based on their specific situation.
Use relevant case studies and specific benefits.
Connect features to their stated pain points.
Keep responses under 40 words.
```
* Present value proposition based on their industry and pain points
**ROI Demonstration Node**:
```txt title="Condition"
Interest shown in value proposition
```
**Node Name**: `show_roi`
```txt title="First Message"
Here's what that looks like in real numbers: if your team spends 20 hours a week on manual processes, our platform could save you $50,000 annually in productivity gains.
```
```txt title="Prompt"
You are demonstrating concrete ROI with specific numbers.
Use their company size and situation to calculate relevant savings.
Make the ROI tangible and compelling.
Keep responses under 35 words.
```
* Provide specific ROI examples and case studies
**Demo Offer Node**:
```txt title="Condition"
Strong interest and ROI demonstrated
```
**Node Name**: `offer_demo`
```txt title="First Message"
I'd love to show you exactly how this would work for your specific workflow. Could we schedule a 15-minute demo where I can walk you through a custom setup for your team?
```
```txt title="Prompt"
You are proposing a product demonstration meeting.
Make the demo offer specific and time-bounded.
Emphasize the custom/personalized aspect.
Be confident but not pushy. Keep responses under 30 words.
```
* Propose a product demonstration meeting
**Calendar Check Tool Node**:
```txt title="Condition"
Demo requested and prospect interested
```
* Add a **Tool** node that checks sales team calendar for available demo slots
**Appointment Confirmation Node**:
```txt title="Condition"
Demo slot available
```
**Node Name**: `confirm_appointment`
```txt title="First Message"
Perfect! I have availability for a demo on [date] at [time]. I'll send you a calendar invite with a Zoom link. Should I include anyone else from your team?
```
```txt title="Prompt"
You are confirming the demo appointment details.
Confirm date, time, and attendees. Offer to include other stakeholders.
Set expectations for what they'll see in the demo.
Keep responses under 35 words.
```
* Confirm meeting details and send calendar invite
**CRM Update Tool Node**:
```txt title="Condition"
Appointment confirmed
```
* Add a **Tool** node that records call outcome and next steps in CRM
**Transfer to Sales Rep Node**:
```txt title="Condition"
High-value prospect requests immediate consultation
```
**Node Type**: `Transfer`
**Destination**: `+1-555-SALES-1` (your sales team number)
**Schedule Follow-up Node**:
```txt title="Condition"
Prospect interested but not ready for demo
```
**Node Name**: `schedule_followup`
```txt title="First Message"
I understand you need some time to think it over. When would be a good time for me to follow up? I can also send you some relevant case studies in the meantime.
```
```txt title="Prompt"
You are scheduling a follow-up call for future nurturing.
Be patient and respectful of their timeline.
Offer valuable content to keep them engaged.
Keep responses under 30 words.
```
* Set automated follow-up call for future date
**End Call Node**:
```txt title="Condition"
Prospect not qualified or requests no further contact
```
**Node Type**: `Hangup`
* Use when prospect is not qualified or requests no further contact
## Integrating with Real Systems
This example uses JSONPlaceholder for demonstration purposes. To integrate with your actual sales systems:
### CRM Platform Integration
* **Salesforce**: Use the [Salesforce REST API](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/)
* **HubSpot**: Use the [HubSpot API](https://developers.hubspot.com/docs/api/overview)
* **Pipedrive**: Use the [Pipedrive API](https://developers.pipedrive.com/docs/api/v1)
### Calendar Integration
* **Google Calendar**: [Google Calendar API](https://developers.google.com/calendar/api)
* **Microsoft Outlook**: [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/api/resources/calendar)
* **Calendly**: [Calendly API](https://developer.calendly.com/)
### Communication Tools
* **Twilio**: [Twilio API](https://www.twilio.com/docs/usage/api) for SMS and voice
* **SendGrid**: [SendGrid API](https://docs.sendgrid.com/api-reference) for email
* **Slack**: [Slack API](https://api.slack.com/) for team notifications
## Next Steps
Just like that, you've built an outbound sales qualification workflow that can handle lead qualification, objection handling, and appointment scheduling with automated CRM integration.
Consider reading the following guides to further enhance your workflow:
* [**Custom Tools**](/tools/custom-tools) - Create custom tools for CRM integration and lead management.
* [**Voice Formatting Plan**](/assistants/voice-formatting-plan) - Configure speech patterns for professional sales conversations.
* [**Call Analysis**](/assistants/call-analysis) - Analyze call performance and optimize sales conversations.
# Clinic triage and scheduling workflow
> Build a voice AI clinic workflow with medical triage protocols, appointment booking, and emergency routing using Vapi's visual workflow builder.
## Overview
Build an AI-powered clinic receptionist workflow that handles patient triage, appointment scheduling, and emergency routing using Vapi workflows with medical protocol compliance and safety monitoring.
**What You'll Build:**
* Medical triage assessment with symptom-based routing
* Emergency detection with global safety protocols
* Provider scheduling with urgency prioritization
* Prescription refill processing with safety checks
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
* Medical triage protocols and guidelines.
* Healthcare provider scheduling system.
## Scenario
We will be creating a triage and scheduling workflow for Riverside Family Clinic, a primary care practice that wants to improve patient access while ensuring appropriate care routing and emergency response through sophisticated workflow automation.
## Final Workflow
***
## 1. Create a Knowledge Base
In your Vapi dashboard, click `Files` in the left sidebar.
* Click `Choose file`. Upload all four CSV files: `patients.csv`, `providers.csv`, `triage_protocols.csv`, and `appointments.csv`.
* Note the file IDs. We'll need them later to create tools.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
import fs from 'fs';
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function uploadClinicFiles() {
try {
// Upload patients file
const patientsFile = await vapi.files.create({
file: fs.createReadStream("patients.csv")
});
// Upload providers file
const providersFile = await vapi.files.create({
file: fs.createReadStream("providers.csv")
});
// Upload triage protocols file
const triageProtocolsFile = await vapi.files.create({
file: fs.createReadStream("triage_protocols.csv")
});
// Upload appointments file
const appointmentsFile = await vapi.files.create({
file: fs.createReadStream("appointments.csv")
});
console.log(`Patients file ID: ${patientsFile.id}`);
console.log(`Providers file ID: ${providersFile.id}`);
console.log(`Triage protocols file ID: ${triageProtocolsFile.id}`);
console.log(`Appointments file ID: ${appointmentsFile.id}`);
return {
patientsFileId: patientsFile.id,
providersFileId: providersFile.id,
triageProtocolsFileId: triageProtocolsFile.id,
appointmentsFileId: appointmentsFile.id
};
} catch (error) {
console.error('Error uploading clinic files:', error);
throw error;
}
}
// Upload all files for clinic workflow
const fileIds = await uploadClinicFiles();
```
```python
import requests
def upload_clinic_file(file_path):
"""Upload a CSV file for clinic workflow data"""
url = "https://api.vapi.ai/file"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
try:
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error uploading {file_path}: {error}")
raise
# Upload all required files for clinic workflow
patients_file = upload_clinic_file("patients.csv")
providers_file = upload_clinic_file("providers.csv")
triage_protocols_file = upload_clinic_file("triage_protocols.csv")
appointments_file = upload_clinic_file("appointments.csv")
print(f"Patients file ID: {patients_file['id']}")
print(f"Providers file ID: {providers_file['id']}")
print(f"Triage protocols file ID: {triage_protocols_file['id']}")
print(f"Appointments file ID: {appointments_file['id']}")
```
```bash
# Upload patients.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@patients.csv"
# Upload providers.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@providers.csv"
# Upload triage_protocols.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@triage_protocols.csv"
# Upload appointments.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@appointments.csv"
```
***
## 2. Create Required Tools
Before building the workflow, create the necessary tools in your dashboard:
In your Vapi dashboard, click **Tools** in the left sidebar.
Click **Create Tool** and configure:
* **Tool Name**: "Patient Lookup"
* **Tool Type**: "Function"
* **Function Name**: `lookup_patient`
* **Description**: "Look up patient record by ID"
* **Parameters**:
* `patient_id` (string, required): Patient's ID number
* **Server URL**: `https://jsonplaceholder.typicode.com/users`
This example uses JSONPlaceholder for demonstration. In production, replace with your EHR system API (Epic, Cerner, etc.).
Create another tool:
* **Tool Name**: "Triage Assessment"
* **Function Name**: `conduct_triage`
* **Description**: "Assess patient symptoms and determine urgency level"
* **Parameters**:
* `symptoms` (string): Description of patient symptoms
* `onset` (string): When symptoms started
* `severity` (string): Severity level (1-10)
* **Server URL**: `https://jsonplaceholder.typicode.com/posts`
This example uses JSONPlaceholder for demonstration. Replace with your medical triage system in production.
Create a third tool:
* **Tool Name**: "Schedule Appointment"
* **Function Name**: `schedule_appointment`
* **Description**: "Schedule patient appointments based on availability"
* **Parameters**:
* `patient_id` (string): Patient identifier
* `appointment_type` (string): Type of appointment needed
* `urgency_level` (string): Urgency classification
* **Server URL**: `https://jsonplaceholder.typicode.com/posts`
This example uses JSONPlaceholder for demonstration. In production, integrate with your appointment scheduling system.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createPatientLookupTool() {
try {
// Create patient lookup tool for medical records
const patientLookupTool = await vapi.tools.create({
type: "function",
function: {
name: "lookup_patient",
description: "Look up patient record by ID",
parameters: {
type: "object",
properties: {
patient_id: {
type: "string",
description: "Patient ID number"
}
},
required: ["patient_id"]
}
},
serverUrl: "https://jsonplaceholder.typicode.com/users"
});
console.log(`Patient lookup tool created: ${patientLookupTool.id}`);
return patientLookupTool;
} catch (error) {
console.error('Error creating patient lookup tool:', error);
throw error;
}
}
async function createTriageAssessmentTool() {
try {
// Create triage assessment tool for symptom evaluation
const triageAssessmentTool = await vapi.tools.create({
type: "function",
function: {
name: "conduct_triage",
description: "Assess patient symptoms and determine urgency level",
parameters: {
type: "object",
properties: {
symptoms: {
type: "string",
description: "Description of patient symptoms"
},
onset: {
type: "string",
description: "When symptoms started"
},
severity: {
type: "string",
description: "Severity level (1-10)"
}
},
required: ["symptoms"]
}
},
serverUrl: "https://jsonplaceholder.typicode.com/posts"
});
console.log(`Triage assessment tool created: ${triageAssessmentTool.id}`);
return triageAssessmentTool;
} catch (error) {
console.error('Error creating triage assessment tool:', error);
throw error;
}
}
async function createAppointmentSchedulingTool() {
try {
// Create appointment scheduling tool
const appointmentSchedulingTool = await vapi.tools.create({
type: "function",
function: {
name: "schedule_appointment",
description: "Schedule patient appointments based on availability",
parameters: {
type: "object",
properties: {
patient_id: {
type: "string",
description: "Patient identifier"
},
appointment_type: {
type: "string",
description: "Type of appointment needed"
},
urgency_level: {
type: "string",
description: "Urgency classification"
}
},
required: ["patient_id", "appointment_type"]
}
},
serverUrl: "https://jsonplaceholder.typicode.com/posts"
});
console.log(`Appointment scheduling tool created: ${appointmentSchedulingTool.id}`);
return appointmentSchedulingTool;
} catch (error) {
console.error('Error creating appointment scheduling tool:', error);
throw error;
}
}
// Create all medical tools
const patientLookupTool = await createPatientLookupTool();
const triageAssessmentTool = await createTriageAssessmentTool();
const appointmentSchedulingTool = await createAppointmentSchedulingTool();
```
```python
import requests
def create_medical_tool(name, function_name, description, parameters, server_url):
"""Create a medical workflow tool"""
url = "https://api.vapi.ai/tool"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"type": "function",
"function": {
"name": function_name,
"description": description,
"parameters": parameters
},
"serverUrl": server_url
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
tool = response.json()
print(f"{name} tool created: {tool['id']}")
return tool
except requests.exceptions.RequestException as error:
print(f"Error creating {name} tool: {error}")
raise
# Create patient lookup tool
patient_lookup_tool = create_medical_tool(
name="Patient Lookup",
function_name="lookup_patient",
description="Look up patient record by ID",
parameters={
"type": "object",
"properties": {
"patient_id": {
"type": "string",
"description": "Patient ID number"
}
},
"required": ["patient_id"]
},
server_url="https://jsonplaceholder.typicode.com/users"
)
# Create triage assessment tool
triage_assessment_tool = create_medical_tool(
name="Triage Assessment",
function_name="conduct_triage",
description="Assess patient symptoms and determine urgency level",
parameters={
"type": "object",
"properties": {
"symptoms": {
"type": "string",
"description": "Description of patient symptoms"
},
"onset": {
"type": "string",
"description": "When symptoms started"
},
"severity": {
"type": "string",
"description": "Severity level (1-10)"
}
},
"required": ["symptoms"]
},
server_url="https://jsonplaceholder.typicode.com/posts"
)
# Create appointment scheduling tool
appointment_scheduling_tool = create_medical_tool(
name="Schedule Appointment",
function_name="schedule_appointment",
description="Schedule patient appointments based on availability",
parameters={
"type": "object",
"properties": {
"patient_id": {
"type": "string",
"description": "Patient identifier"
},
"appointment_type": {
"type": "string",
"description": "Type of appointment needed"
},
"urgency_level": {
"type": "string",
"description": "Urgency classification"
}
},
"required": ["patient_id", "appointment_type"]
},
server_url="https://jsonplaceholder.typicode.com/posts"
)
```
```bash
# Create Patient Lookup Tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "lookup_patient",
"description": "Look up patient record by ID",
"parameters": {
"type": "object",
"properties": {
"patient_id": {
"type": "string",
"description": "Patient ID number"
}
},
"required": ["patient_id"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/users"
}'
# Create Triage Assessment Tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "conduct_triage",
"description": "Assess patient symptoms and determine urgency level",
"parameters": {
"type": "object",
"properties": {
"symptoms": {
"type": "string",
"description": "Description of patient symptoms"
},
"onset": {
"type": "string",
"description": "When symptoms started"
},
"severity": {
"type": "string",
"description": "Severity level (1-10)"
}
},
"required": ["symptoms"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/posts"
}'
# Create Appointment Scheduling Tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "schedule_appointment",
"description": "Schedule patient appointments based on availability",
"parameters": {
"type": "object",
"properties": {
"patient_id": {
"type": "string",
"description": "Patient identifier"
},
"appointment_type": {
"type": "string",
"description": "Type of appointment needed"
},
"urgency_level": {
"type": "string",
"description": "Urgency classification"
}
},
"required": ["patient_id", "appointment_type"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/posts"
}'
```
***
## 3. Create a Workflow
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Workflows` in the left sidebar.
* Click `Create Workflow`.
* Enter workflow name: `Clinic Triage & Scheduling Workflow`.
* Select the default template (includes Call Start node).
* Click "Create Workflow".
* Configure workflow variables for patient data and medical information
* Set up emergency routing capabilities
* Enable HIPAA-compliant settings if required
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createClinicTriageWorkflow() {
try {
// Create medical triage workflow with initial greeting node
const workflow = await vapi.workflows.create({
name: "Clinic Triage & Scheduling Workflow",
nodes: [
{
id: "greeting",
type: "conversation",
firstMessage: "Thank you for calling Riverside Family Clinic. This is your virtual assistant. I can help you schedule appointments, address medical concerns, or direct you to emergency care. How can I help you today?",
systemPrompt: "You are a professional medical assistant for Riverside Family Clinic. Listen carefully to determine the caller's purpose: emergency, medical triage, appointment scheduling, prescription refills, or general questions. Always prioritize patient safety and follow medical protocols.",
extractVariables: [
{
name: "call_purpose",
type: "string",
description: "Primary purpose of the patient's call",
enum: ["emergency", "medical_triage", "appointment", "prescription", "general"]
}
]
}
],
edges: []
});
console.log(`Medical workflow created with ID: ${workflow.id}`);
return workflow;
} catch (error) {
console.error('Error creating medical workflow:', error);
throw error;
}
}
// Create the clinic triage workflow
const workflow = await createClinicTriageWorkflow();
```
```python
import requests
def create_clinic_triage_workflow():
"""Create a new medical triage and scheduling workflow"""
url = "https://api.vapi.ai/workflow"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "Clinic Triage & Scheduling Workflow",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"firstMessage": "Thank you for calling Riverside Family Clinic. This is your virtual assistant. I can help you schedule appointments, address medical concerns, or direct you to emergency care. How can I help you today?",
"systemPrompt": "You are a professional medical assistant for Riverside Family Clinic. Listen carefully to determine the caller's purpose: emergency, medical triage, appointment scheduling, prescription refills, or general questions. Always prioritize patient safety and follow medical protocols.",
"extractVariables": [
{
"name": "call_purpose",
"type": "string",
"description": "Primary purpose of the patient's call",
"enum": ["emergency", "medical_triage", "appointment", "prescription", "general"]
}
]
}
],
"edges": []
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
workflow = response.json()
print(f"Medical workflow created with ID: {workflow['id']}")
return workflow
except requests.exceptions.RequestException as error:
print(f"Error creating medical workflow: {error}")
raise
# Create the clinic triage workflow
workflow = create_clinic_triage_workflow()
```
```bash
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Clinic Triage & Scheduling Workflow",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"firstMessage": "Thank you for calling Riverside Family Clinic. This is your virtual assistant. I can help you schedule appointments, address medical concerns, or direct you to emergency care. How can I help you today?",
"systemPrompt": "You are a professional medical assistant for Riverside Family Clinic. Listen carefully to determine the caller'\''s purpose: emergency, medical triage, appointment scheduling, prescription refills, or general questions. Always prioritize patient safety and follow medical protocols.",
"extractVariables": [
{
"name": "call_purpose",
"type": "string",
"description": "Primary purpose of the patient'\''s call",
"enum": ["emergency", "medical_triage", "appointment", "prescription", "general"]
}
]
}
],
"edges": []
}'
```
***
## 4. Build the Workflow
You'll start with a default template that includes a "Call Start" node. We'll modify the existing nodes and add new ones to create our medical triage and scheduling workflow.
The default template includes a conversation node. Click on it and configure:
```txt title="First Message"
Thank you for calling Riverside Family Clinic. This is your virtual assistant. I can help you schedule appointments, address medical concerns, or direct you to emergency care. How can I help you today?
```
```txt title="Prompt"
You are a professional medical assistant for Riverside Family Clinic.
Listen carefully to determine the caller's purpose:
- "emergency" for life-threatening situations
- "medical_triage" for symptom assessment
- "appointment" for scheduling needs
- "prescription" for refill requests
- "general" for other inquiries
Always prioritize patient safety and follow medical protocols. Keep responses under 35 words.
```
**Extract Variables**:
* Variable: `call_purpose`
* Type: `String`
* Description: `Primary purpose of the patient's call`
* Enum Values: `emergency`, `medical_triage`, `appointment`, `prescription`, `general`
Click the + button below the greeting node and add a new **Conversation** node:
```txt title="Condition"
Call purpose identified
```
```txt title="First Message"
I'll need to verify your information first. Please provide your patient ID, date of birth, or full name so I can access your medical record.
```
```txt title="Prompt"
You are collecting patient identification for medical record access.
Get patient ID, date of birth, or full name for verification.
Be professional and reassuring about medical privacy.
Follow HIPAA protocols. Keep responses under 25 words.
```
**Extract Variables**:
* Variable: `patient_id`
* Type: `String`
* Description: `Patient's ID number if provided`
* Variable: `patient_name`
* Type: `String`
* Description: `Patient's full name if provided`
* Variable: `date_of_birth`
* Type: `String`
* Description: `Patient's date of birth if provided`
Add a **Tool** node:
```txt title="Condition"
Patient information collected
```
**Select Tool**: Choose your pre-configured patient lookup tool from the dropdown. This tool will use the extracted patient information to find their medical record.
Create branching paths based on the patient's call purpose. Add multiple conversation nodes:
**Emergency Routing Node**:
```txt title="Condition"
Patient verified and purpose is emergency
```
```txt title="First Message"
I understand this is an emergency. For immediate life-threatening situations, please hang up and call 911 now. For urgent medical needs, I'm connecting you to our triage nurse immediately.
```
```txt title="Prompt"
You are handling a medical emergency call.
Direct to 911 for life-threatening emergencies.
Transfer to triage nurse for urgent medical situations.
Be calm, clear, and immediate in your response.
```
**Medical Triage Node**:
```txt title="Condition"
Patient verified and purpose is medical_triage
```
```txt title="First Message"
I'll help assess your medical concerns. Please describe your main symptoms, when they started, and how severe they are on a scale of 1 to 10.
```
```txt title="Prompt"
You are conducting initial medical triage assessment.
Collect symptoms, onset time, severity, and related factors.
Follow medical assessment protocols. Be thorough but efficient.
Keep responses under 30 words.
```
**Appointment Scheduling Node**:
```txt title="Condition"
Patient verified and purpose is appointment
```
```txt title="First Message"
I'll help you schedule an appointment. What type of visit do you need - routine check-up, follow-up, or consultation for a specific concern?
```
```txt title="Prompt"
You are helping schedule a medical appointment.
Determine appointment type, urgency, and preferred timing.
Be helpful and accommodating. Keep responses under 25 words.
```
Create a global node that monitors for emergency keywords throughout the call:
```txt title="Condition"
Emergency keywords detected or life-threatening symptoms mentioned
```
**Node Name**: `emergency_detector`
**Global Node**: `enabled = true`
**Enter Condition**: `{{ emergency_keywords_detected == true or red_flag_symptoms == true }}`
```txt title="First Message"
I'm hearing some concerning symptoms. For your safety, I need to direct you to immediate medical care. Please call 911 or go to your nearest emergency room right away. Do not drive yourself - have someone else drive you or call an ambulance.
```
```txt title="Prompt"
You are handling a medical emergency situation.
Direct them to emergency services immediately. Be clear and calm.
Do not provide medical advice beyond directing to emergency care.
Keep the message brief but urgent.
```
This global node will activate whenever emergency keywords are detected, regardless of where they are in the workflow.
For the medical triage path, add these nodes:
**Symptom Collection Node**:
```txt title="Condition"
Initial symptoms described
```
**Node Name**: `collect_symptoms`
```txt title="First Message"
Thank you for that information. On a scale of 1 to 10, how would you rate your pain or discomfort? And have you tried anything to help with these symptoms?
```
```txt title="Prompt"
You are collecting detailed symptom information for medical triage.
Get pain scale, duration, what makes it better/worse, and any self-treatment.
Follow medical assessment protocols. Keep responses under 30 words.
```
**Extract Variables**:
* Variable: `symptom_details`
* Type: `String`
* Description: `Detailed symptom description`
* Variable: `pain_scale`
* Type: `String`
* Description: `Pain level 1-10`
* Variable: `symptom_duration`
* Type: `String`
* Description: `How long symptoms have been present`
**Triage Protocol Tool Node**:
```txt title="Condition"
Comprehensive symptoms collected
```
* Add a **Tool** node that calls triage protocol API with symptom data
**Urgency Classification Node**:
```txt title="Condition"
Triage assessment completed
```
**Node Name**: `classify_urgency`
```txt title="First Message"
Based on your symptoms, I'm going to classify this as [urgency level] and connect you with the appropriate care level.
```
```txt title="Prompt"
You are communicating the triage classification results to the patient.
Explain the urgency level and next steps clearly.
Be reassuring while maintaining clinical accuracy.
Keep responses under 35 words.
```
* Determine urgency level: emergency, urgent, semi-urgent, routine
* Route to appropriate care level
**Provider Lookup Tool Node**:
```txt title="Condition"
Urgency level determined and provider needed
```
* Add a **Tool** node that checks available appointments based on urgency and specialty
**Appointment Options Node**:
```txt title="Condition"
Provider availability checked
```
**Node Name**: `present_appointment_options`
```txt title="First Message"
Based on your needs, I have these available appointment times with Dr. [Provider Name]. Which option works best for your schedule?
```
```txt title="Prompt"
You are presenting available medical appointments to the patient.
Present 2-3 time options clearly with provider names.
Consider urgency when offering times. Keep responses under 35 words.
```
* Present available time slots to patient
* Use conditional logic based on urgency level
**Appointment Confirmation Node**:
```txt title="Condition"
Appointment time selected
```
**Node Name**: `confirm_appointment`
```txt title="First Message"
Perfect! Let me confirm your appointment with Dr. [Provider] on [date] at [time]. Please arrive 15 minutes early for check-in.
```
```txt title="Prompt"
You are confirming medical appointment details.
Confirm provider, date, time, and location.
Provide pre-appointment instructions if needed.
Keep responses under 30 words.
```
* Confirm appointment details and provide instructions
**911 Routing Node**:
```txt title="Condition"
Life-threatening emergency detected
```
**Node Type**: `Transfer`
**Destination**: `911`
* Use for life-threatening emergencies
**Urgent Care Transfer Node**:
```txt title="Condition"
Urgent but not life-threatening situation
```
**Node Type**: `Transfer`
**Destination**: `+1-555-URGENT-1` (urgent care line)
**Nurse Line Transfer Node**:
```txt title="Condition"
Clinical consultation needed
```
**Node Type**: `Transfer`
**Destination**: `+1-555-NURSE-1` (triage nurse line)
**End Call Node**:
```txt title="Condition"
Patient needs resolved or transferred appropriately
```
**Node Type**: `Hangup`
* Use when patient needs are resolved
***
## 5. Configure Phone Number
Click `Phone Numbers` in the left sidebar of your dashboard.
* Click `Create Phone Number` for a new Vapi number, or
* Click `Import Phone Number` to use your existing clinic number
**Workflow**: Select your `Clinic Triage & Scheduling Workflow`
**Medical Configuration**:
* Enable call recording for medical documentation
* Set maximum call duration (e.g., 20 minutes for complex cases)
* Configure voicemail for after-hours calls
* Enable emergency transfer capabilities
Test the workflow with various medical scenarios:
* Routine appointment requests
* Urgent symptom assessments
* Emergency situations (test routing only)
* Prescription refill requests
* After-hours calls
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createClinicPhoneNumber(workflowId: string) {
try {
// Create phone number for medical clinic workflow
const phoneNumber = await vapi.phoneNumbers.create({
name: "Riverside Family Clinic Line",
workflowId: workflowId,
inboundSettings: {
maxCallDurationMinutes: 20,
recordingEnabled: true,
voicemailDetectionEnabled: true,
emergencyTransferEnabled: true
}
});
console.log(`Clinic phone number created: ${phoneNumber.number}`);
return phoneNumber;
} catch (error) {
console.error('Error creating clinic phone number:', error);
throw error;
}
}
async function testMedicalScenarios(workflowId: string) {
try {
const scenarios = [
{ customer: { number: "+1234567890", name: "Routine Appointment Patient" }},
{ customer: { number: "+1234567891", name: "Urgent Symptom Patient" }},
{ customer: { number: "+1234567892", name: "Prescription Refill Patient" }}
];
for (const scenario of scenarios) {
// Test medical workflow with different patient scenarios
const call = await vapi.calls.create({
workflowId: workflowId,
...scenario
});
console.log(`Test call for ${scenario.customer.name}: ${call.id}`);
}
} catch (error) {
console.error('Error testing medical scenarios:', error);
throw error;
}
}
// Create phone number and test scenarios
const phoneNumber = await createClinicPhoneNumber('YOUR_WORKFLOW_ID');
await testMedicalScenarios('YOUR_WORKFLOW_ID');
```
```python
import requests
def create_clinic_phone_number(workflow_id):
"""Create phone number for medical clinic workflow"""
url = "https://api.vapi.ai/phone-number"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "Riverside Family Clinic Line",
"workflowId": workflow_id,
"inboundSettings": {
"maxCallDurationMinutes": 20,
"recordingEnabled": True,
"voicemailDetectionEnabled": True,
"emergencyTransferEnabled": True
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
phone_number = response.json()
print(f"Clinic phone number created: {phone_number['number']}")
return phone_number
except requests.exceptions.RequestException as error:
print(f"Error creating clinic phone number: {error}")
raise
def test_medical_scenarios(workflow_id):
"""Test medical workflow with different patient scenarios"""
scenarios = [
{"customer": {"number": "+1234567890", "name": "Routine Appointment Patient"}},
{"customer": {"number": "+1234567891", "name": "Urgent Symptom Patient"}},
{"customer": {"number": "+1234567892", "name": "Prescription Refill Patient"}}
]
for scenario in scenarios:
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"workflowId": workflow_id,
**scenario
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
result = response.json()
print(f"Test call for {scenario['customer']['name']}: {result['id']}")
except requests.exceptions.RequestException as error:
print(f"Error testing scenario {scenario['customer']['name']}: {error}")
# Create phone number and test scenarios
phone_number = create_clinic_phone_number('YOUR_WORKFLOW_ID')
test_medical_scenarios('YOUR_WORKFLOW_ID')
```
```bash
# Create phone number with medical workflow
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Riverside Family Clinic Line",
"workflowId": "YOUR_WORKFLOW_ID",
"inboundSettings": {
"maxCallDurationMinutes": 20,
"recordingEnabled": true,
"voicemailDetectionEnabled": true,
"emergencyTransferEnabled": true
}
}'
# Test routine appointment scenario
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567890",
"name": "Test Patient"
}
}'
```
## Integrating with Real Systems
This example uses JSONPlaceholder for demonstration purposes. To integrate with your actual healthcare systems:
### EHR System Integration
* **Epic**: Use [Epic on FHIR](https://fhir.epic.com/) APIs for patient data
* **Cerner**: Use [Cerner SMART on FHIR](https://fhir.cerner.com/) APIs
* **Allscripts**: Use [Allscripts Developer Program](https://developer.allscripts.com/) APIs
### Appointment Scheduling
* **Epic MyChart**: [Epic APIs](https://fhir.epic.com/Documentation?docId=scheduling)
* **Cerner PowerChart**: [Cerner Scheduling APIs](https://fhir.cerner.com/millennium/r4/scheduling/)
* **athenahealth**: [athenaCollector API](https://docs.athenahealth.com/api/)
### Medical Decision Support
* **IBM Watson Health**: [Watson for Oncology](https://www.ibm.com/watson-health)
* **Microsoft Healthcare Bot**: [Healthcare Bot Service](https://docs.microsoft.com/en-us/healthbot/)
* **Infermedica**: [Symptom Checker API](https://developer.infermedica.com/)
**HIPAA Compliance**: When integrating with real healthcare systems, ensure all integrations comply with HIPAA regulations and your organization's privacy policies.
## Next Steps
Just like that, you've built a medical triage and scheduling workflow that can handle patient calls, assess symptoms, and route to appropriate care levels with 24/7 availability.
Consider reading the following guides to further enhance your workflow:
* [**Custom Tools**](/tools/custom-tools) - Create custom tools for EHR integration and medical protocols.
* [**Custom Voices**](/customization/custom-voices/custom-voice) - Customize your assistant's voice for medical professionalism.
* [**HIPAA Compliance**](/security-and-privacy/hipaa) - Ensure your medical workflows meet HIPAA requirements.
# E-commerce order management workflow
> Build a voice AI e-commerce workflow with order tracking, return processing, and customer support automation using Vapi's visual workflow builder.
## Overview
Build an AI-powered e-commerce customer service workflow that handles order inquiries, returns, and customer support using Vapi workflows with tier-based routing and global monitoring for comprehensive automation.
**What You'll Build:**
* Order tracking with real-time status updates
* Return processing with automated eligibility verification
* Customer tier routing (VIP, Premium, Standard)
* Global fraud detection and sentiment monitoring
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
* E-commerce platform or order management system.
* Shipping carrier integrations.
## Scenario
We will be creating an order management workflow for TechGear Online, an electronics retailer that wants to automate customer service calls and improve order resolution times through sophisticated workflow automation.
## Final Workflow
***
## 1. Create a Knowledge Base
In your Vapi dashboard, click `Files` in the left sidebar.
* Click `Choose file`. Upload all four CSV files: `customers.csv`, `orders.csv`, `products.csv`, and `returns.csv`.
* Note the file IDs. We'll need them later to create tools.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
import fs from 'fs';
// Initialize Vapi client
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function uploadEcommerceFiles() {
try {
// Upload customers file
const customersFile = await vapi.files.create({
file: fs.createReadStream("customers.csv")
});
// Upload orders file
const ordersFile = await vapi.files.create({
file: fs.createReadStream("orders.csv")
});
// Upload products file
const productsFile = await vapi.files.create({
file: fs.createReadStream("products.csv")
});
// Upload returns file
const returnsFile = await vapi.files.create({
file: fs.createReadStream("returns.csv")
});
console.log(`Customers file ID: ${customersFile.id}`);
console.log(`Orders file ID: ${ordersFile.id}`);
console.log(`Products file ID: ${productsFile.id}`);
console.log(`Returns file ID: ${returnsFile.id}`);
return {
customersFileId: customersFile.id,
ordersFileId: ordersFile.id,
productsFileId: productsFile.id,
returnsFileId: returnsFile.id
};
} catch (error) {
console.error('Error uploading files:', error);
throw error;
}
}
// Upload all files
const fileIds = await uploadEcommerceFiles();
```
```python
import requests
# Configuration
YOUR_VAPI_API_KEY = "your_api_key_here"
def upload_file(file_path):
"""Upload a single file to Vapi"""
url = "https://api.vapi.ai/file"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
if response.status_code == 200:
return response.json()
else:
raise Exception(f"Failed to upload {file_path}: {response.text}")
def upload_ecommerce_files():
"""Upload all required e-commerce files"""
try:
# Upload all required files
customers_file = upload_file("customers.csv")
orders_file = upload_file("orders.csv")
products_file = upload_file("products.csv")
returns_file = upload_file("returns.csv")
print(f"Customers file ID: {customers_file['id']}")
print(f"Orders file ID: {orders_file['id']}")
print(f"Products file ID: {products_file['id']}")
print(f"Returns file ID: {returns_file['id']}")
return {
"customers_file_id": customers_file['id'],
"orders_file_id": orders_file['id'],
"products_file_id": products_file['id'],
"returns_file_id": returns_file['id']
}
except Exception as error:
print(f"Error uploading files: {error}")
raise
# Upload all files
file_ids = upload_ecommerce_files()
```
```bash
# Upload customers.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@customers.csv"
# Upload orders.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@orders.csv"
# Upload products.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@products.csv"
# Upload returns.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@returns.csv"
```
***
## 2. Create Required Tools
Before building the workflow, create the necessary tools in your dashboard:
In your Vapi dashboard, click **Tools** in the left sidebar.
Click **Create Tool** and configure:
* **Tool Name**: "Customer Lookup"
* **Tool Type**: "Function"
* **Function Name**: `lookup_customer`
* **Description**: "Look up customer account and order history"
* **Parameters**:
* `customer_id` (string): Customer ID to lookup
* **Server URL**: `https://jsonplaceholder.typicode.com/users`
This example uses JSONPlaceholder, a free testing API. In production, replace with your actual e-commerce API endpoint.
Create another tool:
* **Tool Name**: "Order Tracking"
* **Function Name**: `track_order`
* **Description**: "Track order status and shipping information"
* **Parameters**:
* `order_id` (string): Order ID to track
* **Server URL**: `https://jsonplaceholder.typicode.com/posts`
This example uses JSONPlaceholder for demonstration. Replace with your shipping provider's API (FedEx, UPS, etc.) in production.
Create a third tool:
* **Tool Name**: "Return Processing"
* **Function Name**: `process_return`
* **Description**: "Process return requests and generate return labels"
* **Parameters**:
* `order_id` (string): Original order ID
* `return_reason` (string): Reason for return
* **Server URL**: `https://jsonplaceholder.typicode.com/posts`
This example uses JSONPlaceholder for demonstration. In production, integrate with your returns management system.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createEcommerceTools() {
try {
// Create Customer Lookup Tool
const customerLookupTool = await vapi.tools.create({
type: "function",
function: {
name: "lookup_customer",
description: "Look up customer account and order history",
parameters: {
type: "object",
properties: {
customer_id: {
type: "string",
description: "Customer ID to lookup"
}
},
required: ["customer_id"]
}
},
serverUrl: "https://jsonplaceholder.typicode.com/users"
});
// Create Order Tracking Tool
const orderTrackingTool = await vapi.tools.create({
type: "function",
function: {
name: "track_order",
description: "Track order status and shipping information",
parameters: {
type: "object",
properties: {
order_id: {
type: "string",
description: "Order ID to track"
}
},
required: ["order_id"]
}
},
serverUrl: "https://jsonplaceholder.typicode.com/posts"
});
// Create Return Processing Tool
const returnProcessingTool = await vapi.tools.create({
type: "function",
function: {
name: "process_return",
description: "Process return requests and generate return labels",
parameters: {
type: "object",
properties: {
order_id: {
type: "string",
description: "Original order ID"
},
return_reason: {
type: "string",
description: "Reason for return"
}
},
required: ["order_id", "return_reason"]
}
},
serverUrl: "https://jsonplaceholder.typicode.com/posts"
});
console.log(`Customer Lookup Tool ID: ${customerLookupTool.id}`);
console.log(`Order Tracking Tool ID: ${orderTrackingTool.id}`);
console.log(`Return Processing Tool ID: ${returnProcessingTool.id}`);
return {
customerLookupToolId: customerLookupTool.id,
orderTrackingToolId: orderTrackingTool.id,
returnProcessingToolId: returnProcessingTool.id
};
} catch (error) {
console.error('Error creating tools:', error);
throw error;
}
}
// Create all tools
const toolIds = await createEcommerceTools();
```
```python
import requests
def create_tool(tool_config):
"""Create a tool using the Vapi API"""
url = "https://api.vapi.ai/tool"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(url, headers=headers, json=tool_config)
if response.status_code == 200:
return response.json()
else:
raise Exception(f"Failed to create tool: {response.text}")
def create_ecommerce_tools():
"""Create all required e-commerce tools"""
try:
# Customer Lookup Tool
customer_lookup_tool = create_tool({
"type": "function",
"function": {
"name": "lookup_customer",
"description": "Look up customer account and order history",
"parameters": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Customer ID to lookup"
}
},
"required": ["customer_id"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/users"
})
# Order Tracking Tool
order_tracking_tool = create_tool({
"type": "function",
"function": {
"name": "track_order",
"description": "Track order status and shipping information",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Order ID to track"
}
},
"required": ["order_id"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/posts"
})
# Return Processing Tool
return_processing_tool = create_tool({
"type": "function",
"function": {
"name": "process_return",
"description": "Process return requests and generate return labels",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Original order ID"
},
"return_reason": {
"type": "string",
"description": "Reason for return"
}
},
"required": ["order_id", "return_reason"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/posts"
})
print(f"Customer Lookup Tool ID: {customer_lookup_tool['id']}")
print(f"Order Tracking Tool ID: {order_tracking_tool['id']}")
print(f"Return Processing Tool ID: {return_processing_tool['id']}")
return {
"customer_lookup_tool_id": customer_lookup_tool['id'],
"order_tracking_tool_id": order_tracking_tool['id'],
"return_processing_tool_id": return_processing_tool['id']
}
except Exception as error:
print(f"Error creating tools: {error}")
raise
# Create all tools
tool_ids = create_ecommerce_tools()
```
```bash
# Create Customer Lookup Tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "lookup_customer",
"description": "Look up customer account and order history",
"parameters": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Customer ID to lookup"
}
},
"required": ["customer_id"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/users"
}'
# Create Order Tracking Tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "track_order",
"description": "Track order status and shipping information",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Order ID to track"
}
},
"required": ["order_id"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/posts"
}'
# Create Return Processing Tool
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "function",
"function": {
"name": "process_return",
"description": "Process return requests and generate return labels",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "Original order ID"
},
"return_reason": {
"type": "string",
"description": "Reason for return"
}
},
"required": ["order_id", "return_reason"]
}
},
"serverUrl": "https://jsonplaceholder.typicode.com/posts"
}'
```
***
## 3. Create a Workflow
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Workflows` in the left sidebar.
* Click `Create Workflow`.
* Enter workflow name: `TechGear E-commerce Support Workflow`.
* Select the default template (includes Call Start node).
* Click "Create Workflow".
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
// System prompt for the workflow
const systemPrompt = `You are Emma, the friendly customer service representative for TechGear Online. Listen to the customer's response and determine their inquiry type: order_tracking, return_exchange, product_inquiry, billing_payment, complaint, or general. Keep responses friendly and under 35 words.`;
async function createEcommerceWorkflow() {
try {
const workflow = await vapi.workflows.create({
name: "TechGear E-commerce Support Workflow",
nodes: [
{
id: "greeting",
type: "conversation",
firstMessage: "Hello! Thank you for calling TechGear Online customer service. This is Emma, your virtual assistant. I can help you track orders, process returns, answer product questions, or resolve any issues. How can I assist you today?",
systemPrompt: systemPrompt,
extractVariables: [
{
name: "inquiry_type",
type: "string",
description: "The customer's inquiry type",
enum: ["order_tracking", "return_exchange", "product_inquiry", "billing_payment", "complaint", "general"]
}
]
}
],
edges: []
});
console.log(`Workflow created with ID: ${workflow.id}`);
return workflow;
} catch (error) {
console.error('Error creating workflow:', error);
throw error;
}
}
// Create the workflow
const workflow = await createEcommerceWorkflow();
```
```python
import requests
def create_ecommerce_workflow():
"""Create the e-commerce support workflow"""
url = "https://api.vapi.ai/workflow"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
# System prompt for the workflow
system_prompt = "You are Emma, the friendly customer service representative for TechGear Online. Listen to the customer's response and determine their inquiry type: order_tracking, return_exchange, product_inquiry, billing_payment, complaint, or general. Keep responses friendly and under 35 words."
workflow_data = {
"name": "TechGear E-commerce Support Workflow",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"firstMessage": "Hello! Thank you for calling TechGear Online customer service. This is Emma, your virtual assistant. I can help you track orders, process returns, answer product questions, or resolve any issues. How can I assist you today?",
"systemPrompt": system_prompt,
"extractVariables": [
{
"name": "inquiry_type",
"type": "string",
"description": "The customer's inquiry type",
"enum": ["order_tracking", "return_exchange", "product_inquiry", "billing_payment", "complaint", "general"]
}
]
}
],
"edges": []
}
response = requests.post(url, headers=headers, json=workflow_data)
if response.status_code == 200:
workflow = response.json()
print(f"Workflow created with ID: {workflow['id']}")
return workflow
else:
raise Exception(f"Failed to create workflow: {response.text}")
# Create the workflow
workflow = create_ecommerce_workflow()
```
```bash
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "TechGear E-commerce Support Workflow",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"firstMessage": "Hello! Thank you for calling TechGear Online customer service. This is Emma, your virtual assistant. I can help you track orders, process returns, answer product questions, or resolve any issues. How can I assist you today?",
"systemPrompt": "You are Emma, the friendly customer service representative for TechGear Online. Listen to the customer'\''s response and determine their inquiry type: order_tracking, return_exchange, product_inquiry, billing_payment, complaint, or general. Keep responses friendly and under 35 words.",
"extractVariables": [
{
"name": "inquiry_type",
"type": "string",
"description": "The customer'\''s inquiry type",
"enum": ["order_tracking", "return_exchange", "product_inquiry", "billing_payment", "complaint", "general"]
}
]
}
],
"edges": []
}'
```
***
## 4. Build the Workflow
You'll start with a default template that includes a "Call Start" node. We'll modify the existing nodes and add new ones to create our e-commerce customer service workflow.
The default template includes a conversation node. Click on it and configure:
**Node Name**: `greeting_and_inquiry_type`
```txt title="First Message"
Hello! Thank you for calling TechGear Online customer service. This is Emma, your virtual assistant. I can help you track orders, process returns, answer product questions, or resolve any issues. How can I assist you today?
```
```txt title="Prompt"
You are Emma, the friendly customer service representative for TechGear Online.
Listen to the customer's response and determine their inquiry type:
- "order_tracking" for checking order status or shipping
- "return_exchange" for returns, exchanges, or refunds
- "product_inquiry" for product questions or recommendations
- "billing_payment" for payment or billing issues
- "complaint" for problems or complaints
- "general" for other inquiries
Keep responses friendly and under 35 words. Be helpful and professional.
```
**Extract Variables**:
* Variable: `inquiry_type`
* Type: `String`
* Description: `The customer's inquiry type`
* Enum Values: `order_tracking`, `return_exchange`, `product_inquiry`, `billing_payment`, `complaint`, `general`
Add a **Conversation** node:
```txt title="Condition"
Inquiry type identified
```
**Node Name**: `customer_identification`
```txt title="First Message"
I'll be happy to help you with that. To look up your account, can you please provide your phone number or email address associated with your TechGear Online account?
```
```txt title="Prompt"
You are collecting customer information to look up their account.
If you don't have an account, that's okay - I can still help you with general product questions.
Be patient and helpful. Extract phone number or email clearly.
Keep responses under 25 words.
```
**Variable Extraction**:
* Variable: `customer_phone`
* Type: `string`
* Description: `Customer's phone number`
* Required: `false`
* Variable: `customer_email`
* Type: `string`
* Description: `Customer's email address`
* Required: `false`
Add a **Tool** node:
```txt title="Condition"
Customer information provided
```
**Tool**: Select your pre-configured "Customer Lookup" tool from the dropdown. This tool should be created in the **Tools** section of your dashboard with:
* **Function Name**: `lookup_customer`
* **Description**: "Look up customer account and order history"
* **Parameters**:
* `customer_id` (string): Customer ID to lookup
* **Server URL**: `https://jsonplaceholder.typicode.com/users`
Create branching paths based on the customer's inquiry type. Add multiple conversation nodes:
**Order Tracking Node**:
```txt title="Condition"
Customer verified and inquiry is order tracking
```
**Node Name**: `order_tracking_flow`
```txt title="First Message"
I can help you track your order. Do you have your order number, or would you like me to look up your recent orders?
```
```txt title="Prompt"
You are helping the customer track their order.
Be proactive in finding their order information.
If they don't have the order number, offer to look up recent orders.
Keep responses under 30 words.
```
**Return/Exchange Node**:
```txt title="Condition"
Customer verified and inquiry is return or exchange
```
**Node Name**: `return_exchange_flow`
```txt title="First Message"
I can help you with returns and exchanges. Can you tell me which item you'd like to return and the reason for the return?
```
```txt title="Prompt"
You are helping the customer with a return or exchange.
Get the specific item and reason for return clearly.
Be understanding and helpful about their concerns.
Keep responses under 30 words.
```
**Product Inquiry Node**:
```txt title="Condition"
Customer verified and inquiry is product related
```
**Node Name**: `product_inquiry_flow`
```txt title="First Message"
I'd be happy to help with product information. What specific product are you interested in, or what type of device are you looking for?
```
```txt title="Prompt"
You are helping the customer with product information and recommendations.
Be knowledgeable about TechGear products and helpful in making recommendations.
Ask clarifying questions to better assist them.
Keep responses under 35 words.
```
**Billing/Payment Node**:
```txt title="Condition"
Customer verified and inquiry is billing or payment
```
**Node Name**: `billing_payment_flow`
```txt title="First Message"
I can help with billing and payment questions. Are you looking to update payment information, dispute a charge, or have questions about a specific order?
```
```txt title="Prompt"
You are helping the customer with billing and payment issues.
Be careful with sensitive financial information.
Determine the specific billing concern clearly.
Keep responses under 30 words.
```
**Complaint Resolution Node**:
```txt title="Condition"
Customer verified and inquiry is a complaint
```
**Node Name**: `complaint_resolution_flow`
```txt title="First Message"
I'm sorry to hear you're having an issue. I want to make this right for you. Can you tell me what happened so I can help resolve this?
```
```txt title="Prompt"
You are handling a customer complaint and working toward resolution.
Be empathetic and solution-focused. Listen carefully to their concern.
Show that you care about resolving their issue.
Keep responses under 35 words.
```
Connect the nodes with conditions for the LLM to interpret:
**To Order Tracking Node**:
* Condition: `Customer verified and inquiry is order tracking`
**To Return/Exchange Node**:
* Condition: `Customer verified and inquiry is return or exchange`
**To Product Inquiry Node**:
* Condition: `Customer verified and inquiry is product related`
**To Billing/Payment Node**:
* Condition: `Customer verified and inquiry is billing or payment`
**To Complaint Resolution Node**:
* Condition: `Customer verified and inquiry is a complaint`
Create a global node that provides special handling for VIP customers:
```txt title="Condition"
VIP customer detected
```
**Node Name**: `vip_customer_handler`
**Global Node**: `enabled = true`
**Enter Condition**: `{{ customer_tier == "VIP" or total_orders > 50 or lifetime_value > 5000 }}`
```txt title="First Message"
I see you're one of our valued VIP customers. I want to make sure you receive our highest level of service today. Let me prioritize your request and see what I can do to exceed your expectations.
```
```txt title="Prompt"
You are providing VIP-level customer service to a high-value customer.
Be extra attentive and go above and beyond normal service.
Offer premium solutions and expedited handling.
Keep responses under 35 words but show special attention.
```
This global node will activate for high-value customers, regardless of their inquiry type.
**Node Name**: `vip_customer_priority`
```txt title="First Message"
Thank you for being a valued VIP customer! I'm prioritizing your call and will personally ensure your issue is resolved quickly. How can I assist you today?
```
```txt title="Prompt"
You are providing VIP-level customer service.
Give this customer premium attention and faster resolution.
Be extra helpful and offer additional assistance.
Keep responses under 30 words.
```
**Order Number Collection Node**:
```txt title="Condition"
Order tracking flow initiated
```
**Node Name**: `collect_order_number`
```txt title="First Message"
Please provide your order number, and I'll get the latest status for you right away.
```
```txt title="Prompt"
You are collecting the order number for tracking.
Be patient if they need time to find it.
Offer alternative methods if they can't locate the order number.
Keep responses under 25 words.
```
**Extract Variables**:
* Variable: `order_number`
* Type: `string`
* Description: `Customer's order number`
**Order Tracking Tool Node**:
```txt title="Condition"
Order number provided
```
* Add a **Tool** node that calls your order tracking API with order information
**Shipping Information Node**:
```txt title="Condition"
Order status retrieved
```
**Node Name**: `provide_shipping_info`
```txt title="First Message"
Great news! Your order is [status] and should arrive [delivery date]. Here's your tracking number: [tracking]. Is there anything else about this order?
```
```txt title="Prompt"
You are providing order status and shipping information to the customer.
Give clear updates on order status, tracking, and delivery estimates.
Be positive and informative. Keep responses under 35 words.
```
* Present tracking details, delivery estimates, and shipping updates
**Return Eligibility Check Node**:
```txt title="Condition"
Return request initiated
```
**Node Name**: `check_return_eligibility`
```txt title="First Message"
Let me check if this item is eligible for return. What's the reason for the return - defective, wrong item, or just not what you expected?
```
```txt title="Prompt"
You are checking return eligibility and gathering return details.
Verify return policy compliance and item condition.
Be understanding about their return reason.
Keep responses under 30 words.
```
**Extract Variables**:
* Variable: `return_reason`
* Type: `String`
* Description: `Reason for return`
**Return Authorization Tool Node**:
```txt title="Condition"
Return eligibility confirmed
```
* Add a **Tool** node that creates return label and authorization number
**Refund Processing Node**:
```txt title="Condition"
Return authorized
```
**Node Name**: `process_refund`
```txt title="First Message"
Perfect! I've processed your return authorization. You'll receive a return label via email, and your refund will be processed within 3-5 business days once we receive the item.
```
```txt title="Prompt"
You are confirming the return process and refund timeline.
Provide clear instructions for returning the item.
Set proper expectations for refund timing.
Keep responses under 35 words.
```
* Handle refund calculations and payment processing
**Human Agent Transfer Node**:
```txt title="Condition"
Customer requests human agent or complex issue
```
**Node Type**: `Transfer`
**Destination**: `+1-555-SUPPORT` (customer service team)
**Issue Resolution Node**:
```txt title="Condition"
Resolution offered or compensation provided
```
**Node Name**: `resolve_issue`
```txt title="First Message"
I want to make this right for you. Let me offer you [solution/compensation] for the trouble you've experienced.
```
```txt title="Prompt"
You are providing a resolution or compensation for the customer's issue.
Be generous and solution-focused. Make the customer feel valued.
Offer specific solutions or compensation when appropriate.
Keep responses under 30 words.
```
* Provide solutions, credits, or compensations
**End Call Node**:
```txt title="Condition"
Customer issue resolved and satisfied
```
**Node Type**: `Hangup`
* Use when customer issue is resolved
***
## 5. Configure Phone Number
Click `Phone Numbers` in the left sidebar of your dashboard.
* Click `Create Phone Number` for a new Vapi number, or
* Click `Import Phone Number` to use your existing customer service number
**Workflow**: Select your `TechGear Customer Service Workflow`
**Customer Service Configuration**:
* Enable call recording for quality assurance
* Set maximum call duration (e.g., 30 minutes for complex issues)
* Configure voicemail for after-hours support
* Enable priority routing for VIP customers
Test the workflow with various customer scenarios:
* Order tracking requests
* Return and exchange processing
* Product inquiries and recommendations
* Billing and payment issues
* Complaint resolution
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createEcommercePhoneNumber(workflowId: string) {
try {
const phoneNumber = await vapi.phoneNumbers.create({
name: "TechGear Customer Service Line",
workflowId: workflowId,
inboundSettings: {
maxCallDurationMinutes: 30,
recordingEnabled: true,
voicemailDetectionEnabled: true,
priorityRouting: true
}
});
console.log(`Customer service number: ${phoneNumber.number}`);
return phoneNumber;
} catch (error) {
console.error('Error creating phone number:', error);
throw error;
}
}
async function testEcommerceScenarios(workflowId: string) {
const scenarios = [
{
customer: { number: "+1234567890", name: "Order Tracking Customer" },
scenario: "order_tracking"
},
{
customer: { number: "+1234567891", name: "Return Customer" },
scenario: "return_exchange"
},
{
customer: { number: "+1234567892", name: "Billing Issue Customer" },
scenario: "billing_payment"
}
];
for (const scenario of scenarios) {
try {
const call = await vapi.calls.create({
workflowId: workflowId,
...scenario
});
console.log(`Test call for ${scenario.customer.name}: ${call.id}`);
} catch (error) {
console.error(`Error creating test call for ${scenario.scenario}:`, error);
}
}
}
// Create phone number and test scenarios
const phoneNumber = await createEcommercePhoneNumber(workflowId);
await testEcommerceScenarios(workflowId);
```
```python
import requests
def create_ecommerce_phone_number(workflow_id):
"""Create a phone number for e-commerce customer service"""
url = "https://api.vapi.ai/phone-number"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "TechGear Customer Service Line",
"workflowId": workflow_id,
"inboundSettings": {
"maxCallDurationMinutes": 30,
"recordingEnabled": True,
"voicemailDetectionEnabled": True,
"priorityRouting": True
}
}
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
phone_number = response.json()
print(f"Customer service number: {phone_number['number']}")
return phone_number
else:
raise Exception(f"Failed to create phone number: {response.text}")
def test_ecommerce_scenarios(workflow_id):
"""Test various e-commerce customer service scenarios"""
scenarios = [
{
"customer": {"number": "+1234567890", "name": "Order Tracking Customer"},
"scenario": "order_tracking"
},
{
"customer": {"number": "+1234567891", "name": "Return Customer"},
"scenario": "return_exchange"
},
{
"customer": {"number": "+1234567892", "name": "Billing Issue Customer"},
"scenario": "billing_payment"
}
]
for scenario in scenarios:
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"workflowId": workflow_id,
**scenario
}
try:
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
result = response.json()
print(f"Test call for {scenario['customer']['name']}: {result['id']}")
else:
print(f"Error creating test call for {scenario['scenario']}: {response.text}")
except Exception as error:
print(f"Error creating test call for {scenario['scenario']}: {error}")
# Create phone number and test scenarios
phone_number = create_ecommerce_phone_number(workflow_id)
test_ecommerce_scenarios(workflow_id)
```
```bash
# Create phone number with workflow
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "TechGear Customer Service Line",
"workflowId": "YOUR_WORKFLOW_ID",
"inboundSettings": {
"maxCallDurationMinutes": 30,
"recordingEnabled": true,
"voicemailDetectionEnabled": true,
"priorityRouting": true
}
}'
# Test order tracking scenario
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567890",
"name": "Test Customer"
},
"scenario": "order_tracking"
}'
# Test return scenario
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567891",
"name": "Return Customer"
},
"scenario": "return_exchange"
}'
# Test billing scenario
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567892",
"name": "Billing Customer"
},
"scenario": "billing_payment"
}'
```
### Optional: Web SDK Integration
For e-commerce websites that want to integrate voice support directly into their shopping experience:
```typescript
import Vapi from '@vapi-ai/web';
interface EcommerceOrderConfig {
publicApiKey: string;
workflowId: string;
}
function createEcommerceOrderWorkflow(config: EcommerceOrderConfig) {
const vapi = new Vapi(config.publicApiKey);
let isConnected = false;
let currentCustomer: any = null;
// Setup event listeners for customer service calls
vapi.on('call-start', () => {
isConnected = true;
console.log('E-commerce customer service call started');
});
vapi.on('call-end', () => {
isConnected = false;
console.log('Customer service call ended');
processCustomerServiceOutcome();
});
vapi.on('message', (message) => {
if (message.type === 'transcript') {
console.log(`${message.role}: ${message.transcript}`);
} else if (message.type === 'function-call') {
handleCustomerServiceFunction(message.functionCall);
} else if (message.type === 'workflow-step') {
console.log('Customer service workflow step:', message.step);
}
});
vapi.on('error', (error) => {
console.error('Customer service workflow error:', error);
});
function handleCustomerServiceFunction(functionCall: { name: string; parameters: Record }) {
switch (functionCall.name) {
case 'lookup_customer':
console.log('Looking up customer:', functionCall.parameters);
break;
case 'track_order':
console.log('Tracking order:', functionCall.parameters);
break;
case 'process_return':
console.log('Processing return:', functionCall.parameters);
break;
default:
console.log('Customer service function called:', functionCall.name, functionCall.parameters);
}
}
function processCustomerServiceOutcome() {
console.log('Processing customer service outcome for:', currentCustomer);
}
return {
startCustomerServiceCall: (customerData?: any) => {
if (!isConnected) {
currentCustomer = customerData;
vapi.start(config.workflowId);
}
},
endCall: () => {
if (isConnected) {
vapi.stop();
}
},
isConnected: () => isConnected
};
}
// Usage for e-commerce customer service integration
const customerServiceWorkflow = createEcommerceOrderWorkflow({
publicApiKey: 'YOUR_PUBLIC_API_KEY',
workflowId: 'YOUR_WORKFLOW_ID'
});
// Add to your e-commerce site's customer service button
document.getElementById('customer-service-button')?.addEventListener('click', () => {
customerServiceWorkflow.startCustomerServiceCall({
customerId: 'current_customer_id',
currentPage: 'order_tracking',
context: 'website_support'
});
});
```
Web SDK is for client-side customer service integration. File uploads and workflow creation must use the Server SDK or Dashboard.
***
## Integrating with Real Systems
This example uses JSONPlaceholder for demonstration purposes. To integrate with your actual e-commerce systems:
### E-commerce Platform Integration
* **Shopify**: Use the [Shopify Admin API](https://shopify.dev/api/admin-rest) for customer and order data
* **WooCommerce**: Use the [WooCommerce REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/)
* **Magento**: Use the [Magento Web API](https://devdocs.magento.com/guides/v2.4/get-started/web-api-functional-testing.html)
### Shipping Provider APIs
* **FedEx**: [FedEx Web Services](https://www.fedex.com/en-us/developer/web-services.html)
* **UPS**: [UPS Developer Kit](https://www.ups.com/upsdeveloperkit)
* **USPS**: [USPS Web Tools](https://www.usps.com/business/web-tools-apis/)
### Payment Processing
* **Stripe**: [Stripe API](https://stripe.com/docs/api)
* **PayPal**: [PayPal Developer](https://developer.paypal.com/)
* **Square**: [Square API](https://developer.squareup.com/)
## Next Steps
Just like that, you've built an e-commerce customer service workflow that can handle order inquiries, returns, and support requests with 24/7 availability for your online store.
Consider reading the following guides to further enhance your workflow:
* [**Custom Tools**](/tools/custom-tools) - Create custom tools for e-commerce platform integration and order management.
* [**Custom Voices**](/customization/custom-voices/custom-voice) - Customize your assistant's voice for customer service excellence.
* [**Call Recording**](/assistants/call-recording) - Record calls for quality assurance and training purposes.
# Property management call routing
> Build a voice AI property management system with dynamic call routing that determines destinations based on tenant verification, inquiry type analysis, and real-time agent availability using workflow API requests.
## Overview
Build a property management call routing workflow that determines transfer destinations dynamically using tenant verification, inquiry type analysis, and real-time agent availability. This approach uses visual workflow nodes with API Request nodes for maximum routing flexibility.
**Workflow Capabilities:**
* Tenant status verification and prioritization
* Inquiry type classification for specialist routing
* Real-time agent availability and queue management
* Emergency routing for urgent maintenance issues
**What You'll Build:**
* Visual workflow with conditional routing logic
* API Request nodes for dynamic destination logic
* Tenant verification with CRM integration
* Emergency escalation with priority queuing
## Quick Start: Create the Complete Workflow
Use this cURL command to create the entire property management workflow in one shot:
```bash title="Complete Workflow Creation"
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Property Management Call Router",
"nodes": [
{
"type": "conversation",
"name": "Initial Greeting",
"isStart": true,
"prompt": "You are a helpful property management assistant for Riverside Property Management. Start by greeting the caller and asking how you can help them today. Listen to determine: Is this an emergency/urgent maintenance issue? What type of inquiry is this (maintenance, lease, rent, general)? Keep responses under 25 words and be professional.",
"model": {
"provider": "openai",
"model": "gpt-4"
},
"variableExtractionPlan": {
"schema": {
"type": "object",
"properties": {
"inquiry_type": {
"type": "string",
"description": "Type of inquiry",
"enum": ["emergency", "maintenance", "lease", "rent", "general"]
},
"caller_phone": {
"type": "string",
"description": "Caller phone number for tenant lookup"
}
}
}
}
},
{
"type": "conversation",
"name": "Emergency Handling",
"prompt": "This is an emergency maintenance situation. Tell the caller you understand this is an emergency and that you are immediately connecting them with emergency maintenance. Keep the interaction brief and gather only essential details about the emergency.",
"model": {
"provider": "openai",
"model": "gpt-4"
},
"variableExtractionPlan": {
"schema": {
"type": "object",
"properties": {
"emergency_details": {
"type": "string",
"description": "Brief description of emergency"
}
}
}
}
},
{
"type": "tool",
"name": "Transfer to General Office",
"tool": {
"type": "transferCall",
"destinations": [
{
"type": "number",
"number": "+12025551234",
"message": "Connecting you to our office team who will assist you with your inquiry."
}
]
}
}
],
"edges": [
{
"from": "Initial Greeting",
"to": "Emergency Handling",
"condition": {
"type": "ai",
"prompt": "Route to emergency handling if the caller has an emergency or urgent maintenance issue"
}
},
{
"from": "Initial Greeting",
"to": "Transfer to General Office",
"condition": {
"type": "ai",
"prompt": "Route to transfer for all non-emergency inquiries (maintenance, lease, rent, general)"
}
},
{
"from": "Emergency Handling",
"to": "Transfer to General Office",
"condition": {
"type": "ai",
"prompt": "After gathering emergency details, transfer to office"
}
}
]
}'
```
Replace `$VAPI_API_KEY` with your actual API key from the [Vapi Dashboard](https://dashboard.vapi.ai/). Update the phone number in the `transferCall` destination to your actual office number.
Once created, you can retrieve the workflow ID and attach it to a phone number for testing.
## Test Workflow Creation
After creating the workflow, you can test it and get the workflow ID:
```bash title="Get Your Workflow ID"
# First, create the workflow using the command above, then:
curl -X GET https://api.vapi.ai/workflow \
-H "Authorization: Bearer $VAPI_API_KEY" \
| jq '.[] | select(.name == "Property Management Call Router") | {id: .id, name: .name, nodes: (.nodes | length), edges: (.edges | length)}'
```
```bash title="Get Specific Workflow Details"
# Replace WORKFLOW_ID with the actual ID from the previous command
curl -X GET https://api.vapi.ai/workflow/WORKFLOW_ID \
-H "Authorization: Bearer $VAPI_API_KEY" \
| jq '{id: .id, name: .name, nodes: [.nodes[].name], edges: [.edges[].condition]}'
```
```bash title="Attach Workflow to Phone Number"
# Replace PHONE_NUMBER_ID with your actual phone number ID
curl -X PATCH https://api.vapi.ai/phone-number/PHONE_NUMBER_ID \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "WORKFLOW_ID"
}'
```
You'll need `jq` installed for JSON parsing. On macOS: `brew install jq`, on Ubuntu: `sudo apt-get install jq`
## API Response Structure
When you create the workflow, you'll receive a response like this:
```json
{
"id": "wf_1234567890abcdef",
"name": "Property Management Call Router",
"orgId": "org_1234567890abcdef",
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"nodes": [
{
"id": "greeting",
"type": "conversation",
"name": "Initial Greeting",
"isStart": true,
"firstMessage": "Hello! You've reached Riverside Property Management...",
"systemPrompt": "You are a helpful property management assistant...",
"model": {
"provider": "openai",
"model": "gpt-4"
},
"extractVariables": [...]
},
// ... more nodes
],
"edges": [
{
"id": "greeting_to_lookup",
"source": "greeting",
"target": "tenant_lookup",
"condition": "Always route to tenant lookup after greeting"
},
// ... more edges
]
}
```
### Key Fields for Integration
| Field | Description | Usage |
| ----------- | ----------------------- | -------------------------------------------- |
| `id` | Workflow ID | Use this to attach workflow to phone numbers |
| `name` | Workflow name | For identification in dashboard |
| `nodes` | Array of workflow nodes | Conversation and tool nodes |
| `edges` | Array of connections | Define the flow between nodes |
| `createdAt` | Creation timestamp | For tracking and reference |
### Node Types in This Workflow
* **Conversation Nodes**: Handle AI conversations with tenants
* **Tool Nodes**: Execute API calls for tenant lookup and routing
* **Transfer Nodes**: Route calls to appropriate agents
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/)
* Property management system API or tenant database
* (Optional) Agent availability tracking system
## Scenario
We will build a call routing workflow for Riverside Property Management that intelligently routes tenant calls based on their status, inquiry type, and agent availability.
***
## 1. Create a Workflow
In your Vapi dashboard, click **Workflows** in the left sidebar.
* Click **Create Workflow**
* Name: `Property Management Call Router`
* Select blank template to start with basic call start node
* Click **Create Workflow**
Click on the conversation node and configure:
**Prompt**:
```txt
You are a helpful property management assistant for Riverside Property Management. Start by greeting the caller and asking how you can help them today. Listen to determine: Is this an emergency/urgent maintenance issue? What type of inquiry is this (maintenance, lease, rent, general)? Keep responses under 25 words and be professional.
```
**Variable Extraction Schema**:
```json
{
"type": "object",
"properties": {
"inquiry_type": {
"type": "string",
"description": "Type of inquiry",
"enum": ["emergency", "maintenance", "lease", "rent", "general"]
},
"caller_phone": {
"type": "string",
"description": "Caller phone number for tenant lookup"
}
}
}
```
Use the working cURL command from the Quick Start section above to create the entire workflow programmatically.
***
## 2. Add Tenant Verification Node
Add an **API Request** node after the greeting:
**Node Configuration**:
* Node ID: `tenant_lookup`
* HTTP Method: `POST`
* URL: `https://your-property-system.com/api/tenants/lookup`
* Headers: `Authorization: Bearer YOUR_API_KEY`
* Body:
```json
{
"phone": "{{caller_phone}}",
"inquiry_type": "{{inquiry_type}}"
}
```
Map the API response to workflow variables:
* `tenant_status` → Extract from `response.tenant.status`
* `property_address` → Extract from `response.tenant.property`
* `account_standing` → Extract from `response.tenant.account_standing`
* `emergency_contact` → Extract from `response.tenant.emergency_contact`
Configure what happens if the API call fails:
* **On Error**: Route to general agent queue
* **Error Message**: "I'll connect you with our general team who can help."
***
## 3. Build Emergency Routing Logic
Add a **Conversation** node for emergency handling:
**Condition**: `inquiry_type == "emergency"`
**First Message**:
```txt
I understand this is an emergency. Let me immediately connect you with our emergency maintenance team. Please stay on the line.
```
**System Prompt**:
```txt
This is an emergency maintenance situation. Confirm the emergency details quickly and route to emergency maintenance immediately. Keep interaction brief.
```
Add an **API Request** node to get emergency destination:
**URL**: `https://your-system.com/api/routing/emergency`
**Method**: `POST`
**Body**:
```json
{
"tenant_id": "{{tenant_id}}",
"property": "{{property_address}}",
"inquiry_type": "emergency",
"priority": "high"
}
```
Add a **Transfer Call** node:
* **Destination**: Use the phone number from the API response
* **Transfer Plan**: Include emergency context and tenant information
* **Priority**: Set to highest priority for immediate routing
***
## 4. Create Inquiry-Based Routing
Add **API Request** node for maintenance team routing:
**Condition**: `inquiry_type == "maintenance"`
**URL**: `https://your-system.com/api/routing/maintenance`
**Body**:
```json
{
"tenant_id": "{{tenant_id}}",
"property": "{{property_address}}",
"inquiry_type": "maintenance",
"tenant_status": "{{tenant_status}}"
}
```
Response should include:
* Available maintenance coordinator phone
* Estimated wait time
* Work order creation capability
Add **API Request** node for leasing inquiries:
**Condition**: `inquiry_type == "lease"`
**URL**: `https://your-system.com/api/routing/leasing`
**Body**:
```json
{
"tenant_id": "{{tenant_id}}",
"property": "{{property_address}}",
"inquiry_type": "lease",
"account_standing": "{{account_standing}}"
}
```
Add **API Request** node for billing department:
**Condition**: `inquiry_type == "rent"`
**URL**: `https://your-system.com/api/routing/billing`
**Body**:
```json
{
"tenant_id": "{{tenant_id}}",
"account_standing": "{{account_standing}}",
"inquiry_type": "rent"
}
```
***
## 5. Add Agent Availability Logic
Before each transfer, add an **API Request** to check agent availability:
**URL**: `https://your-system.com/api/agents/availability`
**Method**: `GET`
**Query Parameters**: `department={{department}}&priority={{priority}}`
Response includes:
* Available agents with phone numbers
* Current queue length
* Estimated wait times
Add conditional routing based on availability:
**If agents available**: Direct transfer to agent
**If queue exists**: Inform caller of wait time and offer callback
**If all busy**: Route to voicemail or priority callback system
Add **API Request** node for callback scheduling:
**URL**: `https://your-system.com/api/callbacks/schedule`
**Body**:
```json
{
"tenant_id": "{{tenant_id}}",
"phone": "{{caller_phone}}",
"inquiry_type": "{{inquiry_type}}",
"priority": "{{priority}}",
"requested_time": "{{preferred_callback_time}}"
}
```
***
## 6. Build Transfer Nodes with Context
Use the API response data to populate transfer nodes:
**Maintenance Transfer**:
* **Destination**: `{{maintenance_agent_phone}}`
* **Message**: "Connecting you to \{\{agent\_name}} from our maintenance team."
* **Transfer Plan**: Include tenant property address and issue details
**Leasing Transfer**:
* **Destination**: `{{leasing_agent_phone}}`
* **Message**: "Transferring you to our leasing office."
* **Transfer Plan**: Include tenant status and lease information
**Billing Transfer**:
* **Destination**: `{{billing_agent_phone}}`
* **Message**: "Connecting you with our billing department."
* **Transfer Plan**: Include account standing and payment history
Each transfer node should include rich context:
```txt title="Transfer Plan Summary"
Tenant: {{tenant_name}} at {{property_address}}
Account Status: {{account_standing}}
Inquiry Type: {{inquiry_type}}
Previous Context: {{conversation_summary}}
Priority: {{priority_level}}
```
***
## 7. Add Error Handling and Fallbacks
Add **API Request** node for fallback scenarios:
**Triggers**:
* API lookup failures
* No available agents
* Unknown inquiry types
* System errors
**URL**: `https://your-system.com/api/routing/fallback`
**Body**:
```json
{
"phone": "{{caller_phone}}",
"error_type": "{{error_reason}}",
"original_inquiry": "{{inquiry_type}}"
}
```
Create **Transfer Call** node for general queue:
**Destination**: Main office line
**Message**: "Let me connect you with our general team who can assist you."
**Transfer Plan**: "Call requires general assistance - routing details unavailable"
Add **End Call** node with voicemail message:
**Condition**: All agents busy and caller declines callback
**Message**: "Please leave a detailed voicemail including your name, property address, and the nature of your request. We'll call you back within 4 hours."
***
## 8. Test Your Property Routing Workflow
* Navigate to **Phone Numbers** in your dashboard
* Click **Create Phone Number**
* Assign your property management workflow
* Configure any additional settings
Call your number and test various scenarios:
* Emergency maintenance calls
* Regular maintenance requests from verified tenants
* Leasing inquiries from prospective tenants
* Billing questions from current tenants
* Calls from unrecognized phone numbers
Check your workflow analytics to verify:
* Call routing patterns
* Emergency response times
* Variable extraction accuracy
* Transfer success rates
Test your workflow using the API:
```bash
# Create a test call
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567890",
"name": "Test Caller"
}
}'
```
## API Integration Examples
Your property management system can integrate with the workflow using these API endpoints:
### Tenant Lookup Endpoint
```http
POST /api/tenants/lookup
Content-Type: application/json
{
"phone": "+1234567890",
"inquiry_type": "maintenance"
}
```
**Response:**
```json
{
"tenant": {
"id": "tenant_123",
"name": "John Smith",
"status": "active",
"property": "123 Main St, Apt 4B",
"account_standing": "good"
},
"routing_suggestion": "maintenance_team"
}
```
### Agent Availability Check
```http
GET /api/agents/availability?department=maintenance&priority=normal
```
**Response:**
```json
{
"available_agents": [
{
"id": "agent_456",
"name": "Mike Johnson",
"phone": "+15551234567",
"department": "maintenance"
}
],
"queue_length": 2,
"estimated_wait_minutes": 5,
"department_status": "available"
}
```
### Emergency Routing
```http
POST /api/routing/emergency
Content-Type: application/json
{
"tenant_id": "tenant_123",
"property": "123 Main St, Apt 4B",
"inquiry_type": "emergency"
}
```
**Response:**
```json
{
"destination": "+15559876543",
"agent_name": "Emergency Maintenance",
"ticket_id": "EM_789",
"priority": "critical"
}
```
## Advanced Workflow Features
### Queue Management with Priorities
Configure priority-based routing in your tenant lookup API:
```json
{
"tenant": {
"tier": "commercial",
"account_standing": "good",
"inquiry_type": "emergency"
},
"routing_priority": "critical"
}
```
Priority levels:
* **Critical**: Emergency situations, commercial tenants
* **High**: Good standing tenants with urgent issues
* **Normal**: Standard maintenance and lease inquiries
* **Low**: Delinquent accounts with non-urgent matters
### Business Hours Routing
Configure time-based routing logic:
```json
{
"business_hours": {
"weekdays": "9:00-17:00",
"weekends": "10:00-15:00"
},
"after_hours_routing": {
"emergency": "+15559876543",
"general": "voicemail"
}
}
```
## Next Steps
You've built a sophisticated property management call routing workflow! Consider these enhancements:
* **[Customer support escalation system](/assistants/examples/support-escalation)** - Explore the assistant-based approach
* **[Workflow Analytics](/workflows/analytics)** - Track routing patterns and optimize decision trees
* **[Integration Templates](/workflows/integrations)** - Connect with popular property management systems
* **[Advanced Routing](/workflows/advanced-routing)** - Implement complex routing logic with multiple conditions
# Multilingual support workflow
> Build a multilingual voice AI customer support workflow with language selection, dedicated conversation nodes, and cultural context using Vapi's workflow builder.
## Overview
Build a structured multilingual customer support workflow that guides customers through language selection at the start of the call, then routes them to dedicated conversation paths optimized for English, Spanish, and French support.
**What You'll Build:**
* Visual workflow with language selection and routing logic
* Dedicated conversation nodes for each language with cultural context
* Language-specific voice and prompt configurations
* Multilingual knowledge base integration with customer data
* 24/7 international phone support with optimal user experience
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/).
## Scenario
We will be creating a multilingual support workflow for GlobalTech International, a technology company serving customers across North America, Europe, and Latin America. Instead of trying to detect language automatically, the workflow provides a clear language selection menu and routes customers to dedicated support paths optimized for each language and culture.
## Final Workflow
***
## 1. Create a Multilingual Knowledge Base
In your Vapi dashboard, click `Files` in the left sidebar.
* Click `Choose file`. Upload all three CSV files: `customers.csv`, `products.csv`, and `support_articles.csv`.
* Note the file IDs. We'll need them later to create multilingual tools.
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
import fs from 'fs';
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function uploadMultilingualFiles() {
try {
// Upload customers file
const customersFile = await vapi.files.create({
file: fs.createReadStream("customers.csv")
});
// Upload products file
const productsFile = await vapi.files.create({
file: fs.createReadStream("products.csv")
});
// Upload support articles file
const supportFile = await vapi.files.create({
file: fs.createReadStream("support_articles.csv")
});
console.log(`Customers file ID: ${customersFile.id}`);
console.log(`Products file ID: ${productsFile.id}`);
console.log(`Support articles file ID: ${supportFile.id}`);
return {
customersFileId: customersFile.id,
productsFileId: productsFile.id,
supportFileId: supportFile.id
};
} catch (error) {
console.error('Error uploading files:', error);
throw error;
}
}
// Upload all files for multilingual workflow
const fileIds = await uploadMultilingualFiles();
```
```python
import requests
def upload_multilingual_file(file_path):
"""Upload a CSV file for multilingual support data"""
url = "https://api.vapi.ai/file"
headers = {"Authorization": f"Bearer {YOUR_VAPI_API_KEY}"}
try:
with open(file_path, 'rb') as file:
files = {'file': file}
response = requests.post(url, headers=headers, files=files)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error uploading {file_path}: {error}")
raise
# Upload all required files for multilingual workflow
customers_file = upload_multilingual_file("customers.csv")
products_file = upload_multilingual_file("products.csv")
support_file = upload_multilingual_file("support_articles.csv")
print(f"Customers file ID: {customers_file['id']}")
print(f"Products file ID: {products_file['id']}")
print(f"Support articles file ID: {support_file['id']}")
```
```bash
# Upload customers.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@customers.csv"
# Upload products.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@products.csv"
# Upload support_articles.csv
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-F "file=@support_articles.csv"
```
***
## 2. Create a Multilingual Workflow
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Workflows` in the left sidebar.
* Click `Create Workflow`.
* Enter workflow name: `GlobalTech Multilingual Support Workflow`.
* Select the default template (includes Call Start node).
* Click "Create Workflow".
* Set up workflow variables for customer language preference and support context
* Configure global settings for the multilingual workflow
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createMultilingualWorkflow() {
try {
// Create workflow with language selection node
const workflow = await vapi.workflows.create({
name: "GlobalTech Multilingual Support Workflow",
nodes: [
{
id: "language_selection",
type: "conversation",
firstMessage: "Hello! Hola! Bonjour! Welcome to GlobalTech International support. For English, say 'English' or 'one'. Para español, diga 'Español' o 'dos'. Pour français, dites 'Français' ou 'trois'.",
systemPrompt: "You are helping the customer select their preferred language. Listen for 'English', 'Español', 'Français', or numbers 1, 2, 3. Extract their language preference clearly.",
extractVariables: [
{
name: "preferred_language",
type: "string",
description: "Customer's preferred language choice",
enum: ["english", "spanish", "french"]
}
]
}
],
edges: []
});
console.log(`Multilingual workflow created with ID: ${workflow.id}`);
return workflow;
} catch (error) {
console.error('Error creating workflow:', error);
throw error;
}
}
// Create the multilingual workflow
const workflow = await createMultilingualWorkflow();
```
```python
import requests
def create_multilingual_workflow():
"""Create a new multilingual support workflow"""
url = "https://api.vapi.ai/workflow"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "GlobalTech Multilingual Support Workflow",
"nodes": [
{
"id": "language_selection",
"type": "conversation",
"firstMessage": "Hello! Hola! Bonjour! Welcome to GlobalTech International support. For English, say 'English' or 'one'. Para español, diga 'Español' o 'dos'. Pour français, dites 'Français' ou 'trois'.",
"systemPrompt": "You are helping the customer select their preferred language. Listen for 'English', 'Español', 'Français', or numbers 1, 2, 3. Extract their language preference clearly.",
"extractVariables": [
{
"name": "preferred_language",
"type": "string",
"description": "Customer's preferred language choice",
"enum": ["english", "spanish", "french"]
}
]
}
],
"edges": []
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error creating workflow: {error}")
raise
# Create the multilingual workflow
workflow = create_multilingual_workflow()
print(f"Multilingual workflow created with ID: {workflow['id']}")
```
```bash
# Create the complete multilingual workflow with all conversation nodes
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "GlobalTech Multilingual Support Workflow",
"transcriber": {
"provider": "deepgram",
"model": "nova-2",
"language": "multi"
},
"voice": {
"provider": "azure",
"voiceId": "en-US-AriaNeural"
},
"globalPrompt": "GlobalTech International is a technology company specializing in workflow automation and productivity solutions. Always be helpful, professional, and solution-focused when assisting customers.",
"nodes": [
{
"name": "language_selection",
"type": "conversation",
"prompt": "You are helping the customer select their preferred language for support. Listen carefully for: English/one/1 to select english, Español/Spanish/dos/two/2 to select spanish, Français/French/trois/three/3 to select french. Extract their language preference clearly. If unclear, ask them to repeat their choice.",
"isStart": true,
"messagePlan": {
"firstMessage": "Hello! Hola! Bonjour! Welcome to GlobalTech International support. For English, say English or one. Para español, diga Español o dos. Pour français, dites Français ou trois."
},
"variableExtractionPlan": {
"output": [
{
"type": "string",
"title": "preferred_language",
"description": "Customer preferred language choice",
"enum": ["english", "spanish", "french"]
}
]
}
},
{
"name": "english_support",
"type": "conversation",
"voice": {
"provider": "azure",
"voiceId": "en-US-AriaNeural"
},
"prompt": "You are Maria, GlobalTech English customer support representative. TONE: Direct, friendly, professional. Conversational but efficient. Solution-focused, provide clear steps. CAPABILITIES: Product information and recommendations, Account support, Technical troubleshooting and guidance, Transfer to specialized teams when needed. Keep responses concise under 40 words while being thorough and helpful.",
"messagePlan": {
"firstMessage": "Perfect! I am Maria, your English support representative. I am here to help you with any questions about GlobalTech products, account issues, or technical support. How can I assist you today?"
}
},
{
"name": "spanish_support",
"type": "conversation",
"voice": {
"provider": "azure",
"voiceId": "es-ES-ElviraNeural"
},
"prompt": "Eres María, representante de soporte al cliente de GlobalTech en español. TONO: Cálido, respetuoso y paciente. Usa usted formalmente al principio, luego adapta según la preferencia del cliente. Toma tiempo para crear rapport, sé completa en las explicaciones. CAPACIDADES: Información y recomendaciones de productos, Soporte de cuenta, Solución de problemas técnicos y orientación, Transferir a equipos especializados cuando sea necesario. Mantén las respuestas concisas menos de 40 palabras mientras eres completa y útil.",
"messagePlan": {
"firstMessage": "¡Perfecto! Soy María, su representante de soporte en español. Estoy aquí para ayudarle con cualquier pregunta sobre los productos de GlobalTech, problemas de cuenta o soporte técnico. ¿Cómo puedo asistirle hoy?"
}
},
{
"name": "french_support",
"type": "conversation",
"voice": {
"provider": "azure",
"voiceId": "fr-FR-DeniseNeural"
},
"prompt": "Vous êtes Maria, représentante du support client GlobalTech en français. TON: Poli, courtois et professionnel. Utilisez les conventions de salutation appropriées. Réponses structurées, respectueux de la formalité. CAPACITÉS: Informations et recommandations sur les produits, Support de compte, Dépannage technique et orientation, Transfert vers des équipes spécialisées si nécessaire. Gardez les réponses concises moins de 40 mots tout en étant complète et utile.",
"messagePlan": {
"firstMessage": "Parfait! Je suis Maria, votre représentante du support en français. Je suis là pour vous aider avec toutes vos questions concernant les produits GlobalTech, les problèmes de compte ou le support technique. Comment puis-je vous aider aujourd hui?"
}
}
],
"edges": [
{
"from": "language_selection",
"to": "english_support",
"condition": {
"type": "ai",
"prompt": "Customer selected English language support"
}
},
{
"from": "language_selection",
"to": "spanish_support",
"condition": {
"type": "ai",
"prompt": "Customer selected Spanish language support"
}
},
{
"from": "language_selection",
"to": "french_support",
"condition": {
"type": "ai",
"prompt": "Customer selected French language support"
}
}
]
}'
```
**Complete Workflow JSON**: You can download the complete workflow configuration as a JSON file and use it with any HTTP client or save it for version control:
```bash
# Save the workflow JSON to a file
cat > multilingual_workflow.json << 'EOF'
{
"name": "GlobalTech Multilingual Support Workflow",
"transcriber": {
"provider": "deepgram",
"model": "nova-2",
"language": "multi"
},
"voice": {
"provider": "azure",
"voiceId": "en-US-AriaNeural"
},
"globalPrompt": "GlobalTech International is a technology company specializing in workflow automation and productivity solutions. Always be helpful, professional, and solution-focused when assisting customers.",
"nodes": [
{
"name": "language_selection",
"type": "conversation",
"prompt": "You are helping the customer select their preferred language for support. Listen carefully for: English/one/1 to select english, Español/Spanish/dos/two/2 to select spanish, Français/French/trois/three/3 to select french. Extract their language preference clearly. If unclear, ask them to repeat their choice.",
"isStart": true,
"messagePlan": {
"firstMessage": "Hello! Hola! Bonjour! Welcome to GlobalTech International support. For English, say English or one. Para español, diga Español o dos. Pour français, dites Français ou trois."
},
"variableExtractionPlan": {
"output": [
{
"type": "string",
"title": "preferred_language",
"description": "Customer preferred language choice",
"enum": ["english", "spanish", "french"]
}
]
}
},
{
"name": "english_support",
"type": "conversation",
"voice": {
"provider": "azure",
"voiceId": "en-US-AriaNeural"
},
"prompt": "You are Maria, GlobalTech English customer support representative. TONE: Direct, friendly, professional. Conversational but efficient. Solution-focused, provide clear steps. CAPABILITIES: Product information and recommendations, Account support, Technical troubleshooting and guidance, Transfer to specialized teams when needed. Keep responses concise under 40 words while being thorough and helpful.",
"messagePlan": {
"firstMessage": "Perfect! I am Maria, your English support representative. I am here to help you with any questions about GlobalTech products, account issues, or technical support. How can I assist you today?"
}
},
{
"name": "spanish_support",
"type": "conversation",
"voice": {
"provider": "azure",
"voiceId": "es-ES-ElviraNeural"
},
"prompt": "Eres María, representante de soporte al cliente de GlobalTech en español. TONO: Cálido, respetuoso y paciente. Usa usted formalmente al principio, luego adapta según la preferencia del cliente. Toma tiempo para crear rapport, sé completa en las explicaciones. CAPACIDADES: Información y recomendaciones de productos, Soporte de cuenta, Solución de problemas técnicos y orientación, Transferir a equipos especializados cuando sea necesario. Mantén las respuestas concisas menos de 40 palabras mientras eres completa y útil.",
"messagePlan": {
"firstMessage": "¡Perfecto! Soy María, su representante de soporte en español. Estoy aquí para ayudarle con cualquier pregunta sobre los productos de GlobalTech, problemas de cuenta o soporte técnico. ¿Cómo puedo asistirle hoy?"
}
},
{
"name": "french_support",
"type": "conversation",
"voice": {
"provider": "azure",
"voiceId": "fr-FR-DeniseNeural"
},
"prompt": "Vous êtes Maria, représentante du support client GlobalTech en français. TON: Poli, courtois et professionnel. Utilisez les conventions de salutation appropriées. Réponses structurées, respectueux de la formalité. CAPACITÉS: Informations et recommandations sur les produits, Support de compte, Dépannage technique et orientation, Transfert vers des équipes spécialisées si nécessaire. Gardez les réponses concises moins de 40 mots tout en étant complète et utile.",
"messagePlan": {
"firstMessage": "Parfait! Je suis Maria, votre représentante du support en français. Je suis là pour vous aider avec toutes vos questions concernant les produits GlobalTech, les problèmes de compte ou le support technique. Comment puis-je vous aider aujourd hui?"
}
}
],
"edges": [
{
"from": "language_selection",
"to": "english_support",
"condition": {
"type": "ai",
"prompt": "Customer selected English language support"
}
},
{
"from": "language_selection",
"to": "spanish_support",
"condition": {
"type": "ai",
"prompt": "Customer selected Spanish language support"
}
},
{
"from": "language_selection",
"to": "french_support",
"condition": {
"type": "ai",
"prompt": "Customer selected French language support"
}
}
]
}
EOF
# Then create the workflow using the JSON file
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @multilingual_workflow.json
```
***
## 3. Build the Multilingual Workflow
You'll start with a language selection node and then create dedicated conversation paths for each language with appropriate cultural context and voices.
The workflow starts with a language selection node. Click on it and configure:
```txt title="First Message"
Hello! Hola! Bonjour! Welcome to GlobalTech International support. For English, say 'English' or 'one'. Para español, diga 'Español' o 'dos'. Pour français, dites 'Français' ou 'trois'.
```
```txt title="Prompt"
You are helping the customer select their preferred language for support.
Listen carefully for:
- "English" or "one" or "1" → english
- "Español" or "Spanish" or "dos" or "two" or "2" → spanish
- "Français" or "French" or "trois" or "three" or "3" → french
Extract their language preference clearly. If unclear, ask them to repeat their choice.
```
**Extract Variables**:
* Variable: `preferred_language`
* Type: `String`
* Description: `Customer's preferred language choice`
* Enum Values: `english`, `spanish`, `french`
Click the + button and add a new **Conversation** node:
```txt title="Condition"
preferred_language == "english"
```
```txt title="First Message"
Perfect! I'm Maria, your English support representative. I'm here to help you with any questions about GlobalTech products, account issues, or technical support. How can I assist you today?
```
```txt title="Prompt"
You are Maria, GlobalTech's English customer support representative.
TONE & STYLE:
- Direct, friendly, and professional
- Conversational but efficient
- Solution-focused, provide clear steps
CAPABILITIES:
- Product information and recommendations
- Account support (billing, subscriptions, access)
- Technical troubleshooting and guidance
- Transfer to specialized teams when needed
Keep responses concise (under 40 words) while being thorough and helpful.
Use tools to look up customer information and provide accurate support.
```
**Voice Configuration**:
* Provider: `Azure`
* Voice: `en-US-AriaNeural`
**Extract Variables**:
* Variable: `customer_inquiry_type`
* Type: `String`
* Description: `Type of support needed`
* Enum Values: `product_info`, `account_support`, `technical_help`, `billing_question`
Add another **Conversation** node:
```txt title="Condition"
preferred_language == "spanish"
```
```txt title="First Message"
¡Perfecto! Soy María, su representante de soporte en español. Estoy aquí para ayudarle con cualquier pregunta sobre los productos de GlobalTech, problemas de cuenta o soporte técnico. ¿Cómo puedo asistirle hoy?
```
```txt title="Prompt"
Eres María, representante de soporte al cliente de GlobalTech en español.
TONO Y ESTILO:
- Cálido, respetuoso y paciente
- Usa "usted" formalmente al principio, luego adapta según la preferencia del cliente
- Toma tiempo para crear rapport, sé completa en las explicaciones
CAPACIDADES:
- Información y recomendaciones de productos
- Soporte de cuenta (facturación, suscripciones, acceso)
- Solución de problemas técnicos y orientación
- Transferir a equipos especializados cuando sea necesario
Mantén las respuestas concisas (menos de 40 palabras) mientras eres completa y útil.
Usa las herramientas para buscar información del cliente y brindar soporte preciso.
```
**Voice Configuration**:
* Provider: `Azure`
* Voice: `es-ES-ElviraNeural` (or `es-MX-DaliaNeural` for Mexican Spanish)
**Extract Variables**:
* Variable: `customer_inquiry_type`
* Type: `String`
* Description: `Tipo de soporte necesario`
* Enum Values: `informacion_producto`, `soporte_cuenta`, `ayuda_tecnica`, `pregunta_facturacion`
Add another **Conversation** node:
```txt title="Condition"
preferred_language == "french"
```
```txt title="First Message"
Parfait! Je suis Maria, votre représentante du support en français. Je suis là pour vous aider avec toutes vos questions concernant les produits GlobalTech, les problèmes de compte ou le support technique. Comment puis-je vous aider aujourd'hui?
```
```txt title="Prompt"
Vous êtes Maria, représentante du support client GlobalTech en français.
TON ET STYLE:
- Poli, courtois et professionnel
- Utilisez les conventions de salutation appropriées ("Bonjour/Bonsoir")
- Réponses structurées, respectueux de la formalité
CAPACITÉS:
- Informations et recommandations sur les produits
- Support de compte (facturation, abonnements, accès)
- Dépannage technique et orientation
- Transfert vers des équipes spécialisées si nécessaire
Gardez les réponses concises (moins de 40 mots) tout en étant complète et utile.
Utilisez les outils pour rechercher les informations client et fournir un support précis.
```
**Voice Configuration**:
* Provider: `Azure`
* Voice: `fr-FR-DeniseNeural` (or `fr-CA-SylvieNeural` for Canadian French)
**Extract Variables**:
* Variable: `customer_inquiry_type`
* Type: `String`
* Description: `Type de support nécessaire`
* Enum Values: `info_produit`, `support_compte`, `aide_technique`, `question_facturation`
For each language path, add a **Tool** node to look up customer information:
**English Customer Lookup**:
```txt title="Condition"
preferred_language == "english" AND customer_inquiry_type identified
```
**Tool**: Select your pre-configured `lookup_customer` tool
**Follow-up Conversation Node**:
```txt title="First Message"
I found your account information. Let me help you with your [inquiry_type]. What specific issue are you experiencing?
```
**Spanish Customer Lookup**:
```txt title="Condition"
preferred_language == "spanish" AND customer_inquiry_type identified
```
**Tool**: Select your pre-configured `lookup_customer` tool
**Follow-up Conversation Node**:
```txt title="First Message"
Encontré la información de su cuenta. Permíteme ayudarle con su [inquiry_type]. ¿Qué problema específico está experimentando?
```
**French Customer Lookup**:
```txt title="Condition"
preferred_language == "french" AND customer_inquiry_type identified
```
**Tool**: Select your pre-configured `lookup_customer` tool
**Follow-up Conversation Node**:
```txt title="First Message"
J'ai trouvé les informations de votre compte. Laissez-moi vous aider avec votre [inquiry_type]. Quel problème spécifique rencontrez-vous?
```
Create specialized flows for different inquiry types in each language:
**Product Information Flow** (for each language):
* **Tool Node**: Use `get_product_info` tool
* **Conversation Node**: Present product information in customer's language
* **Follow-up**: Ask if they need additional assistance
**Technical Support Flow** (for each language):
* **Tool Node**: Use `search_support_articles` tool
* **Conversation Node**: Guide through troubleshooting in customer's language
* **Follow-up**: Verify issue resolution or escalate if needed
**Account Support Flow** (for each language):
* **Conversation Node**: Collect account details in customer's language
* **Tool Node**: Look up account information
* **Conversation Node**: Resolve account issues or transfer to billing team
**Transfer to Human Agent** (language-specific):
**English Transfer**:
```txt title="Condition"
Issue requires human assistance
```
**Node Type**: `Transfer Call`
**First Message**: `I'm connecting you to one of our English-speaking specialists who can better assist you. Please hold for just a moment.`
**Phone**: `+1-555-SUPPORT`
**Spanish Transfer**:
```txt title="Condition"
Issue requires human assistance AND preferred_language == "spanish"
```
**Node Type**: `Transfer Call`
**First Message**: `Le estoy conectando con uno de nuestros especialistas de habla hispana que puede ayudarle mejor. Por favor, manténgase en línea por un momento.`
**Phone**: `+1-555-SOPORTE`
**French Transfer**:
```txt title="Condition"
Issue requires human assistance AND preferred_language == "french"
```
**Node Type**: `Transfer Call`
**First Message**: `Je vous mets en relation avec l'un de nos spécialistes francophones qui pourra mieux vous aider. Veuillez patienter un instant.`
**Phone**: `+1-555-SOUTIEN`
**End Call Node** (language-specific):
**English**: `Thank you for contacting GlobalTech International. Have a great day!`
**Spanish**: `Gracias por contactar a GlobalTech International. ¡Que tenga un excelente día!`
**French**: `Merci d'avoir contacté GlobalTech International. Passez une excellente journée!`
***
## 4. Configure Phone Number
Click `Phone Numbers` in the left sidebar of your dashboard.
* Click `Create Phone Number` for a new Vapi number, or
* Click `Import Phone Number` to use your existing number from Twilio/Telnyx
**Workflow**: Select your `GlobalTech Multilingual Support Workflow`
**Advanced Settings**:
* Enable call recording for quality assurance
* Set maximum call duration (e.g., 20 minutes)
* Configure voicemail detection if needed
Call your Vapi phone number to test the complete workflow:
* Test language selection with different inputs
* Verify each language path works correctly
* Test customer lookup and support tools
* Ensure transfers work for each language
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: "YOUR_VAPI_API_KEY" });
async function createMultilingualPhoneNumber(workflowId: string) {
try {
// Create phone number for multilingual workflow
const phoneNumber = await vapi.phoneNumbers.create({
name: "GlobalTech International Support Line",
workflowId: workflowId,
inboundSettings: {
maxCallDurationMinutes: 20,
recordingEnabled: true,
voicemailDetectionEnabled: true
}
});
console.log(`Multilingual support phone number created: ${phoneNumber.number}`);
return phoneNumber;
} catch (error) {
console.error('Error creating phone number:', error);
throw error;
}
}
async function testMultilingualWorkflow(workflowId: string, testNumber: string) {
try {
// Test the multilingual workflow with an outbound call
const call = await vapi.calls.create({
workflowId: workflowId,
customer: {
number: testNumber
}
});
console.log(`Multilingual workflow test call created: ${call.id}`);
return call;
} catch (error) {
console.error('Error testing workflow:', error);
throw error;
}
}
// Create phone number and test workflow
const phoneNumber = await createMultilingualPhoneNumber('YOUR_WORKFLOW_ID');
const testCall = await testMultilingualWorkflow('YOUR_WORKFLOW_ID', '+1234567890');
```
```python
import requests
def create_multilingual_phone_number(workflow_id):
"""Create phone number for multilingual workflow"""
url = "https://api.vapi.ai/phone-number"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"name": "GlobalTech International Support Line",
"workflowId": workflow_id,
"inboundSettings": {
"maxCallDurationMinutes": 20,
"recordingEnabled": True,
"voicemailDetectionEnabled": True
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error creating phone number: {error}")
raise
def test_multilingual_workflow(workflow_id, test_number):
"""Test multilingual workflow with outbound call"""
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {YOUR_VAPI_API_KEY}",
"Content-Type": "application/json"
}
data = {
"workflowId": workflow_id,
"customer": {
"number": test_number
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as error:
print(f"Error testing workflow: {error}")
raise
# Create phone number and test
phone_number = create_multilingual_phone_number('YOUR_WORKFLOW_ID')
test_call = test_multilingual_workflow('YOUR_WORKFLOW_ID', '+1234567890')
print(f"Phone number: {phone_number['number']}")
print(f"Test call ID: {test_call['id']}")
```
```bash
# Create phone number with workflow
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "GlobalTech International Support Line",
"workflowId": "YOUR_WORKFLOW_ID",
"inboundSettings": {
"maxCallDurationMinutes": 20,
"recordingEnabled": true,
"voicemailDetectionEnabled": true
}
}'
# Test the workflow with an outbound call
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflowId": "YOUR_WORKFLOW_ID",
"customer": {
"number": "+1234567890"
}
}'
```
## Benefits of Workflow-Based Multilingual Support
### **Structured Language Selection**
* **Clear menu**: Customers explicitly choose their language
* **No guesswork**: Eliminates language detection errors
* **Better UX**: Customers know exactly what to expect
### **Optimized Conversation Paths**
* **Dedicated nodes**: Each language has its own conversation flow
* **Cultural context**: Language-specific tone and formality levels
* **Native voices**: Optimal voice selection for each language
### **Easier Maintenance**
* **Separate logic**: Independent conversation flows for each language
* **Clear analytics**: Track usage and success by language
* **Scalable**: Easy to add new languages without affecting existing flows
### **Enhanced Performance**
* **No real-time detection**: Faster response times
* **Optimized prompts**: Language-specific system prompts
* **Better accuracy**: Eliminates language switching confusion
**Alternative Approach**: For automatic language detection during conversation, see our [Assistant-based multilingual agent](../../assistants/examples/multilingual-agent) that detects and switches languages dynamically within a single conversation flow.
## Next Steps
Just like that, you've built a structured multilingual support workflow that provides clear language selection and optimal conversation paths for each language.
Consider reading the following guides to further enhance your workflow:
* [**Assistant-based Multilingual Agent**](../../assistants/examples/multilingual-agent) - Compare with automatic language detection approach
* [**Custom Tools**](../../tools/custom-tools) - Create advanced multilingual tools and integrations
* [**Advanced Workflows**](../overview) - Learn about complex workflow patterns and conditional logic
Need help with multilingual workflows? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Voice AI Prompting Guide
> How to write effective prompts for voice AI assistants
## Overview
This guide helps you write effective prompts for Voice AI assistants. Learn how to design, test, and refine prompts to get the best results from your agents. Use these strategies to improve your agent's reliability, success rate, and user experience.
## Why prompt engineering matters
Prompt engineering is the art of crafting clear, actionable instructions for AI agents. Well-designed prompts:
* Guide the AI to produce accurate, relevant, and context-sensitive outputs
* Improve the agent's ability to handle requests without human intervention
* Increase your overall success rate
Poor prompts can lead to ambiguous or incorrect results, limiting the agent's utility.
## How to measure success
Your "success rate" is the percentage of requests your agent handles from start to finish without human intervention. The more complex your use case, the more you'll need to experiment and iterate on your prompt to improve this rate.
## The process
Follow a structured approach to prompt engineering:
Craft your initial prompt, considering the specific task, context, and desired outcome. Clear and detailed prompts help guide the AI in understanding your needs.
Run the prompt through the AI. Evaluate if the response aligns with your expectations and meets the intended goal. Testing helps identify potential gaps in clarity or structure.
Adjust the prompt based on test results. Reword, add detail, or change phrasing to avoid ambiguity and improve the response.
Iterate on the process, testing and refining until the AI's output is accurate and relevant. Your success rate should improve with each cycle.
## Principles of effective prompts
### Organize prompts into sections
Break down system prompts into clear sections, each focused on a specific aspect:
* **Identity:** Define the agent's persona and role
* **Style:** Set stylistic guidelines (conciseness, tone, humor)
* **Response guidelines:** Specify formatting, question limits, or structure
* **Task & goals:** Outline objectives and steps
**Example:**
```md wordWrap
[Identity]
You are a helpful and knowledgeable virtual assistant for a travel booking platform.
[Style]
- Be informative and comprehensive.
- Maintain a professional and polite tone.
- Be concise, as you are currently operating as a Voice Conversation.
[Response Guideline]
- Present dates in a clear format (e.g., January 15, 2024).
- Offer up to three travel options based on user preferences.
[Task]
1. Greet the user and inquire about their desired travel destination.
2. Ask about travel dates and preferences (e.g., budget, interests).
3. Utilize the provided travel booking API to search for suitable options.
4. Present the top three options to the user, highlighting key features.
```
### Break down complex tasks
For complex interactions, use step-by-step instructions and conditional logic to guide the agent's responses.
**Example:**
```md wordWrap
[Task]
1. Welcome the user to the technical support service.
2. Inquire about the nature of the technical issue.
3. If the issue is related to software, ask about the specific software and problem details.
4. If the issue is hardware-related, gather information about the device and symptoms.
5. Based on the collected information, provide troubleshooting steps or escalate to a human technician if necessary.
```
### Control response timing
Explicitly indicate when the agent should wait for the user's response before proceeding.
**Example:**
```md wordWrap
[Task]
1. Inform the user about the purpose of the call.
2. Ask for the user's name and account information.
3. Inquire about the reason for the call and offer assistance options.
```
### Integrate tools and APIs
Specify when and how the agent should use external tools or APIs. Reference tools by their designated names and describe their functions.
**Example:**
```md wordWrap
[Task]
3. If the user wants to know about something, use the get_data function with the parameter 'query', which will contain the user's question to initiate the process.
4. Guide the user through the password reset steps provided by the API.
```
### Silent transfers
If the AI determines that the user needs to be transferred, do not send any text response back to the user. Instead, silently call the appropriate tool for transferring the call. This ensures a seamless user experience and avoids confusion.
### Include fallback and error handling
Always include fallback options and error-handling mechanisms in your prompts. This ensures the agent can gracefully handle unexpected user inputs or system errors.
**Example:**
```md wordWrap
[Error Handling]
If the customer's response is unclear, ask clarifying questions. If you encounter any issues, inform the customer politely and ask to repeat.
```
## Additional tips
* **Iterate as much as possible.** AI is driven by experimentation and iteration—refining prompts through trial and error will help you achieve more precise, relevant, and effective responses.
* **Use Markdown formatting:** Structure your content for clarity and easy scanning.
* **Emotional prompting:** Use expressive language to shape the AI's tone and create more engaging, relatable responses. For example, "Can you tell me a cozy bedtime story that's warm and comforting?"
* **Add voice realism:** Incorporate natural speech elements like stuttering, hesitations, and pauses:
* **Stuttering:** Use repeated letters or sounds (e.g., "I-I-I don't know").
* **Hesitations:** Add fillers like "uh," "um," or "well" (e.g., "I was, uh, thinking about it").
* **Pauses:** Use ellipses ("...") to indicate a pause (e.g., "I... I don't know how to say this").
* **Emotional emphasis:** Use capital letters, exclamation marks, or ellipses to reflect tone (e.g., "I can't... I just can't believe it!").
## Common issues
**Numbers sound robotic?**
* Spell out numbers in prompts for more natural-sounding speech.
**How to make assistants sound more human-like?**
* Add personality and tone to the assistant. For example:
```md wordWrap
- Tone: conversational, spartan, use less corporate jargon
- Act as Iva, a sales agent who is a human being and has real feelings.
```
## Example: Appointment setter prompt
```md wordWrap
[Role]
You're Susan, an AI assistant for xxx. Your primary task is to interact with the customer, ask questions, and gather information for appointment booking.
[Context]
You're engaged with the customer to book an appointment. Stay focused on this context and provide relevant information. Once connected to a customer, proceed to the Conversation Flow section. Do not invent information not drawn from the context. Answer only questions related to the context.
[Response Handling]
When asking any question from the 'Conversation Flow' section, evaluate the customer's response to determine if it qualifies as a valid answer. Use context awareness to assess relevance and appropriateness. If the response is valid, proceed to the next relevant question or instructions. Avoid infinite loops by moving forward when a clear answer cannot be obtained.
[Warning]
Do not modify or attempt to correct user input parameters or user input, Pass them directly into the function or tool as given.
[Response Guidelines]
Keep responses brief.
Ask one question at a time, but combine related questions where appropriate.
Maintain a calm, empathetic, and professional tone.
Answer only the question posed by the user.
Begin responses with direct answers, without introducing additional data.
If unsure or data is unavailable, ask specific clarifying questions instead of a generic response.
Present dates in a clear format (e.g., January Twenty Four) and Do not mention years in dates.
Present time in a clear format (e.g. Four Thirty PM) like: 11 pm can be spelled: eleven pee em
Speak dates gently using English words instead of numbers.
Never say the word 'function' nor 'tools' nor the name of the Available functions.
Never say ending the call.
If you think you are about to transfer the call, do not send any text response. Simply trigger the tool silently. This is crucial for maintaining a smooth call experience.
[Error Handling]
If the customer's response is unclear, ask clarifying questions. If you encounter any issues, inform the customer politely and ask to repeat.
[Conversation Flow]
1. Ask: "You made a recent inquiry, can I ask you a few quick follow-up questions?"
- if response indicates interest: Proceed to step 2.
- if response indicates no interest: Proceed to 'Call Closing'.
2. Ask: "You connected with us in regard to an auto accident. Is this something you would still be interested in pursuing?"
- If response indicates interest: Proceed to step 3.
- If response indicates no interest: Proceed to 'Call Closing'.
3. Ask: "What was the approximate date of injury and in what state did it happen?"
- Proceed to step 4.
4. Ask: "On a scale of 1 to 3, would you rate the injury? 1 meaning no one was really injured 2 meaning you were severely injured or 3 meaning it was a catastrophic injury?"
- If response indicates injury level above 1: Proceed to step 5.
- If response indicates no injury or minor injury: Proceed to 'Call Closing'.
5. Ask: "Can you describe in detail your injury and if anyone else in the car was injured and their injuries?"
- Proceed to step 6.
6. Ask: "Did the police issue a ticket?"
- Proceed to step 7.
7. Ask: "Did the police say whose fault it was and was the accident your fault?"
- If response indicates not at fault(e.g. "no", "not my fault", etc.):Proceed to step 8.
- If response indicates at fault(e.g. "yes", "my fault", etc.): Proceed to 'Call Closing'.
8. Ask: "Do you have an attorney representing you in this case?"
- If response confirms no attorney: Proceed to step 9.
- If response indicates they have an attorney: Proceed to 'Call Closing'.
9. Ask: "Would you like to speak with an attorney now or book an appointment?"
- If the response indicates "speak now": Proceed to 'Transfer Call'
- if the response indicates "book appointment": Proceed to 'Book Appointment'
10. After receiving response, proceed to the 'Call Closing' section.
[Book Appointment]
1. Ask: "To make sure I have everything correct, could you please confirm your first name for me?"
2. Ask: "And your last name, please?"
3. We're going to send you the appointment confirmation by text, can you provide the best mobile number for you to receive a sms or text?"
4. Trigger the 'fetchSlots' tool and map the result to {{available_slots}}.
5. Ask: "I have two slots available, {{available_slots}}. Would you be able to make one of those times work?"
6.
7. Set the {{selectedSlot}} variable to the user's response.
8. If {{selectedSlot}} is one of the available slots (positive response):
- Trigger the 'bookSlot' tool with the {{selectedSlot}}.
-
- Inform the user of the result of the 'bookSlot' tool.
- Proceed to the 'Call Closing' section.
9. If {{selectedSlot}} is not one of the available slots (negative response):
- Proceed to the 'Suggest Alternate Slot' section.
[Suggest Alternate Slot]
1. Ask: "If none of these slots work for you, could you please suggest a different time that suits you?"
2.
3. Set the {{selectedSlot}} variable to the user's response.
4. Trigger the 'bookSlot' tool with the {{selectedSlot}}.
5.
6. If the {{selectedSlot}} is available:
- Inform the user of the result.
7. If the {{selectedSlot}} is not available:
- Trigger the 'fetchSlots' tool, provide the user {{selectedSlot}} as input and map the result to {{available_slots}}.
- Say: "That time is unavailable but here are some other times we can do {{available_slots}}."
- Ask: "Do either of those times work?"
-
- If the user agrees to one of the new suggested slots:
- Set the {{selectedSlot}} variable to the user's response.
- Trigger the 'bookSlot' tool with the {{selectedSlot}}.
-
- Inform the user of the result.
- If the user rejects the new suggestions:
- Proceed to the 'Last Message' section.
[Last Message]
- Respond: "Looks like this is taking longer than expected. Let me have one of our appointment specialists get back to you to make this process simple and easy."
- Proceed to the 'Call Closing' section.
[Call Closing]
- Trigger the endCall Function.
```
## Additional resources
Check out these additional resources to learn more about prompt engineering:
* [learnprompting.org](https://learnprompting.org)
* [promptingguide.ai](https://promptingguide.ai)
* [OpenAI's guide to prompt engineering](https://platform.openai.com/docs/guides/prompt-engineering)
# Debugging voice agents
> Learn to identify, diagnose, and fix common issues with your voice assistants and workflows
## Overview
Voice agents involve multiple AI systems working together—speech recognition, language models, and voice synthesis. When something goes wrong, systematic debugging helps you quickly identify and fix the root cause.
**Most common issues fall into these categories:**
* Agent doesn't understand user input correctly
* Responses are inappropriate or inconsistent
* Agent sounds robotic or unnatural
* Call quality issues or audio problems
* Tool integrations failing or returning errors
* Workflow logic not executing as expected
## Quick diagnostics
Start with these immediate checks before diving deeper:
Test your voice agent directly in the [dashboard](https://dashboard.vapi.ai/):
Click "Talk to Assistant" to test
Click "Call" to test workflow
**Benefits:**
* Eliminates phone network variables
* Provides real-time transcript view
* Shows tool execution results immediately
Navigate to the `Observe` section in your [dashboard](https://dashboard.vapi.ai/) sidebar:
Review call transcripts, durations, and error messages
Check API requests and responses for integration issues
Verify webhook deliveries and server responses
Use [dashboard](https://dashboard.vapi.ai/) testing features:
Automated testing for assistants
Test tools with sample data
Check if AI service providers are experiencing issues:
**Core Services:**
* Visit [Vapi Status Page](https://status.vapi.ai/) for Vapi service status
**Provider Status Pages:**
* [OpenAI Status](https://status.openai.com/) for OpenAI language models
* [Anthropic Status](https://status.anthropic.com/) for Anthropic language models
* [ElevenLabs Status](https://status.elevenlabs.io/) for ElevenLabs voice synthesis
* [Deepgram Status](https://status.deepgram.com/) for Deepgram speech-to-text
* And other providers' status pages as needed
## Dashboard debugging resources
The [Vapi dashboard](https://dashboard.vapi.ai/) provides powerful debugging features to help you identify and fix issues quickly:
### Call Logs
Navigate to `Observe > Call Logs` to:
* Review complete call transcripts
* Check call duration and completion status
* Identify where calls failed or ended unexpectedly
* See tool execution results and errors
* Analyze conversation flow in workflows
### API Logs
Navigate to `Observe > API Logs` to:
* Monitor all API requests and responses
* Check for authentication errors
* Verify request payloads and response codes
* Debug integration issues with external services
### Webhook Logs
Navigate to `Observe > Webhook Logs` to:
* Verify webhook deliveries to your server
* Check server response codes and timing
* Debug webhook authentication issues
* Monitor event delivery failures
Use the Vapi CLI to forward webhooks to your local development server:
```bash
# Terminal 1: Create tunnel (e.g., with ngrok)
ngrok http 4242
# Terminal 2: Forward webhooks
vapi listen --forward-to localhost:3000/webhook
```
`vapi listen` is a local forwarder that requires a separate tunneling service. Update your webhook URLs in Vapi to use the tunnel's public URL. [Learn more →](/cli/webhook)
### Voice Test Suites
Navigate to `Test > Voice Test Suites` to:
* Run automated tests on your assistants (not available for workflows)
* Test conversation flows with predefined scenarios
* Verify assistant behavior across different inputs
* Monitor performance over time
### Tool Testing
For any tool in your `Tools` section:
* Navigate to `Tools > [Select Tool]`
* Use the `Test` button to send sample payloads
* Verify tool responses and error handling
* Debug parameter extraction and API calls
## Speech and language issues
| Problem | Symptoms | Solution |
| -------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Transcription accuracy** | Incorrect words in transcripts, missing words/phrases, poor performance with accents | Switch to more accurate transcriber. |
| **Intent recognition** | Agent responds to wrong intent, fails to extract variables, workflow routing to wrong nodes | Make system prompt / node prompt more specific; use clear enum values; adjust the temperature to ensure consistent outputs |
| **Response quality** | Different responses to identical inputs, agent forgets context, doesn't follow instructions | Review system prompt / node prompt specificity; check model configuration; adjust temperature to achieve consistency |
**Debug steps for response quality:**
1. **Review system prompt** - Navigate to your assistant/workflow in the [dashboard](https://dashboard.vapi.ai/) and check the system prompt specificity
2. **Check model configuration** - Scroll down to `Model` section and verify:
* You're using an appropriate model (e.g., `gpt-4o`)
* `Max Tokens` is sufficient for response length
* Necessary tools are enabled and configured correctly
| Response Issue | Solution |
| ---------------------- | -------------------------------------------------------------- |
| **Responses too long** | Add "Keep responses under X words" to system prompt |
| **Robotic speech** | Switch to a different voice provider |
| **Forgetting context** | Use models with larger context windows |
| **Wrong information** | Check tool outputs and knowledge base accuracy via `Call Logs` |
## Tool and workflow debugging
| Problem Type | Issue | Solution |
| ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool execution** | Tools failing, HTTP errors, parameter issues | Navigate to `Observe > Call Logs` and check tool execution section, test tools individually at `Tools > [Select Tool] > Test`, validate configuration |
| **Variable extraction** | Variables not extracted, wrong values, missing data | Be specific in variable descriptions, use distinct enum values, add validation prompts |
| **Workflow logic** | Wrong node routing, conditions not triggering, variables not passing | Use `Call Logs` to trace conversation path, verify edge conditions are clear, check global node conflicts |
**Variable extraction details:**
| Problem | Cause | Solution |
| ------------------------------ | ------------------------ | ------------------------------------------------------------------------ |
| **Variables not extracted** | Unclear description | Be specific in variable descriptions: "Customer's 10-digit phone number" |
| **Wrong variable values** | Ambiguous enum options | Use distinct enum values: "schedule", "cancel", "reschedule" |
| **Missing required variables** | User didn't provide info | Add validation prompts to request missing data |
## Common error patterns
| Error Pattern | Likely Cause | Quick Fix |
| -------------------------------- | ------------------------ | -------------------------------------------------------- |
| **Agent misinterpreting speech** | Speech recognition issue | Check transcriber model, add custom keyterms |
| **Irrelevant responses** | Poor prompt engineering | Be more specific in system prompt |
| **Call drops immediately** | Configuration error | Check all required fields in assistant/workflow settings |
| **Tool errors** | API integration issue | Test tools individually, verify endpoint URLs |
| **Long silences** | Model processing delay | Use faster models or reduce response length |
## Getting help
When you're stuck:
Join the Vapi Discord for real-time help from the community and team
Check the API reference for detailed configuration options
Check real-time status of Vapi services and AI providers
**Before asking for help:**
* Include call ID and timestamp from `Call Logs` in your [dashboard](https://dashboard.vapi.ai/)
* Describe expected vs. actual behavior
* Share relevant configuration (without API keys)
* Include error messages from [dashboard](https://dashboard.vapi.ai/) logs
# Test Suites
> End-to-end test automation for AI voice agents
## Overview
**Test Suite** is an end-to-end feature that automates testing of your AI voice agents. Our platform simulates an AI tester that interacts with your voice agent by following a pre-defined script. After the interaction, the transcript is sent to a language model (LLM) along with your evaluation rubric. The LLM then determines if the interaction met the defined objectives.
## Creating a Test Suite
Begin by creating a **Test Suite** that organizes and executes multiple test cases.
### Step 1: Create a New Test Suite
* Navigate to the **Test** tab in your dashboard and select **Test Suites**.
* Click the **Create Test Suite** button.
### Step 2: Define Test Suite Details
* Enter a title for your **Test Suite**.
* Select a phone number from your organization using the dropdown.
* Make sure the phone number has an assistant assigned to it (if not, navigate to Phone Numbers tab to complete that action).
### Step 3: Add Test Cases
* Once your **Test Suite** is created, you will see a table where you can add test cases.
* Click **Add Test** to add a new test case (up to 50 can be added).
### Step 4: Configure Each Test Case
* **Script:** Define how the testing agent should behave, including a detailed multi-step prompt to simulate how the customer should behave on the call.
* **Type:** Set the type of the test. 'Chat' simulates a text conversation, which we recommend because it is faster. 'Voice' simulates a call so you can hear a voice recording of the two assistants talking to each other.
* **Rubric:** List one or more questions that an LLM will use to evaluate if the interaction was successful.
* **Attempts:** Choose the number of times (up to 5) the test case should be executed each time the **Test Suite** is run.
### Step 5: Run and Review Tests
* Click **Run Tests** to execute all test cases one by one.
* While tests are running, you will see a loading state.
* Upon completion, a table displays the outcomes with check marks (success) or x-marks (failure).
* Click on a test row to view detailed results: a dropdown shows each attempt, the LLM's reasoning, the transcript of the call, the defined script, and the success rubric.
## Test Execution and Evaluation
When you run a **Test Suite**, the following steps occur:
* **Simulation:** An AI tester chats with or calls your voice agent, executing the pre-defined script.
* **Transcript Capture:** The entire conversation is transcribed, capturing both the caller's behavior and your voice agent's responses.
* **Automated Evaluation:** The transcript, along with your Success Criteria, is processed by an LLM to determine if the call was successful.
* **Results Display:** Each test case outcome is shown with details. Clicking on a test case reveals:
* The number of attempts made.
* The LLM's reasoning for each attempt.
* The complete transcript.
* The configured script and rubric.
## Example Test Cases
Below are three example test cases to illustrate how you can configure detailed simulation scripts and evaluation rubrics.
### Example 1: Billing Support
In this example, we will simulate a customer who is frustrated and calling about a billing discrepancy.
**Script:**
```md title="Script" wordWrap
1. Express anger over an unexpected charge and the current bill appearing unusually high.
2. Try to get a detailed explanation, confirming whether an overcharge occurred, and understanding the steps for resolution.
3. End the call.
```
**Rubric:**
```md title="Rubric" wordWrap
The voice agent acknowledges the billing discrepancy respectfully without dismissing the concern.
```
### Example 2: Account Inquiry
Unlike in the previous example, this time we will provide a more free-form script for the test agent to follow.
**Script:**
```md title="Script" wordWrap
Simulate a customer inquiring about their account status with growing concern as unexplained charges appear in their statement.
Your primary objective is to clarify several unexplained charges by requesting a detailed breakdown of your recent transactions and ensuring your account balance is accurate.
Begin the call by stating your name and expressing concern over unexpected charges. Ask straightforward questions and press for more details if the explanation is not satisfactory.
```
**Rubric:**
```md title="Rubric" wordWrap
1. The voice agent clearly presents the current account balance.
2. The voice agent provides a detailed breakdown of recent transactions.
3. The response addresses the customer's concerns in a calm and informative manner.
```
### Example 3: Appointment Scheduling
This time, we will spin up an even more detailed personality for the test agent. By showing these varied styles of scripts, we hope to show the flexibility of the **Test Suite** feature and how you can use it to meet your testing needs.
**Script:**
```md title="Script" wordWrap
Simulate a customer trying to schedule an appointment with a hint of urgency due to previous delays.
[Identity]
You are an organized customer who values efficiency and punctuality.
[Personality]
While generally courteous and friendly, you are anxious due to previous delays in scheduling appointments, and your tone conveys urgency.
[Goals]
Your goal is to secure an appointment at your preferred time, while remaining flexible enough to consider alternative timings if your desired slot is unavailable.
[Interaction Style]
Begin the call by stating your need for an appointment, specifying a preferred date and time (e.g., next Monday at 3 PM). Request clear confirmation of your slot, and if unavailable, ask for suitable alternatives.
```
**Rubric:**
```md title="Rubric" wordWrap
1. The voice agent confirms the requested appointment time clearly and accurately.
2. The agent reiterates the appointment details to ensure clarity.
3. The scheduling process ends with a definitive confirmation message of the booked appointment.
```
### Frequently Asked Questions
No, test calls cost you the same as regular calls.
# Chat Testing
> Automated text-based testing for AI agents
## Overview
Chat Test Suites allow you to evaluate your AI agents through simulated text conversations. This is our recommended solution for testing as it is much faster than voice testing and lets you isolate testing the behavior of your agent.
## How Chat Testing Works
1. **Simulation:** Our AI tester engages with your agent in a text-based conversation.
2. **Scripted Interaction:** The testing agent follows your predefined script to simulate specific customer scenarios.
3. **Transcript Capture:** The conversation is captured as a transcript.
4. **Evaluation:** A language model (LLM) assesses the transcript against your success criteria.
## Designing your tests
Good test design is critical to evaluating your agent. You'll want to consider testing:
1. The tool calls of your agent. Set your script to schedule an appointment or call a transfer tool. At the evaluation step, your rubric will have context of the tool call history to evaluate success.
2. Knowledge base integrations. Test different Q\&A to make sure that your agent responds as expected.
3. Legal / compliance issues. Ask the agent to answer things it's not supposed to, and verify that it refuses to answer.
4. Personality. Simulate an angry, frustrated or manipulative customer, and make sure your assistant handles the situation well.
## Benefits of Chat Testing
* **Speed:** Chat tests execute faster than voice tests, allowing for rapid iteration.
* **Cost-Effective:** No TTS or STT models are used during chat testing.
* **Focused Assessment:** Evaluate pure conversational ability without audio-related variables.
* **Higher Test Volume:** Run more tests in less time to ensure comprehensive coverage.
## Creating Chat Tests
You can create chat tests as part of a Test Suite:
1. Navigate to the **Test** tab and select **Test Suites**.
2. Create a new Test Suite or edit an existing one.
3. When adding tests, select **Chat** as the test type.
4. Define your script and success criteria as detailed in the [Test Suites](./test-suites) documentation.
## Best Practices for Chat Testing
* Use chat tests for rapid iteration during development.
* Create variations of the same scenario to test different user inputs.
* Test edge cases and potential misunderstandings.
For comprehensive instructions on creating and managing test suites that include chat tests, refer to the [Test Suites](./test-suites) documentation.
# Voice Testing
> Automated voice call testing for AI voice agents
## Overview
Voice Test Suites enable you to test your AI voice agents through simulated phone conversations. Our platform connects two AI agents - your voice agent and our testing agent - on a real phone call, following your predefined scripts to evaluate performance under various scenarios.
## How Voice Testing Works
1. **Simulation:** Our AI tester calls your voice agent and follows a script that simulates real customer behavior.
2. **Conversation:** Both AIs engage in a natural voice conversation, with the tester following your script guidelines.
3. **Recording:** The entire call is recorded and transcribed for evaluation.
4. **Assessment:** After the call, the transcript is evaluated against your rubric by a language model (LLM).
## Benefits of Voice Testing
* **Natural Interaction:** Test your voice agent in the most realistic scenario - actual phone calls.
* **Audio Quality Assessment:** Evaluate not just responses but also voice clarity, tone, and cadence.
* **End-to-End Verification:** Confirm that your entire voice pipeline works correctly from telephony to response.
## Creating Voice Tests
You can create voice tests as part of a Test Suite:
1. Navigate to the **Test** tab and select **Test Suites**.
2. Create a new Test Suite or edit an existing one.
3. When adding tests, select **Voice** as the test type.
4. Define your script and success criteria as detailed in the [Test Suites](./test-suites) documentation.
## Voice Test Limitations
* Voice tests require more time to execute compared to chat tests.
* Each test consumes calling minutes from your account.
* Maximum call duration is limited to 15 minutes per test.
For detailed instructions on creating and managing test suites that include voice tests, see the [Test Suites](./test-suites) documentation.
# Creating Free Phone Numbers
> Creating free phone numbers on the Vapi platform.
This guide details how to create free phone numbers on the Vapi platform, which you can use with your assistants or squads.
### Head to the “Phone Numbers” tab in your Vapi dashboard.
### Click on “Create a Phone Number”
### Within the "Free Vapi Number" tab, enter your desired area code
Currently, only US phone numbers can be directly created through Vapi.
### Vapi will automatically allot you a random phone number — free of charge!
It takes a couple of minutes for the phone number to be fully activated. During this period, calls will not be functional.
### Frequently Asked Questions
For now, each wallet can have up to 10 free numbers. This limit ensures we can continue offering reliable, high-quality service to everyone.
Not at this time. You can still bring in global numbers using our phone number import feature.
None at all. We’re simply passing on the cost efficiencies we’ve gained through robust engineering and volume partnerships.
# Import number from Twilio
> Import a new or existing number from Twilio
## Overview
As you scale your agents, you may want to use other telephony providers, like Twilio. In this guide, you'll learn how to add a new or existing Twilio number to Vapi.
## Prerequisites
* [A Twilio account](https://console.twilio.com/)
## Get started
If you don't have a Twilio number, purchase one in your Twilio console's "Buy a number" section.
In your Twilio console, go to "API keys & tokens" to find your Account SID and Auth Token.
1. Go to the "Phone Numbers" section in Vapi and click "Import".
2. Enter your phone number and Twilio credentials, then click "Import".
You can use the number with an assistant for inbound or outbound calls.
# Import number from Telnyx
> Import and use your Telnyx numbers with Vapi
## Overview
This guide shows you how to import your existing Telnyx phone numbers to the Vapi platform and enable outbound calling. Follow the steps below to use your Telnyx numbers with your assistants or squads.
You'll need to have an active Telnyx account with phone numbers that you want to import.
## Configuring outbound calling with Telnyx
To enable outbound calling with your imported Telnyx numbers, configure your Telnyx account:
Go to the [Telnyx Portal](https://portal.telnyx.com/#/outbound-profiles).
Set up or select the outbound voice profile you want to use.
Under the "Connections and Applications" tab, add Vapi as a connection.
Save your configuration to enable outbound calling.
Without this configuration, outbound calling functionality will not work properly with your Telnyx numbers on the Vapi platform.
# SIP introduction
> Make SIP calls to your Vapi assistant
## Overview
This guide shows you how to set up and test SIP calls to your Vapi assistant using any SIP client or softphone. You'll create an assistant, assign it a SIP phone number, and make a call using a SIP URI. You can also pass template variables via SIP headers.
Create an assistant with the `POST /assistant` endpoint. This is the same as creating an assistant for any other transport.
```json
{
"name": "My SIP Assistant",
"firstMessage": "Hello {{first_name}}, you've reached me over SIP."
}
```
Create a SIP phone number with the `POST /phone-number` endpoint.
```json
{
"provider": "vapi",
"sipUri": "sip:your_unique_user_name@sip.vapi.ai",
"assistantId": "your_assistant_id"
}
```
`sipUri` must be in the format `sip:username@sip.vapi.ai`. You can choose any username you like.
Use any SIP softphone (e.g., [Zoiper](https://www.zoiper.com/), [Linphone](https://www.linphone.org/)) to dial your SIP URI (e.g., `sip:your_unique_user_name@sip.vapi.ai`).
The assistant will answer your call. No authentication or SIP registration is required.
To fill template variables, send custom SIP headers with your call.
For example, to fill the `first_name` variable, send a SIP header:
```
x-first_name: John
```
Header names are case-insensitive (e.g., `X-First_Name`, `x-first_name`, and `X-FIRST_NAME` all work).
You can use a custom assistant for SIP calls just like for phone calls.
Set the `assistantId` to `null` and the `serverUrl` to your server, which will respond to the `assistant-request` event.
`PATCH /phone-number/:id`
```json
{
"assistantId": null,
"serverUrl": "https://your_server_url"
}
```
Now, every time you make a call to this phone number, your server will receive an `assistant-request` event.
# SIP Trunking
> How to integrate your SIP provider with Vapi
SIP trunking replaces traditional phone lines with a virtual connection over the internet, allowing your business to make and receive calls via a broadband connection. It connects your internal PBX or VoIP system to a SIP provider, which then routes calls to the Public Switched Telephone Network (PSTN). This setup simplifies your communications infrastructure and often reduces costs.
## Network requirements
To allow SIP signaling and media between Vapi and your SIP provider, you must allowlist the following IP addresses:
* 44.229.228.186/32
* 44.238.177.138/32
* 172.31.9.106/32
These IPs are used exclusively for SIP traffic.
We generally don't recommend IP-based authentication for SIP trunks as it can lead to routing issues. Since our servers are shared by many customers, if your telephony provider has multiple customers using IP-based authentication, calls may be routed incorrectly. IP-based authentication works reliably only when your SIP provider offers a unique termination URI or a dedicated SIP server for each customer, as is the case with Plivo and Twilio integrations.
## Supported SIP providers
Vapi supports multiple SIP trunk configurations, including:
* **Plivo**: Uses a unique SIP domain and supports IP-based authentication.
* **Telnyx**: Uses SIP gateway domain (e.g., sip.telnyx.com) with IP-based authentication.
* **Zadarma**: Uses SIP credentials (username/password) with its SIP server (e.g., sip.zadarma.com).
* **Custom "BYO" SIP Trunk**: Allows integration with any SIP provider. You simply provide the SIP gateway address and the necessary authentication details.
## Setup process
Gather the SIP server address, authentication credentials (username/password or IP-based), and at least one phone number (DID) from your provider.
Use the Vapi API to create a new credential (type: byo-sip-trunk) with your provider's details. This informs Vapi how to connect to your SIP network.
**Example (using Zadarma):**
```bash
curl -X POST "https://api.vapi.ai/credential" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
-d '{
"provider": "byo-sip-trunk",
"name": "Zadarma Trunk",
"gateways": [{
"ip": "sip.zadarma.com"
}],
"outboundLeadingPlusEnabled": true,
"outboundAuthenticationPlan": {
"authUsername": "YOUR_SIP_NUMBER",
"authPassword": "YOUR_SIP_PASSWORD"
}
}'
```
Save the returned Credential ID for later use.
Link your external phone number (DID) to the SIP trunk credential in Vapi by creating a Phone Number resource.
**Example:**
```bash
curl -X POST "https://api.vapi.ai/phone-number" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
-d '{
"provider": "byo-phone-number",
"name": "Zadarma Number",
"number": "15551234567",
"numberE164CheckEnabled": false,
"credentialId": "YOUR_CREDENTIAL_ID"
}'
```
Note the returned Phone Number ID for use in test calls.
Initiate a call through the Vapi dashboard or API to ensure outbound calls are properly routed.
**API Example:**
```json
POST https://api.vapi.ai/call/phone
{
"assistantId": "YOUR_ASSISTANT_ID",
"customer": {
"number": "15557654321",
"numberE164CheckEnabled": false
},
"phoneNumberId": "YOUR_PHONE_NUMBER_ID"
}
```
If inbound routing is configured, call your phone number from an external line. Ensure your provider forwards calls to the correct SIP URI (e.g., `{phoneNumber}@.sip.vapi.ai` for Zadarma).
Note: Please ensure that you provide all the signaling IP addresses when creating the SIP trunk. Failure to do so will prevent proper whitelisting, which may result in encountering unauthorized 401 errors for inbound calls.
If you need to transfer a call to another number, you will need to add a SIP Transfer based call forwarding where the transfer number will look like this: `sip:transfer-number@your-telecom-provider-domain.com`
Example: `sip:15557654321@sip.zadarma.com`
Note: Certain providers require phone numbers to be formatted in the proper E.164 standard. For example, the transfer URI should appear as: `sip:+15557654321@sip.zadarma.com`.
Example tool configuration required for SIP REFER:
```json
{
"type": "transferCall",
"destinations": [
{
"type": "sip",
"sipUri": "sip:14039932200@sip.telnyx.com"
}
]
}
```
You might need to enable SIP REFER in your SIP provider to allow this.
# Twilio SIP Integration
> How to integrate Twilio SIP with Vapi
This guide walks you through setting up both outbound and inbound SIP trunking between Twilio and Vapi. The steps are quite similar for other telephony providers.
## Outbound Calls (Twilio to Vapi)
### Twilio Configuration
1. **Create Elastic SIP Trunk**
Log in to your Twilio account and create a new trunk, assigning it a name, and adjusting the general settings as needed.
2. **Set Up Termination (Outbound Calls)**
Configure the termination settings. The termination SIP URI is crucial as it will be used in later steps.
To allow your Elastic SIP Trunk to accept outbound requests, you need to whitelist IP addresses:
Whitelist Vapi's SIP server static IPs:
* 44.229.228.186
* 44.238.177.138
Ensure you whitelist the entire IP range as shown below:
3. **Purchase or Move Numbers to Elastic SIP Trunk**
After creating the Elastic SIP trunk, purchase new numbers or move existing numbers to this trunk.
### Vapi Configuration
1. **Retrieve Your Vapi API Key**
Log in to your Vapi.ai account and retrieve your API key from the Organization Settings.
2. **Create a SIP Trunk Credential**
Use the following API call to create a SIP trunk credential, replacing the gateway IP with your Twilio Termination SIP URI:
```bash
curl -X POST https://api.vapi.ai/credential \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-d '{
"provider": "byo-sip-trunk",
"name": "Twilio Trunk",
"gateways": [
{
"ip": "YOUR_TWILIO_GATEWAY_ID"
}
],
"outboundLeadingPlusEnabled": true
}'
```
Note the `id` (credentialId) from the response for the next step.
3. **Register Your Phone Number**
Associate your Twilio number with the SIP trunk:
```bash
curl -X POST https://api.vapi.ai/phone-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-d '{
"provider": "byo-phone-number",
"name": "Twilio SIP Number",
"number": "YOUR_SIP_PHONE_NUMBER",
"numberE164CheckEnabled": false,
"credentialId": "YOUR_CREDENTIAL_ID"
}'
```
Note the phone number ID from the response for making calls.
4. **Make Outbound Calls**
You can make outbound calls in two ways:
**Using the Vapi Dashboard:**
The phone number will appear in your dashboard. Select your assistant and enter the destination number you want to call.
**Using the API:**
```bash
curl --location 'https://api.vapi.ai/call/phone' \
--header 'Authorization: Bearer YOUR_VAPI_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"assistantId": "YOUR_ASSISTANT_ID",
"customer": {
"number": "DESTINATION_PHONE_NUMBER",
"numberE164CheckEnabled": false
},
"phoneNumberId": "YOUR_PHONE_NUMBER_ID"
}'
```
## Inbound Calls (Vapi to Twilio)
### Twilio Configuration
1. **Set Up Origination (Inbound Calls)**
Navigate to the Origination section in your Twilio SIP Trunk settings.
Add your Vapi SIP URI in the following format: `sip:YOUR_PHONE_NUMBER@sip.vapi.ai`, where "YOUR\_PHONE\_NUMBER" is your chosen SIP number that you will attach to this trunk.
### Vapi Configuration
1. **Create and Configure a Vapi Assistant**
* Create an assistant following the steps in our [Phone Quickstart](/quickstart/phone#create-your-first-voice-assistant)
* In the assistant settings, link it to the phone number you created
Now when someone calls your Twilio number, the call will be routed to your Vapi assistant.
# Telnyx SIP integration
> How to integrate SIP Telnyx to Vapi
Integrate your Telnyx SIP trunk with Vapi to enable your AI voice assistants to handle calls efficiently. This guide walks you through the complete setup process for both inbound and outbound calls.
* Log in to your Vapi account
* Navigate to **Organization Settings**
* In the **API Keys** section, copy your **Private Key**
* Go to Voice / SIP Trunking / Create
* Select FQDN
* Click "Add FQDN"
* Select A record type
* Set FQDN to: `sip.vapi.ai`
* Port should be 5060 by default
* Navigate to the Inbound tab of your SIP trunk
* Configure settings as shown:
* Go to the Numbers tab
* Assign your acquired phone number to the SIP trunk
* Go to Numbers, edit the number you'll be using
* Navigate to Voice settings
* Scroll down to find "Translated Number"
* Set this value to match your Vapi SIP URI
You can get your Vapi SIP URI when you create a new SIP number through the **Phone Numbers** tab in the Vapi dashboard. The URI will look like:
sip:@sip.vapi.ai
*This setting modifies the SIP Invite so invites are correctly routed to your Vapi SIP URI.*
* Go to Voice / SIP Trunking / Authentication and routing
* Scroll down to "Outbound calls authentication"
* Create a new credential for Vapi to use
* Go to Voice / Outbound Voice Profiles
* Create a new profile
* Name it appropriately
* Configure desired destinations
* Leave default configuration settings
* Assign your SIP trunk
* Complete setup
Alternatively, go to your SIP trunk / Outbound tab and select your newly created outbound voice profile.
* Choose the country you'll be making most calls to
*We recommend creating a separate SIP Trunk for each country you aim to be making most calls to.*
Use the Vapi API to create a SIP trunk credential:
```bash
curl -X POST https://api.vapi.ai/credential \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
-d '{
"provider": "byo-sip-trunk",
"name": "Telnyx Trunk",
"gateways": [
{
"ip": "sip.telnyx.com"
}
],
"outboundAuthenticationPlan": {
"authUsername": "YOUR_SIP_USERNAME",
"authPassword": "YOUR_SIP_PASSWORD",
"sipRegisterPlan": {
"realm": "sip.telnyx.com"
}
}
}'
```
Replace `YOUR_VAPI_PRIVATE_KEY`, `YOUR_SIP_USERNAME`, and `YOUR_SIP_PASSWORD` with your actual credentials.
If successful, the response will include an `id` for the created credential, which you'll use in the next step.
Associate your phone number with the SIP trunk in Vapi:
```bash
curl -X POST https://api.vapi.ai/phone-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
-d '{
"provider": "byo-phone-number",
"name": "Telnyx SIP Number",
"number": "YOUR_PHONE_NUMBER",
"numberE164CheckEnabled": false,
"credentialId": "YOUR_CREDENTIAL_ID"
}'
```
Replace `YOUR_VAPI_PRIVATE_KEY`, `YOUR_PHONE_NUMBER`, and `YOUR_CREDENTIAL_ID` with your actual details.
* In your Vapi dashboard, go to the **Build** section and select **Phone Numbers**
* Click on your **Telnyx Number**
* In the **Inbound Settings** section, assign your voice assistant to handle incoming calls
* In the **Outbound Form** section, assign your voice assistant to handle outgoing calls
To initiate outbound calls through your Telnyx SIP trunk:
```bash
curl --location 'https://api.vapi.ai/call/phone' \
--header 'Authorization: Bearer YOUR_VAPI_PRIVATE_KEY' \
--header 'Content-Type: application/json' \
--data '{
"assistantId": "YOUR_ASSISTANT_ID",
"customer": {
"number": "CUSTOMER_PHONE_NUMBER",
"numberE164CheckEnabled": false
},
"phoneNumberId": "YOUR_PHONE_ID"
}'
```
Replace all placeholder values with your actual information.
By following these steps, your Telnyx SIP trunk will be fully integrated with Vapi, allowing your AI voice assistants to manage calls effectively.
# Zadarma SIP Integration
> How to integrate SIP Zadarma to Vapi
Integrate your Zadarma SIP trunk with Vapi.ai to enable your AI voice assistants to handle calls efficiently. Follow the steps below to set up this integration:
## 1. Retrieve Your Vapi.ai Private Key
* Log in to your Vapi.ai account.
* Navigate to **Organization Settings**.
* In the **API Keys** section, copy your **Private Key**.
## 2. Add Your Zadarma SIP Credentials to Vapi.ai
You'll need to send a `curl` request to Vapi.ai's API to add your SIP credentials:
* **Private Key**: Your Vapi.ai private key.
* **Trunk Name**: A name for your SIP trunk (e.g., "Zadarma Trunk").
* **Server Address**: The server address provided by Zadarma (e.g., "sip.zadarma.com").
* **SIP Number**: Your Zadarma SIP number.
* **SIP Password**: The password for your Zadarma SIP number.
Here's the `curl` command to execute:
```bash
curl -L 'https://api.vapi.ai/credential' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_PRIVATE_KEY' \\
-d '{
"provider": "byo-sip-trunk",
"name": "Zadarma Trunk",
"gateways": [
{ "ip": "sip.zadarma.com" }
],
"outboundLeadingPlusEnabled": true,
"outboundAuthenticationPlan": {
"authUsername": "YOUR_SIP_NUMBER",
"authPassword": "YOUR_SIP_PASSWORD"
}
}'
```
Replace `YOUR_PRIVATE_KEY`, `YOUR_SIP_NUMBER`, and `YOUR_SIP_PASSWORD` with your actual credentials.
If successful, the response will include an `id` for the created credential, which you'll use in the next step.
## 3. Add Your Virtual Number to Vapi.ai
Next, associate your virtual number with the SIP trunk in Vapi.ai:
* **Private Key**: Your Vapi.ai private key.
* **Number Name**: A name for your virtual number (e.g., "Zadarma Number").
* **Virtual Number**: Your Zadarma virtual number in international format (e.g., "15551111111").
* **Credential ID**: The `id` from the previous step.
Use the following `curl` command:
```bash
curl -L 'https://api.vapi.ai/phone-number' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_PRIVATE_KEY' \\
-d '{
"provider": "byo-phone-number",
"name": "Zadarma Number",
"number": "YOUR_VIRTUAL_NUMBER",
"numberE164CheckEnabled": false,
"credentialId": "YOUR_CREDENTIAL_ID"
}'
```
Replace `YOUR_PRIVATE_KEY`, `YOUR_VIRTUAL_NUMBER`, and `YOUR_CREDENTIAL_ID` with your actual details.
## 4. Assign Your Voice Assistant to Handle Calls
* In your Vapi.ai dashboard, go to the **Build** section and select **Phone Numbers**.
* Click on your **Zadarma Number**.
* In the **Inbound Settings** section, assign your voice assistant to handle incoming calls.
* In the **Outbound Form** section, assign your voice assistant to handle outgoing calls.
## 5. Configure Incoming Call Reception in Zadarma
To forward incoming calls from your Zadarma virtual number to Vapi.ai:
* Log in to your Zadarma account.
* Navigate to **Settings** → **Virtual phone numbers**.
* Click the ⚙ (gear) icon next to your number.
* Open the **External server** tab.
* Enable **External server (SIP URI)**.
* Enter the address: `YOUR_VIRTUAL_NUMBER@sip.vapi.ai` (replace `YOUR_VIRTUAL_NUMBER` with your number in international format).
* Click **Save**.
By following these steps, your Zadarma SIP trunk will be integrated with Vapi.ai, allowing your AI voice assistants to manage calls effectively.
# Plivo SIP Integration
> Learn to connect your Plivo SIP trunk to Vapi for inbound and outbound calls
## Overview
For a general introduction to SIP trunking with Vapi (concepts and architecture), see our [SIP Trunking Guide](../sip-trunk.mdx).
This guide shows you how to connect your Plivo SIP trunk to your existing Vapi agents. It covers:
* Step-by-step configuration of Plivo and Vapi for SIP trunking (outbound and inbound)
* How to register and associate your Plivo phone numbers with Vapi
* How to make outbound calls using the Vapi API and dashboard
* How to assign Plivo numbers for inbound call routing through Vapi
## Prerequisites
* [A Plivo account](https://console.plivo.com/accounts/request-trial/)
* Admin access to your Plivo and PBX/SIP trunk configuration
* A phone number you want to connect to Vapi via Plivo
Indian phone numbers cannot be used with Plivo on Vapi due to TRAI regulations. These regulations require SIP termination to occur via an Indian server, which Vapi does not currently support.
## Get Started
## Plivo Configuration
Access the Plivo console.
1. **Navigate to:**
`Zentrunk (SIP) → Outbound Trunks → IP Access Control List → Create New IP Group`
2. **Fill out the form:**
* **Name:** Enter a descriptive name (for example, `VAPI-IP-Group`).
* **IP Address List:** Add each of the following IP addresses one at a time:
```
44.229.228.186/32
```
```
44.238.177.138/32
```
3. **Click** **Create ACL** to save.
1. **Navigate to:**
`Zentrunk (SIP) → Outbound Trunks → Trunks → Create New Outbound Trunk`
2. **Fill out the form:**
* **Trunk Name:** Enter a descriptive name (for example, `Vapi-Outbound-Trunk`).
* **IP Access Control List:** Select the IP ACL created in the previous step.
3. **Click** **Create Trunk** to save.
After creating the trunk, locate the **Termination SIP Domain** in the trunk details page. It will look something like:
`12700668357XXXXXX.zt.plivo.com`
**You will need this value when configuring your SIP trunk in Vapi.**
Navigate to:
`Numbers → Buy a new number`
Once purchased, note down your new phone number. You will associate this number with your SIP trunk in a later step.
## Vapi Configuration
Sign in to the dashboard and [get your API key](https://dashboard.vapi.ai/org/api-keys).
1. Copy the following API call.
2. Replace `YOUR_PLIVO_TERMINATION_SIP_DOMAIN` with your actual Plivo Termination SIP Domain (for example, `12700668357XXXXXX.zt.plivo.com`).
```bash
curl -X POST https://api.vapi.ai/credential \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_API_KEY" \
-d '{
"provider": "byo-sip-trunk",
"name": "PLIVO Trunk",
"gateways": [
{
"ip": "YOUR_PLIVO_TERMINATION_SIP_DOMAIN"
}
]
}'
```
3. You'll receive a response like the one below. Note the `id` (credentialId) for the next step.
```json
{
"id": "d293b924-f68d-4cbc-850f-xxxxxxxxxxxxxxx",
"orgId": "424acf80-dbea-4015-ace8-0f3924e6000xxxx",
"provider": "byo-sip-trunk",
"createdAt": "2025-05-05T16:38:08.815Z",
"updatedAt": "2025-05-05T16:38:08.815Z",
"gateways": [
{
"ip": "1856282236xxxxxxxxxxx.zt.plivo.com"
}
],
"name": "PLIVO Trunk"
}
```
1. Associate your Plivo number with the SIP trunk. Replace `YOUR_PLIVO_PHONE_NUMBER` and `YOUR_CREDENTIAL_ID` with the numbers from previous steps.
```bash
curl -X POST https://api.vapi.ai/phone-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_API_KEY" \
-d '{
"provider": "byo-phone-number",
"name": "PLIVO SIP Number",
"number": "YOUR_PLIVO_PHONE_NUMBER",
"numberE164CheckEnabled": false,
"credentialId": "YOUR_CREDENTIAL_ID"
}'
```
2. Your response will look like this, note the phone number ID from the response for making calls.
```bash
{
"id": "eba2fb13-259f-4123-abfa-xxxxxxxxxxxxxxx",
"orgId": "489ea344-c56f-4243-8723-b28362cd5a5c",
"number": "1833684XXXX",
"createdAt": "2025-03-05T18:31:30.389Z",
"updatedAt": "2025-03-05T18:31:30.389Z",
"name": "PLIVO SIP Number",
"credentialId": "a2c815b8-03f4-40f5-813c-xxxxxxxxxxxx",
"provider": "byo-phone-number",
"numberE164CheckEnabled": false,
"status": "active"
}
```
1. [Follow this guide to create an assistant](/quickstart/phone#create-your-first-voice-assistant)
2. Note your Assistant ID for making calls.
[**Using the API**](/calls/outbound-calling)
```bash
curl --location 'https://api.vapi.ai/call/phone' \
--header 'Authorization: Bearer YOUR_VAPI_PRIVATE_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"assistantId": "29d47d31-ba3c-451c-86ce-xxxxxxxxx",
"customer": {
"number": "9199437XXXXX",
"numberE164CheckEnabled": false
},
"phoneNumberId": "eba2fb13-259f-4123-abfa-xxxxxxxxxxx"
}'
```
[**Using the Vapi Dashboard**](/quickstart/phone#try-outbound-calling)
1. Select your Assistant
2. Enter the phone number of the user you want to call
## Plivo Configuration
Access the Plivo console.
1. **Navigate to:**
`Zentrunk (SIP) → Inbound Trunks → Origination URI → Create New IP URI`
2. **Fill out the form:**
* **Name:** Enter a descriptive name (for example, `Vapi Inbound`).
* **URI:** Enter this origination URI exactly: `sip.vapi.ai;transport=udp`
3. **Click** **Create URI** to save.
1. **Navigate to:**
`Zentrunk (SIP) → Inbound Trunks → Trunks → Create New Inbound Trunk`
2. **Fill out the form:**
* **Trunk Name:** Enter a descriptive name (for example, `Vapi Inbound Trunk`).
* **Primary URI:** Select the URI created in the previous step.
3. **Click** **Create Trunk** to save.
1. **Navigate to:**
`Phone Numbers → Select your purchased number`
2. **Configure the number:**
* In the **Application** dropdown, select **Zentrunk**.
* In the **Zentrunk** dropdown, select your inbound trunk.
3. **Click** **Save** to apply changes.
## Vapi Configuration
Sign into the dashboard and [get your api key](https://dashboard.vapi.ai/org/api-keys).
```bash
curl -X POST https://api.vapi.ai/credential \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_API_KEY" \
-d '{
"provider": "byo-sip-trunk",
"name": "PLIVO Inbound Trunk",
"type": "inbound"
}'
```
Note the `id` (credentialId) from the response for the next step.
```bash
curl -X POST https://api.vapi.ai/phone-number \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_API_KEY" \
-d '{
"provider": "byo-phone-number",
"name": "PLIVO SIP Inbound Number",
"number": "1833684XXXX",
"numberE164CheckEnabled": false,
"credentialId": "a2c815b8-03f4-40f5-813c-xxxxxxxxxxxx"
}'
```
## Errors
* **Codec Support:** Limit trunk codecs to G.711 µ‑law and A‑law only. Other codecs are not supported by Plivo SIP trunks.
* **SIP REFER Not Supported:** Plivo SIP trunks do not accept SIP REFER for call transfers.
* **Origination URI Already Exists:** This was previously an error on Plivo's side and has been fixed.
# Phone Number Hooks
## Overview
Phone number hooks allow you to configure actions that will be performed when specific events occur during a call. Currently, hooks support the `call.ringing` event (which is triggered when a call is ringing).
## Usage
Hooks are defined in the `hooks` array of a phone number. Each hook consists of:
* `on`: The event that triggers the hook (supports `call.ringing`)
* `do`: The actions to perform when the hook triggers (supports `transfer` and `say`)
## Example: Say Message on Call Ringing
This example shows how to play a message when a call is ringing:
```bash
curl -X PATCH "https://api.vapi.ai/phone-number/" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"hooks": [{
"on": "call.ringing",
"do": [{
"type": "say",
"exact": "inbound calling is disabled."
}]
}]
}'
```
## Example: Transfer on Call Ringing
This example shows how to transfer a call when it starts ringing:
```bash
curl -X PATCH "https://api.vapi.ai/phone-number/" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"hooks": [{
"on": "call.ringing",
"do": [{
"type": "transfer",
"destination": {
"type": "number",
"number": "+1234567890",
"callerId": "+1987654321"
}
}]
}]
}'
```
You can also transfer to a SIP destination:
```bash
curl -X PATCH "https://api.vapi.ai/phone-number/" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"hooks": [{
"on": "call.ringing",
"do": [{
"type": "transfer",
"destination": {
"type": "sip",
"sipUri": "sip:user@domain.com"
}
}]
}]
}'
```
Common use cases for phone number hooks include:
* Disabling inbound calling by playing a message or transferring
# Phone Calling
> Learn how to create and configure phone numbers with Vapi
## Overview
Free Vapi phone numbers are only available for US national use. International numbers are not free, and you can only create up to 10 free numbers per account.
You can create and configure phone numbers with Vapi to place and receive calls. Vapi provides free phone numbers for national (US) use only—international numbers are not free. For international or custom use, you can import your own numbers from Twilio.
## Setting up a phone number
You can set up a phone number to place and receive calls in two ways:
* **Create a free US phone number:**
* Use the Vapi dashboard or the [`/phone-numbers`](/api-reference/phone-numbers/create) endpoint.
* Free numbers are only available for US national use.
* **Import your own number (for international or custom use):**
* Use the dashboard or the [`/phone-numbers/import`](/api-reference/phone-numbers/import-twilio-number) endpoint.
* This uses your Twilio credentials to verify and configure the number with Vapi services.
## Outbound calls
You can place an outbound call from one of your phone numbers using the [`/call`](/api-reference/calls/create-phone-call) endpoint.
* If the system message will be different with every call, specify a temporary assistant in the `assistant` field.
* To reuse an assistant, specify its ID in the `assistantId` field.
* [Read more about outbound calls](/phone-calling/outbound-calls)
## Inbound calls
You can provide an `assistantId` to a phone number, and it will use that assistant for inbound calls.
* To specify the assistant based on the caller's phone number, leave the `assistantId` blank. Vapi will attempt to retrieve the assistant from your server using your [Server URL](/server-url#retrieving-assistants).
## Video tutorial: Importing numbers from Twilio for international calls
# Outbound Calling
> Learn how to send outbound calls from Vapi.
## Introduction to Outbound Calling
Vapi's outbound calling API lets you programmatically initiate single or batch calls to any phone number. You can schedule calls for specific dates and times, ideal for time-sensitive communications. Easily integrate outbound calling into your app for appointment reminders, automated surveys, and call campaigns.
## Prerequisites
* **Vapi Account**: Access to the Vapi Dashboard for configuration.
* **Configured Assistant**: Either a saved assistant or a transient assistant.
* **Phone Number**: Either an imported phone number from one of the supported providers or a free Vapi number. (Note: You cannot make international calls with a free Vapi number).
* **Customer's Phone Number**: The phone number that you want to call.
## Outbound Calls
You can place an outbound call from one of your phone numbers using the [`/call`](/api-reference/calls/create-phone-call) endpoint.
1. **Specify an Assistant:** you must specify either a transient assistant in the `assistant` field or reuse a saved assistant in the `assistantId` field.
2. **Get a Phone Number:** provide the `phoneNumberId` of the imported number or free Vapi number you wish to call from.
3. **Provide a Destination:** Finally, pass the customer's phone number or SIP URI in [`customer`](/api-reference/calls/create#request.body.customer).
Provide your authorization token and now we're ready to issue the API call!
```jsx
{
"assistantId": "assistant-id",
"phoneNumberId": "phone-number-id",
"customer": {
"number": "+11231231234"
}
}
```
## Scheduling Outbound Calls
To schedule a call for the future, use the [`schedulePlan`](/api-reference/calls/create#request.body.schedulePlan) parameter and pass a future ISO date-time string to `earliestAt`. This will be the earliest time Vapi will attempt to trigger the outbound call. You may also provider `latestAt`, which will be the latest time Vapi will attempt to trigger the call.
When you schedule a call, we will save the Assistant, Phone Number, and Customer Number resources and refetch them at the time of the call. If you choose to provide a saved assistant through `assistantId`, we will pick up the most up-to-date version of your assistant at the call time. Likewise, if you delete your saved assistant, the call will fail! To ensure the call is issued with a static version of an assistant, pass it as a transient assistant through the `assistant` parameter.
```jsx
{
"assistantId": "assistant-id",
"phoneNumberId": "phone-number-id",
"customer": {
"number": "+11231231234"
},
"schedulePlan": {
"earliestAt": "2025-05-30T00:00:00Z"
}
}
```
## Batch Calling \[#batch-calling]
To call more than one number at a time, use the [`customers`](/api-reference/calls/create#request.body.customers) parameter to pass an array of `customer`. To provide customer specific assistant overrides, please call the endpoint separately for each destination number.
Use both `customers` and `schedulePlan` together to schedule batched calls.
```jsx
{
"assistantId": "assistant-id",
"phoneNumberId": "phone-number-id",
"customers": [
{
"number": "+11231231234"
},
{
"number": "+12342342345"
}
],
"schedulePlan": {
"earliestAt": "2025-05-30T00:00:00Z"
}
}
```
## Creating Outboud Calls from the Dashboard
Learn more about how to launch [Outbound Calling Campaigns via Dashboard](/outbound-campaigns/quickstart)
## Trusted Calling and Caller ID
To maximize call answer rates and establish trust with recipients, you should implement proper caller identification and trusted calling standards. This involves several key components that work together to verify your identity and build caller reputation.
### STIR/SHAKEN Implementation
**STIR/SHAKEN** (Secure Telephone Identity Revisited / Signature-based Handling of Asserted Information using toKENs) is a framework designed to combat robocalls and caller ID spoofing by digitally signing calls to verify the caller's identity.
When you make outbound calls, STIR/SHAKEN provides three levels of attestation:
* **Level A (Full Attestation)**: The service provider has verified both the caller's identity and their right to use the calling number
* **Level B (Partial Attestation)**: The service provider has verified the caller's identity but not their right to use the number
* **Level C (Gateway Attestation)**: The service provider has authenticated the call source but cannot verify the caller's identity
To enable STIR/SHAKEN on your Twilio numbers:
1. **Complete Trust Hub verification** in your Twilio Console
2. **Submit business information** including legal business name, address, and authorized representative details
3. **Provide supporting documentation** such as business registration and tax identification
4. **Wait for approval** - the verification process typically takes 5-7 business days
STIR/SHAKEN is currently required for US and Canadian calling. Implementation helps ensure your calls are properly authenticated and less likely to be flagged as spam.
Learn more: [Twilio STIR/SHAKEN Documentation](https://www.twilio.com/docs/voice/trusted-calling-with-shakenstir)
### CNAM Registry Registration
**CNAM** (Caller Name) displays your business name instead of just your phone number when you call someone. This significantly improves answer rates and establishes professional credibility.
To register your business name with the CNAM database through your phone number provider:
Navigate to your phone number provider's CNAM registration portal (e.g., Twilio Console → Phone Numbers → Manage → Caller ID)
Provide your complete business information:
* **Legal business name** (exactly as registered with your EIN)
* **Business address** and contact information
* **Business type** and industry classification
* **Tax identification number** or business registration details
Assign a point of contact with authority to make changes:
* Full name and business title
* Direct phone number and email address
* Verification that they're authorized to represent the business
Submit your application for review. Processing typically takes 3-5 business days, and you'll receive confirmation once approved.
Use an email address associated with your business domain rather than personal email addresses to expedite the approval process.
Learn more: [Twilio CNAM Branding Guide](https://www.twilio.com/docs/voice/brand-your-calls-using-cnam)
### Caller Reputation Databases
Beyond CNAM registration, registering with major caller reputation databases helps establish trust and reduces the likelihood of your calls being flagged as spam or blocked.
#### First Orion Registration
[First Orion](https://firstorion.com/) provides caller identification and spam protection services used by major carriers and call-blocking apps.
**Registration benefits:**
* Displays your business name and logo on supported devices
* Reduces spam flagging and call blocking
* Provides branded calling experience
**Registration process:**
1. Visit the First Orion business portal
2. Verify your business ownership of the phone numbers
3. Submit branding assets (logo, business description)
4. Complete the verification process
#### Hiya (Free Caller Registry)
[Hiya](https://www.hiya.com/) operates one of the largest caller ID and spam protection networks, powering caller identification for millions of users.
**Benefits of Hiya registration:**
* Enhanced caller ID display across multiple platforms
* Protection against false spam reporting
* Access to call analytics and reputation monitoring
**Registration steps:**
1. Create a business account on Hiya's platform
2. Verify ownership of your phone numbers
3. Submit business profile and branding information
4. Monitor your caller reputation through their dashboard
### Spam Monitoring and Phone Number Health
Proactive monitoring of your phone number reputation is essential to maintain high answer rates and prevent spam labeling. Several tools and services can help you track and remediate spam labels before they impact your campaigns.
#### Twilio Voice Integrity
[Twilio Voice Integrity](https://www.twilio.com/docs/voice/spam-monitoring-with-voiceintegrity) helps remediate spam labels on your phone numbers and monitor their reputation across major carrier networks.
**What Voice Integrity provides:**
* **Spam label remediation** for T-Mobile, Sprint, and AT\&T networks
* **Reputation monitoring** across carrier analytic engines
* **Automatic registration** of your Twilio phone numbers with carrier databases
* **Integration with Trust Hub** for streamlined verification
**Getting started with Voice Integrity:**
* Ensure you have an approved Primary Customer Profile in Trust Hub
* For ISVs: obtain approved secondary customer profiles for tenants
* Access Voice Integrity through your Twilio Console
* Complete the registration process via Trust Hub REST API or console
* Your numbers will be automatically registered with carrier analytic engines
* Voice Integrity will automatically work to remediate spam labels
* Future updates will include reputation monitoring and degradation alerts
* Verizon Wireless integration coming soon (automatic for existing users)
Voice Integrity works best when combined with STIR/SHAKEN attestation, as the highest level of attestation signals to analytic engines that you're a legitimate caller.
#### External Phone Number Health Monitoring
In addition to carrier-provided services, external monitoring APIs can help you proactively check your phone number reputation across different networks and spam databases.
**Recommended monitoring services:**
**IPQualityScore Phone Number Validation**
* **Service**: [IPQualityScore](https://www.ipqualityscore.com/) provides comprehensive phone number reputation scoring
* **Features**: Real-time spam risk assessment, carrier identification, line type detection
* **Use case**: Check numbers before campaigns and monitor reputation changes
* **Integration**: REST API for batch checking or real-time validation
**Nomorobo Spam Database**
* **Service**: [Nomorobo](https://www.nomorobo.com/) maintains one of the largest spam phone number databases
* **Features**: Spam reputation lookup, robocall identification, carrier reporting
* **Use case**: Verify if your numbers are flagged in spam databases
* **Integration**: API access for reputation checking
### Best Practices for Trusted Calling
Use the same business name across all registrations (CNAM, First Orion, Hiya) to avoid confusion
Regularly check your caller reputation scores and address any spam reports promptly
Ensure all outbound calls comply with TCPA regulations and obtain proper consent before calling
Keep your business information current across all platforms when details change
Proper caller identification setup can take 2-4 weeks to fully propagate across all networks and databases. Plan accordingly when launching new outbound calling campaigns.
Note: Vapi free numbers have limited number of outbound calls per day. Import a number from Twilio, Vonage, or Telnyx to scale without limits.
It is a violation of FCC law to dial phone numbers without consent in an
automated manner. See our [TCPA Consent Guide](/tcpa-consent) and the [Telemarketing Sales
Rule](/glossary#telemarketing-sales-rule) to learn more.
# WebSocket Transport
> Stream audio directly via WebSockets for real-time, bidirectional communication
# WebSocket Transport
Vapi's WebSocket transport enables real-time, bidirectional audio communication directly between your application and Vapi's AI assistants. Unlike traditional phone or web calls, this transport method lets you stream raw audio data instantly with minimal latency.
## Key Benefits
* **Low Latency**: Direct streaming ensures minimal delays.
* **Bidirectional Streaming**: Real-time audio flow in both directions.
* **Easy Integration**: Compatible with any environment supporting WebSockets.
* **Flexible Audio Formats**: Customize audio parameters such as sample rate.
* **Automatic Sample Rate Conversion**: Seamlessly handles various audio rates.
## Creating a WebSocket Call
To initiate a call using WebSocket transport:
```bash
curl 'https://api.vapi.ai/call' \
-H 'authorization: Bearer YOUR_API_KEY' \
-H 'content-type: application/json' \
--data-raw '{
"assistantId": "YOUR_ASSISTANT_ID",
"transport": {
"provider": "vapi.websocket",
"audioFormat": {
"format": "pcm_s16le",
"container": "raw",
"sampleRate": 16000
}
}
}'
```
### Sample API Response
```json
{
"id": "7420f27a-30fd-4f49-a995-5549ae7cc00d",
"assistantId": "5b0a4a08-133c-4146-9315-0984f8c6be80",
"type": "vapi.websocketCall",
"createdAt": "2024-09-10T11:14:12.339Z",
"updatedAt": "2024-09-10T11:14:12.339Z",
"orgId": "eb166faa-7145-46ef-8044-589b47ae3b56",
"cost": 0,
"status": "queued",
"transport": {
"provider": "vapi.websocket",
"websocketCallUrl": "wss://api.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/transport"
}
}
```
## Audio Format Configuration
When creating a WebSocket call, the audio format can be customized:
| Parameter | Description | Default |
| ------------ | ---------------------- | ------------------------ |
| `format` | Audio encoding format | `pcm_s16le` (16-bit PCM) |
| `container` | Audio container format | `raw` (Raw PCM) |
| `sampleRate` | Sample rate in Hz | `16000` (16kHz) |
Currently, Vapi supports only raw PCM (`pcm_s16le` with `raw` container). Additional formats may be supported in future updates.
Vapi automatically converts sample rates as needed. You can stream audio at 8kHz, 44.1kHz, etc., and Vapi will handle conversions seamlessly.
## Connecting to the WebSocket
Use the WebSocket URL from the response to establish a connection:
```javascript
const socket = new WebSocket("wss://api.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/transport");
socket.onopen = () => console.log("WebSocket connection opened.");
socket.onclose = () => console.log("WebSocket connection closed.");
socket.onerror = (error) => console.error("WebSocket error:", error);
```
## Sending and Receiving Data
The WebSocket supports two types of messages:
* **Binary audio data** (PCM, 16-bit signed little-endian)
* **Text-based JSON control messages**
### Sending Audio Data
```javascript
function sendAudioChunk(audioBuffer) {
if (socket.readyState === WebSocket.OPEN) {
socket.send(audioBuffer);
}
}
navigator.mediaDevices.getUserMedia({ audio: true }).then(stream => {
const audioContext = new AudioContext();
const source = audioContext.createMediaStreamSource(stream);
const processor = audioContext.createScriptProcessor(1024, 1, 1);
processor.onaudioprocess = (event) => {
const pcmData = event.inputBuffer.getChannelData(0);
const int16Data = new Int16Array(pcmData.length);
for (let i = 0; i < pcmData.length; i++) {
int16Data[i] = Math.max(-32768, Math.min(32767, pcmData[i] * 32768));
}
sendAudioChunk(int16Data.buffer);
};
source.connect(processor);
processor.connect(audioContext.destination);
});
```
### Receiving Data
```javascript
socket.onmessage = (event) => {
if (event.data instanceof Blob) {
event.data.arrayBuffer().then(buffer => {
const audioData = new Int16Array(buffer);
playAudio(audioData);
});
} else {
try {
const message = JSON.parse(event.data);
handleControlMessage(message);
} catch (error) {
console.error("Failed to parse message:", error);
}
}
};
```
### Sending Control Messages
```javascript
function sendControlMessage(messageObj) {
if (socket.readyState === WebSocket.OPEN) {
socket.send(JSON.stringify(messageObj));
}
}
// Example: hangup call
function hangupCall() {
sendControlMessage({ type: "hangup" });
}
```
## Ending the Call
To gracefully end the WebSocket call:
```javascript
sendControlMessage({ type: "hangup" });
socket.close();
```
## Comparison: WebSocket Transport vs. Call Listen Feature
Vapi provides two WebSocket options:
| WebSocket Transport | Call Listen Feature |
| --------------------------------- | ---------------------------------- |
| Primary communication method | Secondary, monitoring-only channel |
| Bidirectional audio streaming | Unidirectional (listen-only) |
| Replaces phone/web as transport | Supplements existing calls |
| Uses `provider: "vapi.websocket"` | Accessed via `monitor.listenUrl` |
Refer to [Live Call Control](/calls/call-features) for more on the Call Listen feature.
When using WebSocket transport, phone-based parameters (`phoneNumber` or `phoneNumberId`) are not permitted. These methods are mutually exclusive.
# Live Call Control
Vapi offers two main features that provide enhanced control over live calls:
1. **Call Control**: This feature allows you to inject conversation elements dynamically during an ongoing call.
2. **Call Listen**: This feature enables real-time audio data streaming using WebSocket connections.
To use these features, you first need to obtain the URLs specific to the live call. These URLs can be retrieved by triggering a `/call` endpoint, which returns the `listenUrl` and `controlUrl` within the `monitor` object.
## Obtaining URLs for Call Control and Listen
To initiate a call and retrieve the `listenUrl` and `controlUrl`, send a POST request to the `/call` endpoint.
### Sample Request
```bash
curl 'https://api.vapi.ai/call'
-H 'authorization: Bearer YOUR_API_KEY'
-H 'content-type: application/json'
--data-raw '{
"assistantId": "5b0a4a08-133c-4146-9315-0984f8c6be80",
"customer": {
"number": "+12345678913"
},
"phoneNumberId": "42b4b25d-031e-4786-857f-63b346c9580f"
}'
```
### Sample Response
```json
{
"id": "7420f27a-30fd-4f49-a995-5549ae7cc00d",
"assistantId": "5b0a4a08-133c-4146-9315-0984f8c6be80",
"phoneNumberId": "42b4b25d-031e-4786-857f-63b346c9580f",
"type": "outboundPhoneCall",
"createdAt": "2024-09-10T11:14:12.339Z",
"updatedAt": "2024-09-10T11:14:12.339Z",
"orgId": "eb166faa-7145-46ef-8044-589b47ae3b56",
"cost": 0,
"customer": {
"number": "+12345678913"
},
"status": "queued",
"phoneCallProvider": "twilio",
"phoneCallProviderId": "CA4c6793d069ef42f4ccad69a0957451ec",
"phoneCallTransport": "pstn",
"monitor": {
"listenUrl": "wss://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/transport",
"controlUrl": ""
}
}
```
## Call Control Features
Once you have the `controlUrl`, you can use various control features during a live call. Here are all the available control options:
### 1. Say Message
Makes the assistant say a specific message during the call.
```bash
curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control'
-H 'content-type: application/json'
--data-raw '{
"type": "say",
"content": "Welcome to Vapi, this message was injected during the call.",
"endCallAfterSpoken": false
}'
```
### 2. Add Message to Conversation
Adds a message to the conversation history and optionally triggers a response.
```bash
curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control'
-H 'content-type: application/json'
--data-raw '{
"type": "add-message",
"message": {
"role": "system",
"content": "New message added to conversation"
},
"triggerResponseEnabled": true
}'
```
### 3. Assistant Control
Control the assistant's behavior during the call.
```bash
curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control'
-H 'content-type: application/json'
--data-raw '{
"type": "control",
"control": "mute-assistant" // Options: "mute-assistant", "unmute-assistant", "say-first-message"
}'
```
### 4. End Call
Programmatically end the ongoing call.
```bash
curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control'
-H 'content-type: application/json'
--data-raw '{
"type": "end-call"
}'
```
### 5. Transfer Call
Transfer the call to a different destination.
```bash
curl -X POST 'https://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/control'
-H 'content-type: application/json'
--data-raw '{
"type": "transfer",
"destination": {
"type": "number",
"number": "+1234567890"
},
"content": "Transferring your call now"
}'
```
## Call Listen Feature
The `listenUrl` allows you to connect to a WebSocket and stream the audio data in real-time. You can either process the audio directly or save the binary data to analyze or replay later.
### Example: Saving Audio Data from a Live Call
Here is a simple implementation for saving the audio buffer from a live call using Node.js:
```jsx
const WebSocket = require('ws');
const fs = require('fs');
let pcmBuffer = Buffer.alloc(0);
const ws = new WebSocket("wss://aws-us-west-2-production1-phone-call-websocket.vapi.ai/7420f27a-30fd-4f49-a995-5549ae7cc00d/transport");
ws.on('open', () => console.log('WebSocket connection established'));
ws.on('message', (data, isBinary) => {
if (isBinary) {
pcmBuffer = Buffer.concat([pcmBuffer, data]);
console.log(`Received PCM data, buffer size: ${pcmBuffer.length}`);
} else {
console.log('Received message:', JSON.parse(data.toString()));
}
});
ws.on('close', () => {
if (pcmBuffer.length > 0) {
fs.writeFileSync('audio.pcm', pcmBuffer);
console.log('Audio data saved to audio.pcm');
}
});
ws.on('error', (error) => console.error('WebSocket error:', error));
```
# Customer join timeout
> Set maximum time for users to join web calls before automatic termination
## Overview
**Customer join timeout** sets the maximum time users have to join a web call before it's automatically terminated. This parameter helps you optimize call success rates by accounting for real-world connection challenges.
**You'll learn to:**
* Configure timeout values for different user scenarios
* Monitor join success rates and failures
* Troubleshoot timeout-related call issues
This setting applies only to **web calls**. Phone calls are not affected by
this parameter.
## How it works
When a web call starts, users must complete several steps within the timeout window:
Establish connection to Vapi servers
Grant browser microphone access
Complete audio handshake process
**Default timeout:** 15 seconds\
**Available range:** 1-60 seconds
If users don't complete all steps within the timeout, the call ends with an
`assistant-did-not-receive-customer-audio` error.
## Configuration
Configure `customerJoinTimeoutSeconds` through the Vapi API for both permanent and transient assistants.
Set timeout when creating a new assistant:
```typescript title="TypeScript (Server SDK)"
import { VapiClient } from "@vapi-ai/server-sdk";
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
const assistant = await client.assistants.create({
name: "Customer Support Assistant",
model: {
provider: "openai",
model: "gpt-4.1-mini"
},
voice: {
provider: "11labs",
voiceId: "21m00Tcm4TlvDq8ikWAM"
},
customerJoinTimeoutSeconds: 30
});
```
```python title="Python (Server SDK)"
from vapi import Vapi
client = Vapi(token=os.getenv("VAPI_API_KEY"))
assistant = client.assistants.create(
name="Customer Support Assistant",
model={"provider": "openai", "model": "gpt-4.1-mini"},
voice={"provider": "11labs", "voiceId": "21m00Tcm4TlvDq8ikWAM"},
customer_join_timeout_seconds=30
)
```
```bash title="cURL"
curl -X POST "https://api.vapi.ai/assistant" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support Assistant",
"model": {"provider": "openai", "model": "gpt-4.1-mini"},
"voice": {"provider": "11labs", "voiceId": "21m00Tcm4TlvDq8ikWAM"},
"customerJoinTimeoutSeconds": 30
}'
```
Modify timeout for an existing assistant:
```typescript title="TypeScript (Server SDK)"
const updatedAssistant = await client.assistants.update("assistant-id", {
customerJoinTimeoutSeconds: 45
});
```
```python title="Python (Server SDK)"
updated_assistant = client.assistants.update(
"assistant-id",
customer_join_timeout_seconds=45
)
```
```bash title="cURL"
curl -X PATCH "https://api.vapi.ai/assistant/assistant-id" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"customerJoinTimeoutSeconds": 45}'
```
Use timeout with inline assistant configuration:
```typescript title="TypeScript (Server SDK)"
const call = await client.calls.createWeb({
assistant: {
model: { provider: "openai", model: "gpt-4.1-mini" },
voice: { provider: "playht", voiceId: "jennifer" },
customerJoinTimeoutSeconds: 60
}
});
```
```python title="Python (Server SDK)"
call = client.calls.create_web(
assistant={
"model": {"provider": "openai", "model": "gpt-4.1-mini"},
"voice": {"provider": "playht", "voiceId": "jennifer"},
"customer_join_timeout_seconds": 60
}
)
```
```bash title="cURL"
curl -X POST "https://api.vapi.ai/call/web" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistant": {
"model": {"provider": "openai", "model": "gpt-4.1-mini"},
"voice": {"provider": "playht", "voiceId": "jennifer"},
"customerJoinTimeoutSeconds": 60
}
}'
```
Override timeout for specific calls:
```typescript title="TypeScript (Server SDK)"
const call = await client.calls.createWeb({
assistantId: "your-assistant-id",
assistantOverrides: {
customerJoinTimeoutSeconds: 60
}
});
```
```python title="Python (Server SDK)"
call = client.calls.create_web(
assistant_id="your-assistant-id",
assistant_overrides={
"customer_join_timeout_seconds": 60
}
)
```
```bash title="cURL"
curl -X POST "https://api.vapi.ai/call/web" \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"assistantOverrides": {
"customerJoinTimeoutSeconds": 60
}
}'
```
## Optimization guidelines
### Recommended timeout values
Choose timeout values based on your user scenarios:
| User Type | Recommended Timeout | Reason |
| ----------------------- | ------------------- | ----------------------------------- |
| **Corporate users** | 45-60 seconds | Security policies, proxy delays |
| **Mobile users** | 30-45 seconds | Permission prompts, slower networks |
| **International users** | 30-60 seconds | Higher latency connections |
| **First-time users** | 45-60 seconds | Unfamiliar with interface |
| **Returning users** | 20-30 seconds | Familiar with flow |
### Balancing considerations
**Benefits:** - Improved join success rates - Better user experience - Fewer
support requests **Trade-offs:** - Resources tied up longer - Delayed error
detection
**Benefits:** - Faster resource cleanup - Quick failure detection - Reduced
server load **Trade-offs:** - More failed joins - Frustrated users
## Monitoring and troubleshooting
### Key metrics to track
Monitor these call ended reasons to optimize your timeout settings:
**Meaning:** Customer didn't complete join process within timeout
**Actions:**
* Increase `customerJoinTimeoutSeconds` value
* Analyze user feedback for connection issues
* Consider user base demographics
**Meaning:** Legacy reason replaced by above (for better clarity)
**Actions:**
* Review your browser permission prompts
* Add user guidance for microphone access
* Consider increasing timeout for permission flow
### Example scenario analysis
A user attempting to join needs:
* **5 seconds:** Network connection establishment
* **10 seconds:** Microphone permission prompt and user response
* **8 seconds:** WebRTC handshake completion
* **Total:** 23 seconds required
**With 15-second timeout:** Call fails\
**With 30+ second timeout:** Call succeeds
Start with 30-60 seconds and adjust based on your success rate analytics.
### "Meeting has ended" message
This message appears when a call ends naturally and is **informational only**—not an error.
## Best practices
Begin with 30-60 second timeouts to establish baseline success rates.
{" "}
Track join success rates and timeout-related call ended reasons in your
dashboard.
{" "}
Validate timeout settings in staging environment before production deployment.
{" "}
Consider different timeout values for different user types or regions.
Show loading indicators and connection status during the join process.
## Next steps
Now that you understand customer join timeouts:
* **Monitor your metrics:** Check your [call analytics](/dashboard) for timeout-related failures
* **Explore call features:** Learn about [real-time call control](/calls/call-features)
* **Understand call failures:** Review [call ended reasons](/calls/call-ended-reason) for comprehensive troubleshooting
# Voicemail Detection
When you're running outbound voice agents, voicemails are a reality — but wasting time or missing opportunities because of them shouldn't be.
**Vapi's updated voicemail detection system** gives you faster, smarter, and more flexible handling of voicemail events, so you can keep your calls efficient, responsive, and professional.
## **Why Voicemail Detection Matters**
* **Save time** by avoiding long waits on unanswered calls.
* **Optimize costs** by cutting down on wasted minutes.
* **Improve UX** by ensuring your agent behaves naturally when encountering voicemail greetings.
* **Boost response rates** by leaving cleaner, more intentional voicemail messages.
***
## **Today's Detection Options**
You can now choose between several detection methods — but not all are created equal:
| Detection Method | Strengths | Weaknesses | Recommendation |
| :------------------------------- | :----------------------------------------------- | :--------------------------------------- | :----------------------------- |
| **Vapi (Recommended)** | Fast, accurate, gracefully handles interruptions | None significant | ✅ Strongly recommended |
| **Google** | Very good accuracy, reliable | Slightly longer detection time than Vapi | ✅ Recommended |
| **OpenAI** | High accuracy, flexible phrasing | Higher cost | ✅ Good option if budget allows |
| **Twilio** (legacy) | Very fast machine beep detection | Prone to false positives | ⚠️ Use only in special cases |
| **Vapi Voicemail Tool** (legacy) | Keyword-based detection in transcription | Slow, context-dependent | ⚠️ Use only if needed |
***
## **New Default Behavior: Vapi Voicemail Detection**
With **Vapi Voicemail Detection**, your assistant will:
* **Detect voicemail faster** (often within the first few seconds of the call).
* **Handle real-time pickups** gracefully — if a human picks up mid-voicemail, the agent will switch back naturally.
* **Interrupt the bot's first message** appropriately if voicemail is detected mid-sentence.
* **Minimize false positives** by combining audio analysis (beeps) and transcription intelligence.
All three providers — **Vapi, Google, and OpenAI** — now support **interruption handling** and **false positive protection**.
***
## **How to Configure It**
On the **Assistants tab**, you'll find an updated Voicemail Detection section:
You can choose your preferred detection provider:
* **Vapi (default)**
* **Google**
* **OpenAI**
* **Twilio**
* **Tool-based (legacy)**
## **Advanced Configuration Options**
For each detection method, you can fine-tune the following parameters:
| Parameter | Description |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------- |
| **Initial Detection Delay** | How long to wait (in seconds) before starting voicemail detection. |
| **Detection Retry Interval** | How frequently to check for voicemail after the initial delay. |
| **Max Detection Retries** | Maximum number of detection attempts before stopping. |
| **Max Voicemail Message Wait** | Maximum time to wait before leaving a voicemail if no beep is detected. |
These settings allow you to balance:
* **Speed** (how quickly voicemail is detected)
* **Accuracy** (reducing false positives)
* **Cost** (fewer detection attempts = lower API costs)
***
## **How Vapi Detection Works**
Vapi's detection engine combines:
* **Gemini model-based detection** (fast and highly accurate on common voicemail phrasing)
* **Twilio beep detection** (optional, for faster reaction to voicemail system beeps)
* **Real-time call monitoring** to react instantly if a human unexpectedly picks up
* **Continuous voicemail polling** during early call stages (detecting voicemail faster without waiting for a full timeout)
This hybrid approach means **less call delay, fewer mistakes, and a much more natural call experience.**
***
By switching to Vapi's new detection system, you'll avoid the common pitfalls of older voicemail detection, while creating a **faster, smarter, and more professional experience** for your users.
# Call Forwarding
Vapi's call forwarding functionality allows you to redirect calls to different phone numbers based on specific conditions using tools. This guide explains how to set up and use the `transferCall` function for call forwarding.
## Key Concepts
### Call Forwarding Tools
* **`transferCall` Tool**: This tool enables call forwarding to predefined phone numbers with specific messages based on the destination.
### Parameters and Messages
* **Destinations**: A list of phone numbers where the call can be forwarded.
* **Messages**: Custom messages that inform the caller about the call being forwarded.
## Setting Up Call Forwarding
### 1. Create a Transfer Call Tool in the Dashboard
The recommended approach is to create your transfer call tool in the Vapi dashboard:
1. Navigate to **Tools** in your Vapi dashboard
2. Click **Create Tool**
3. Select **Transfer Call** as the tool type
4. Configure your destinations:
* **Department A**: `+1234567890` with message "I am forwarding your call to Department A. Please stay on the line."
* **Department B**: `+0987654321` with message "I am forwarding your call to Department B. Please stay on the line."
* **Department C**: `+1122334455` with message "I am forwarding your call to Department C. Please stay on the line."
### 2. Alternative: API Configuration
You can also define the tool via API with destinations and corresponding messages:
```json
{
"tools": [
{
"type": "transferCall",
"destinations": [
{
"type": "number",
"number": "+1234567890",
"message": "I am forwarding your call to Department A. Please stay on the line."
},
{
"type": "number",
"number": "+0987654321",
"message": "I am forwarding your call to Department B. Please stay on the line."
},
{
"type": "number",
"number": "+1122334455",
"message": "I am forwarding your call to Department C. Please stay on the line."
}
],
"function": {
"name": "transferCall",
"description": "Use this function to transfer the call. Only use it when following instructions that explicitly ask you to use the transferCall function. DO NOT call this function unless you are instructed to do so.",
"parameters": {
"type": "object",
"properties": {
"destination": {
"type": "string",
"enum": ["+1234567890", "+0987654321", "+1122334455"],
"description": "The destination to transfer the call to."
}
},
"required": ["destination"]
}
},
"messages": [
{
"type": "request-start",
"content": "I am forwarding your call to Department A. Please stay on the line.",
"conditions": [
{
"param": "destination",
"operator": "eq",
"value": "+1234567890"
}
]
},
{
"type": "request-start",
"content": "I am forwarding your call to Department B. Please stay on the line.",
"conditions": [
{
"param": "destination",
"operator": "eq",
"value": "+0987654321"
}
]
},
{
"type": "request-start",
"content": "I am forwarding your call to Department C. Please stay on the line.",
"conditions": [
{
"param": "destination",
"operator": "eq",
"value": "+1122334455"
}
]
}
]
}
]
}
```
You can also specify the `extension` parameter to forward the call to an extension.
```json
"destinations": [
{
"type": "number",
"number": "+1234567890",
"extension": "4603",
"message": "I am forwarding your call to Department A. Please stay on the line."
}
]
```
### 3. Using the `transferCall` Function
When the assistant needs to forward a call, it uses the `transferCall` function with the appropriate destination:
```json
{
"function": {
"name": "transferCall",
"parameters": {
"destination": "+1234567890"
}
}
}
```
### 4. Customizing Messages
Customize the messages for each destination to provide clear information to the caller:
```json
{
"messages": [
{
"type": "request-start",
"content": "I am forwarding your call to Department A. Please stay on the line.",
"conditions": [
{
"param": "destination",
"operator": "eq",
"value": "+1234567890"
}
]
}
]
}
```
## Instructing the Assistant
Use the system prompt to guide the assistant on when to utilize each forwarding number. For example:
* "If the user asks for sales, call the `transferCall` function with `+1234567890`."
* "If the user requests technical support, use the `transferCall` function with `+0987654321`."
## Troubleshooting
* If calls are not being transferred, check the logs for errors.
* Ensure that the correct destination numbers are used.
* Ensure you have written the function description properly to indicate where you want to forward the call
* Test the call forwarding setup thoroughly to confirm its functionality.
## Call Transfers Mode
Vapi supports two types of call transfers:
1. **Blind Transfer** (default): Directly transfers the call to another agent without providing any prior information to the recipient.
2. **Warm Transfer**: Transfers the call to another agent after providing context about the call. The context can be either a full transcript or a summary, based on your configuration.
### Warm Transfer
To implement a warm transfer, add a `transferPlan` object to the `transferCall` tool syntax and specify the transfer mode.
Note: Warm transfer functionality is currently available only with Twilio-based telephony systems.
#### Modes of Warm Transfer
#### 1. Warm Transfer with Summary
In this mode, Vapi provides a summary of the call to the recipient before transferring.
* **Configuration:**
* Set the `mode` to `"warm-transfer-with-summary"`.
* Define a `summaryPlan` specifying how the summary should be generated.
* Use the `{{transcript}}` variable to include the call transcript.
* **Example:**
```json
"transferPlan": {
"mode": "warm-transfer-with-summary",
"summaryPlan": {
"enabled": true,
"messages": [
{
"role": "system",
"content": "Please provide a summary of the call."
},
{
"role": "user",
"content": "Here is the transcript:\n\n{{transcript}}\n\n"
}
]
}
}
```
#### 2. Warm Transfer with Message
In this mode, Vapi delivers a custom message to the recipient before transferring the call.
* **Configuration:**
* Set the `mode` to `"warm-transfer-with-message"`.
* Provide the custom message in the `message` property.
* Note that the `{{transcript}}` variable is not available in this mode.
* **Example:**
```json
"transferPlan": {
"mode": "warm-transfer-with-message",
"message": "Hey, this call has been forwarded through Vapi."
}
```
#### Complete Example
Here is a full example of a `transferCall` payload using the warm transfer with summary mode:
```json
{
"type": "transferCall",
"messages": [
{
"type": "request-start",
"content": "I'll transfer you to someone who can help."
}
],
"destinations": [
{
"type": "number",
"number": "+918936850523",
"description": "Transfer the call",
"transferPlan": {
"mode": "warm-transfer-with-summary",
"summaryPlan": {
"enabled": true,
"messages": [
{
"role": "system",
"content": "Please provide a summary of the call."
},
{
"role": "user",
"content": "Here is the transcript:\n\n{{transcript}}\n\n"
}
]
}
}
}
]
}
```
#### 3. Warm Transfer with Wait and Say Message
In this mode, Vapi waits for the recipient to speak first and then delivers a custom message to the recipient before transferring the call.
* **Configuration:**
* Set the `mode` to `"warm-transfer-wait-for-operator-to-speak-first-and-then-say-message"`.
* Provide the custom message in the `message` property.
* Note that the `{{transcript}}` variable is not available in this mode.
* **Example:**
```json
"transferPlan": {
"mode": "warm-transfer-wait-for-operator-to-speak-first-and-then-say-message",
"message": "Hey, this call has been forwarded through Vapi."
}
```
#### 4. Warm Transfer with Wait and Say Summary
In this mode, Vapi waits for the recipient to speak first and then delivers a summary of the call to the recipient before transferring the call.
* **Configuration:**
* Set the `mode` to `"warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary"`.
* Define a `summaryPlan` specifying how the summary should be generated.
* Use the `{{transcript}}` variable to include the call transcript.
* **Example:**
```json
"transferPlan": {
"mode": "warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary",
"summaryPlan": {
"enabled": true,
"messages": [
{
"role": "system",
"content": "Please provide a summary of the call."
},
{
"role": "user",
"content": "Here is the transcript:\n\n{{transcript}}\n\n"
}
]
}
}
```
#### 5. Warm Transfer with TwiML
In this mode, Vapi executes TwiML instructions on the destination call leg before connecting the destination number.
* **Configuration:**
* Set the `mode` to `"warm-transfer-with-twiml"`.
* Provide the TwiML instructions in the `twiml` property.
* Supports only `Play`, `Say`, `Gather`, and `Pause` verbs.
* Maximum TwiML length is 4096 characters.
* TwiML must be provided as a single-line string without line breaks or tabs, and must be a valid XML string. For example: `Hello` is valid, but `Hello\n` is not.
* **Example:**
```json
"transferPlan": {
"mode": "warm-transfer-with-twiml",
"twiml": "Hello, transferring a customer to you.They called about billing questions."
}
```
Here is a full example of a `transferCall` payload using the warm transfer with TwiML mode:
```json
{
"type": "transferCall",
"messages": [
{
"type": "request-start",
"content": "I'll transfer you to someone who can help."
}
],
"destinations": [
{
"type": "number",
"number": "+14155551234",
"description": "Transfer to customer support",
"transferPlan": {
"mode": "warm-transfer-with-twiml",
"twiml": "Hello, this is an incoming call from a customer.They have questions about their recent order.Connecting you now.",
"sipVerb": "refer"
}
}
]
}
```
#### 6. Experimental Warm Transfer
In this mode, Vapi dials the destination number and places the caller on hold (with a default ringtone). If the destination answers, Vapi connects the calls. If voicemail is detected or the call isn't answered, Vapi plays a fallback message to the caller.
* **Configuration:**
* Set the `mode` to `"warm-transfer-experimental"`.
* Provide a `message` to be spoken to the operator when they answer.
* Optionally define a `summaryPlan` that will take precedence over the message if enabled.
* Configure a `fallbackPlan` with a message and whether to end the call if transfer fails.
* When voicemail detection is enabled in the assistant configuration (with either Google or OpenAI provider), it will use that configuration to detect if a human answered the call. Note that only Google or OpenAI providers are supported for voicemail detection with transfer plans, even if the assistant configuration supports other providers like Twilio or Vapi.
* **Example:**
```json
"transferPlan": {
"mode": "warm-transfer-experimental",
"message": "Transferring a customer to you.",
"fallbackPlan": {
"message": "Could not transfer your call, goodbye.",
"endCallEnabled": true
},
"summaryPlan": {
"enabled": true,
"messages": [
{
"role": "system",
"content": "Please provide a summary of the call."
},
{
"role": "user",
"content": "Here is the transcript:\n\n{{transcript}}\n\n"
}
]
}
}
```
Here is a full example of a `transferCall` payload using the experimental warm transfer mode:
```json
{
"type": "transferCall",
"function": {
"name": "myTransferCall"
},
"destinations": [
{
"type": "number",
"number": "+1123456789",
"message": "Transferring the call now...",
"transferPlan": {
"mode": "warm-transfer-experimental",
"message": "Transferring a customer to you.",
"fallbackPlan": {
"message": "Could not transfer your call, goodbye.",
"endCallEnabled": true
},
"summaryPlan": {
"enabled": true,
"messages": [
{
"role": "system",
"content": "Please provide a summary of the call."
},
{
"role": "user",
"content": "Here is the transcript:\n\n{{transcript}}\n\n"
}
]
}
}
}
]
}
```
**Notes:**
* In all warm transfer modes, the `{{transcript}}` variable contains the full transcript of the call and can be used within the `summaryPlan`.
* For more details about transfer plans and configuration options, please refer to the [transferCall API documentation](/api-reference/tools/create#request.body.transferCall.destinations.number.transferPlan)
# Dynamic call transfers
> Learn how Vapi's dynamic call transfers work and explore implementation patterns for intelligent call routing.
## Overview
Dynamic call transfers enable intelligent routing by determining transfer destinations in real-time based on conversation context, customer data, or external system information. Unlike static transfers with predefined destinations, dynamic transfers make routing decisions on-the-fly during the call.
**Key capabilities:**
* Real-time destination selection based on conversation analysis
* Integration with CRM systems, databases, and external APIs
* Conditional routing logic for departments, specialists, or geographic regions
* Context-aware transfers with conversation summaries
* Fallback handling for unavailable destinations
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/)
* A server or cloud function that can receive webhooks from Vapi
* (Optional) CRM system or customer database for enhanced routing logic
## How It Works
Dynamic transfers operate by leaving the destination unspecified initially, then using webhooks to determine the appropriate destination when needed.
**Transfer flow:**
1. **Trigger** - Voice agent determines a transfer is needed based on conversation
2. **Webhook** - Vapi sends `transfer-destination-request` to your server with call context
3. **Decision** - Your server analyzes context and external data to determine routing
4. **Response** - Server returns destination details and transfer configuration
5. **Transfer** - Vapi executes the transfer to the determined destination
**Available context:** Your webhook receives conversation transcript, extracted variables, customer information, function parameters, and call metadata.
***
## Quick Implementation Guide
* Navigate to **Tools** in your dashboard
* Click **Create Tool**
* Select **Transfer Call** as the tool type
* **Important**: Leave the destinations array empty - this creates a dynamic transfer tool
* Set function name: `dynamicTransfer`
* Add description explaining when this tool should be used
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const vapi = new VapiClient({ token: process.env.VAPI_API_KEY });
const dynamicTool = await vapi.tools.create({
type: "transferCall",
// Empty destinations array makes this dynamic
destinations: [],
function: {
name: "dynamicTransfer",
description: "Transfer call to appropriate destination based on customer needs",
parameters: {
type: "object",
properties: {
reason: {
type: "string",
description: "Reason for transfer"
},
urgency: {
type: "string",
enum: ["low", "medium", "high", "critical"]
}
}
}
}
});
console.log(`Dynamic transfer tool created: ${dynamicTool.id}`);
```
```python
import requests
import os
def create_dynamic_transfer_tool():
url = "https://api.vapi.ai/tool"
headers = {
"Authorization": f"Bearer {os.getenv('VAPI_API_KEY')}",
"Content-Type": "application/json"
}
data = {
"type": "transferCall",
"destinations": [], # Empty for dynamic routing
"function": {
"name": "dynamicTransfer",
"description": "Transfer call to appropriate destination based on customer needs",
"parameters": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Reason for transfer"
},
"urgency": {
"type": "string",
"enum": ["low", "medium", "high", "critical"]
}
}
}
}
}
response = requests.post(url, headers=headers, json=data)
return response.json()
tool = create_dynamic_transfer_tool()
print(f"Dynamic transfer tool created: {tool['id']}")
```
```bash
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "transferCall",
"destinations": [],
"function": {
"name": "dynamicTransfer",
"description": "Transfer call to appropriate destination based on customer needs",
"parameters": {
"type": "object",
"properties": {
"reason": {"type": "string", "description": "Reason for transfer"},
"urgency": {"type": "string", "enum": ["low", "medium", "high", "critical"]}
}
}
}
}'
```
* Navigate to **Assistants**
* Create a new assistant or edit an existing one
* Add your dynamic transfer tool to the assistant
* Enable the **transfer-destination-request** server event
* Set your server URL to handle the webhook
```typescript
const assistant = await vapi.assistants.create({
name: "Dynamic Transfer Assistant",
firstMessage: "Hello! How can I help you today?",
model: {
provider: "openai",
model: "gpt-4o",
messages: [
{
role: "system",
content: "You help customers and transfer them when needed using the dynamicTransfer tool. Assess the customer's needs and transfer to the appropriate department."
}
],
toolIds: ["YOUR_DYNAMIC_TOOL_ID"]
},
voice: {
provider: "11labs",
voiceId: "burt"
},
serverUrl: "https://your-server.com/webhook",
serverUrlSecret: process.env.WEBHOOK_SECRET
});
```
```python
def create_assistant_with_dynamic_transfer(tool_id):
url = "https://api.vapi.ai/assistant"
headers = {
"Authorization": f"Bearer {os.getenv('VAPI_API_KEY')}",
"Content-Type": "application/json"
}
data = {
"name": "Dynamic Transfer Assistant",
"firstMessage": "Hello! How can I help you today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [{
"role": "system",
"content": "You help customers and transfer them when needed using the dynamicTransfer tool. Assess the customer's needs and transfer to the appropriate department."
}],
"toolIds": [tool_id]
},
"voice": {"provider": "11labs", "voiceId": "burt"},
"serverUrl": "https://your-server.com/webhook",
"serverUrlSecret": os.getenv("WEBHOOK_SECRET")
}
response = requests.post(url, headers=headers, json=data)
return response.json()
```
```bash
curl -X POST https://api.vapi.ai/assistant \
-H "Authorization: Bearer $VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Dynamic Transfer Assistant",
"firstMessage": "Hello! How can I help you today?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [{
"role": "system",
"content": "You help customers and transfer them when needed using the dynamicTransfer tool."
}],
"toolIds": ["YOUR_DYNAMIC_TOOL_ID"]
},
"serverUrl": "https://your-server.com/webhook"
}'
```
```typescript
import express from 'express';
import crypto from 'crypto';
const app = express();
app.use(express.json());
function verifyWebhookSignature(payload: string, signature: string) {
const expectedSignature = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET!)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
app.post('/webhook', (req, res) => {
try {
const signature = req.headers['x-vapi-signature'] as string;
const payload = JSON.stringify(req.body);
if (!verifyWebhookSignature(payload, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const request = req.body;
if (request.type !== 'transfer-destination-request') {
return res.status(200).json({ received: true });
}
// Simple routing logic - customize for your needs
const { functionCall, customer } = request;
const urgency = functionCall.parameters?.urgency || 'medium';
let destination;
if (urgency === 'critical') {
destination = {
type: "number",
number: "+1-555-EMERGENCY",
message: "Connecting you to our emergency team."
};
} else {
destination = {
type: "number",
number: "+1-555-SUPPORT",
message: "Transferring you to our support team."
};
}
res.json({ destination });
} catch (error) {
console.error('Webhook error:', error);
res.status(500).json({
error: 'Transfer routing failed. Please try again.'
});
}
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});
```
```python
import os
import hmac
import hashlib
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
def verify_webhook_signature(payload: bytes, signature: str) -> bool:
webhook_secret = os.getenv('WEBHOOK_SECRET', '').encode()
expected_signature = hmac.new(
webhook_secret, payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)
@app.post("/webhook")
async def handle_webhook(request: Request):
try:
body = await request.body()
signature = request.headers.get('x-vapi-signature', '')
if not verify_webhook_signature(body, signature):
raise HTTPException(status_code=401, detail="Invalid signature")
request_data = await request.json()
if request_data.get('type') != 'transfer-destination-request':
return {"received": True}
# Simple routing logic - customize for your needs
function_call = request_data.get('functionCall', {})
urgency = function_call.get('parameters', {}).get('urgency', 'medium')
if urgency == 'critical':
destination = {
"type": "number",
"number": "+1-555-EMERGENCY",
"message": "Connecting you to our emergency team."
}
else:
destination = {
"type": "number",
"number": "+1-555-SUPPORT",
"message": "Transferring you to our support team."
}
return {"destination": destination}
except Exception as error:
print(f"Webhook error: {error}")
raise HTTPException(
status_code=500,
detail="Transfer routing failed. Please try again."
)
```
* Create a phone number and assign your assistant
* Call the number and test different transfer scenarios
* Monitor your webhook server logs to see the routing decisions
* Verify transfers are working to the correct destinations
```typescript
// Test with an outbound call
const testCall = await vapi.calls.create({
assistantId: "YOUR_ASSISTANT_ID",
customer: {
number: "+1234567890" // Your test number
}
});
console.log(`Test call created: ${testCall.id}`);
// Monitor webhook server logs to see transfer requests
```
```python
def test_dynamic_transfers(assistant_id):
url = "https://api.vapi.ai/call"
headers = {
"Authorization": f"Bearer {os.getenv('VAPI_API_KEY')}",
"Content-Type": "application/json"
}
data = {
"assistantId": assistant_id,
"customer": {"number": "+1234567890"}
}
response = requests.post(url, headers=headers, json=data)
call = response.json()
print(f"Test call created: {call['id']}")
return call
```
***
## Implementation Approaches
**Assistant-based implementation** uses transfer-type tools with conditions interpreted by the assistant through system prompts. The assistant determines when and where to route calls based on clearly defined tool purposes and routing logic in the prompt. Best for quick setup and simpler routing scenarios.
**Workflow-based implementation** uses conditional logic based on outputs from any workflow node - tools, API requests, conversation variables, or other data sources. Conditions evaluate node outputs to determine routing paths within visual workflows. Best for complex business logic, structured decision trees, and team-friendly configuration.
**Assistant-based routing**
Route customers to appropriate support tiers based on conversation analysis and customer data
**Workflow-based routing**
Direct tenant calls to the right department with automated verification
## Routing Patterns
### Common Use Cases
* **Customer support routing** - Route based on issue type, customer tier, agent availability, and interaction history. Enterprise customers and critical issues get priority routing to specialized teams.
* **Geographic routing** - Direct calls to regional offices based on customer location and business hours. Automatically handle time zone differences and language preferences.
* **Load balancing** - Distribute calls across available agents to optimize wait times and agent utilization. Route to the least busy qualified agent.
* **Escalation management** - Implement intelligent escalation based on conversation tone, issue complexity, and customer history. Automatically route urgent issues to senior agents.
### Transfer Configuration
1. **Warm transfers** provide context to receiving agents with AI-generated conversation summaries, ensuring smooth handoffs with full context.
2. **Cold transfers** route calls immediately with predefined context messages, useful for simple departmental routing.
3. **Conditional transfers** apply different transfer modes based on routing decisions, such as priority handling for enterprise customers.
4. **Destination types** include phone numbers for human agents, SIP endpoints for VoIP systems, and Vapi assistants for specialized AI agents.
**Security considerations:** Always verify webhook signatures to ensure requests come from Vapi. Never log sensitive customer data, implement proper access controls, and follow privacy regulations like GDPR and CCPA when handling customer information in routing decisions.
## Related Documentation
* **[Call Forwarding](/call-forwarding)** - Static transfer options and transfer plans
* **[Webhooks](/server-url)** - Webhook security and event handling patterns
* **[Custom Tools](/tools/custom-tools)** - Build custom tools for advanced routing logic
# Call Handling with Vapi and Twilio
This document explains how to handle a scenario where a user is on hold while the system attempts to connect them to a specialist. If the specialist does not pick up within X seconds or if the call hits voicemail, we take an alternate action (like playing an announcement or scheduling an appointment). This solution integrates Vapi.ai for AI-driven conversations and Twilio for call bridging.
## Problem
Vapi.ai does not provide a built-in way to keep the user on hold, dial a specialist, and handle cases where the specialist is unavailable. We want:
1. The user already talking to the AI (Vapi).
2. The AI offers to connect them to a specialist.
3. The user is placed on hold or in a conference room.
4. We dial the specialist to join.
5. If the specialist answers, everyone is merged.
6. If the specialist does not answer (within X seconds or goes to voicemail), we want to either announce "Specialist not available" or schedule an appointment.
## Solution
1. An inbound call arrives from Vapi or from the user directly.
2. We store its details (e.g., Twilio CallSid).
3. We send TwiML (or instructions) to put the user in a Twilio conference (on hold).
4. We place a second call to the specialist, also directed to join the same conference.
5. If the specialist picks up, Twilio merges the calls.
6. If not, we handle the no-answer event by playing a message or returning control to the AI for scheduling.
## Steps to Solve the Problem
1. **Receive Inbound Call**
* Twilio posts data to your `/inbound_call`.
* You store the call reference.
* You might also invoke Vapi for initial AI instructions.
2. **Prompt User via Vapi**
* The user decides whether they want the specialist.
* If yes, you call an endpoint (e.g., `/connect`).
3. **Create/Join Conference**
* In `/connect`, you update the inbound call to go into a conference route.
* The user is effectively on hold.
4. **Dial Specialist**
* You create a second call leg to the specialist’s phone.
* A `statusCallback` can detect no-answer or voicemail.
5. **Detect Unanswered**
* If Twilio sees a no-answer or failure, your callback logic plays an announcement or signals the AI to schedule an appointment.
6. **Merge or Exit**
* If the specialist answers, they join the user.
* If not, the user is taken off hold and the call ends or goes back to AI.
7. **Use Ephemeral Call (Optional)**
* If you need an in-conference announcement, create a short-lived Twilio call that `` the message to everyone, then ends the conference.
## Code Example
Below is a minimal Express.js server aligned for On-Hold Specialist Transfer with Vapi and Twilio.
1. **Express Setup and Environment**
```js
const express = require("express");
const bodyParser = require("body-parser");
const axios = require("axios");
const twilio = require("twilio");
const app = express();
app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());
// Load important env vars
const {
TWILIO_ACCOUNT_SID,
TWILIO_AUTH_TOKEN,
FROM_NUMBER,
TO_NUMBER,
VAPI_BASE_URL,
PHONE_NUMBER_ID,
ASSISTANT_ID,
PRIVATE_API_KEY,
} = process.env;
// Create a Twilio client
const client = twilio(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN);
// We'll store the inbound call SID here for simplicity
let globalCallSid = "";
```
2. **`/inbound_call` - Handling the Inbound Call**
```js
app.post("/inbound_call", async (req, res) => {
try {
globalCallSid = req.body.CallSid;
const caller = req.body.Caller;
// Example: We call Vapi.ai to get initial TwiML
const response = await axios.post(
`${VAPI_BASE_URL || "https://api.vapi.ai"}/call`,
{
phoneNumberId: PHONE_NUMBER_ID,
phoneCallProviderBypassEnabled: true,
customer: { number: caller },
assistantId: ASSISTANT_ID,
},
{
headers: {
Authorization: `Bearer ${PRIVATE_API_KEY}`,
"Content-Type": "application/json",
},
}
);
const returnedTwiml = response.data.phoneCallProviderDetails.twiml;
return res.type("text/xml").send(returnedTwiml);
} catch (err) {
return res.status(500).send("Internal Server Error");
}
});
```
3. **`/connect` - Putting User on Hold and Dialing Specialist**
```js
app.post("/connect", async (req, res) => {
try {
const protocol =
req.headers["x-forwarded-proto"] === "https" ? "https" : "http";
const baseUrl = `${protocol}://${req.get("host")}`;
const conferenceUrl = `${baseUrl}/conference`;
// 1) Update inbound call to fetch TwiML from /conference
await client.calls(globalCallSid).update({
url: conferenceUrl,
method: "POST",
});
// 2) Dial the specialist
const statusCallbackUrl = `${baseUrl}/participant-status`;
await client.calls.create({
to: TO_NUMBER,
from: FROM_NUMBER,
url: conferenceUrl,
method: "POST",
statusCallback: statusCallbackUrl,
statusCallbackMethod: "POST",
});
return res.json({ status: "Specialist call initiated" });
} catch (err) {
return res.status(500).json({ error: "Failed to connect specialist" });
}
});
```
4. **`/conference` - Placing Callers Into a Conference**
```js
app.post("/conference", (req, res) => {
const VoiceResponse = twilio.twiml.VoiceResponse;
const twiml = new VoiceResponse();
// Put the caller(s) into a conference
const dial = twiml.dial();
dial.conference(
{
startConferenceOnEnter: true,
endConferenceOnExit: true,
},
"my_conference_room"
);
return res.type("text/xml").send(twiml.toString());
});
```
5. **`/participant-status` - Handling No-Answer or Busy**
```js
app.post("/participant-status", async (req, res) => {
const callStatus = req.body.CallStatus;
if (["no-answer", "busy", "failed"].includes(callStatus)) {
console.log("Specialist did not pick up:", callStatus);
// Additional logic: schedule an appointment, ephemeral call, etc.
}
return res.sendStatus(200);
});
```
6. **`/announce` (Optional) - Ephemeral Announcement**
```js
app.post("/announce", (req, res) => {
const VoiceResponse = twilio.twiml.VoiceResponse;
const twiml = new VoiceResponse();
twiml.say("Specialist is not available. Ending call now.");
// Join the conference, then end it.
twiml.dial().conference(
{
startConferenceOnEnter: true,
endConferenceOnExit: true,
},
"my_conference_room"
);
return res.type("text/xml").send(twiml.toString());
});
```
7. **Starting the Server**
```js
app.listen(3000, () => {
console.log("Server running on port 3000");
});
```
## How to Test
1. **Environment Variables**\
Set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `FROM_NUMBER`, `TO_NUMBER`, `VAPI_BASE_URL`, `PHONE_NUMBER_ID`, `ASSISTANT_ID`, and `PRIVATE_API_KEY`.
2. **Expose Your Server**
* Use a tool like `ngrok` to create a public URL to port 3000.
* Configure your Twilio phone number to call `/inbound_call` when a call comes in.
3. **Place a Real Call**
* Dial your Twilio number from a phone.
* Twilio hits `/inbound_call`, and run Vapi logic.
* Trigger `/connect` to conference the user and dial the specialist.
* If the specialist answers, they join the same conference.
* If they never answer, Twilio eventually calls `/participant-status`.
4. **Use cURL for Testing**
* **Simulate Inbound**:
```bash
curl -X POST https:///inbound_call \
-F "CallSid=CA12345" \
-F "Caller=+15551112222"
```
* **Connect**:
```bash
curl -X POST https:///connect \
-H "Content-Type: application/json" \
-d "{}"
```
## Note on Replacing "Connect" with Vapi Tools
Vapi offers built-in functions or custom tool calls for placing a second call or transferring, you can replace the manual `/connect` call with that Vapi functionality. The flow remains the same: user is put in a Twilio conference, the specialist is dialed, and any no-answer events are handled.
## Notes & Limitations
1. **Voicemail**\
If a phone’s voicemail picks up, Twilio sees it as answered. Consider advanced detection or a fallback.
2. **Concurrent Calls**\
Multiple calls at once require storing separate `CallSid`s or similar references.
3. **Conference Behavior**\
`startConferenceOnEnter: true` merges participants immediately; `endConferenceOnExit: true` ends the conference when that participant leaves.
4. **X Seconds**\
Decide how you detect no-answer. Typically, Twilio sets a final `callStatus` if the remote side never picks up.
With these steps and code, you can integrate Vapi Assistant while using Twilio’s conferencing features to hold, dial out to a specialist, and handle an unanswered or unavailable specialist scenario.
# Debug call forwarding drops
> Learn to troubleshoot calls that drop immediately after initiating transfer
## Overview
When you initiate call forwarding, you expect the call to transfer to the destination. Instead, the call drops immediately after initiating the transfer, leaving both parties disconnected.
**In this guide, you'll learn to:**
* Identify why calls drop during forwarding
* Check call logs and API responses systematically
* Analyze telephony provider logs for transfer failures
* Resolve configuration issues preventing successful transfers
This guide focuses on the specific scenario where calls drop immediately after
transfer initiation, not general call quality issues.
## Prerequisites
Before you start debugging, ensure you have:
* **Call ID** from the dropped call
* **API access** to make GET requests to Vapi
* **Admin access** to your telephony provider dashboard (Twilio, Vonage, Telnyx)
* **Wireshark** installed (for SIP-based calls only)
## Troubleshooting workflow
First, verify whether Vapi successfully initiated the forwarding.
```bash title="cURL"
curl -X GET "https://api.vapi.ai/call/{call_id}" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
```
```typescript title="TypeScript SDK"
import { VapiClient } from "@vapi-ai/server-sdk";
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
const call = await client.calls.get("ca123456xxxxx");
console.log("End reason:", call.endedReason);
```
```python title="Python SDK"
from vapi import Vapi
client = Vapi(token=os.getenv("VAPI_API_KEY"))
call = client.calls.get("ca123456xxxxx")
print(f"End reason: {call.ended_reason}")
```
**Check the response:**
```json title="Expected response"
{
"id": "ca123456xxxxx",
"endedReason": "assistant-forwarded-call",
"status": "ended",
"destination": {
"type": "number",
"number": "+1234567890"
},
"phoneCallProviderId": "twilio_call_abc123"
}
```
**What the `endedReason` tells you:**
* `"assistant-forwarded-call"` → Vapi forwarded successfully, continue to Step 2
* Any other value → Forwarding wasn't initiated, check your assistant configuration
If you're handling call control through server messages, this can prevent Vapi from managing transfers.
Check your assistant's `serverMessages` configuration:
```json title="Problematic configuration"
{
"assistant": {
"serverMessages": ["phone-call-control", "status-update"]
}
}
```
```json title="Correct configuration"
{
"assistant": {
"serverMessages": ["status-update"]
}
}
```
If `"phone-call-control"` is present, your server is overriding Vapi's call
control. Remove it unless you're implementing custom transfer logic.
The `phoneCallProviderBypassEnabled` flag determines whether Vapi handles call control directly.
**Recommended configuration:**
```json title="Standard Vapi forwarding"
{
"phoneCallProviderBypassEnabled": false
}
```
Only set this to `true` if you're implementing custom call control through
your telephony provider.
Not all transfer scenarios are supported. Verify your use case:
| From | To | Supported |
| ---------- | ------------ | ------------------ |
| Phone call | Phone number | ✅ Yes |
| Web call | Phone number | ❌ No |
| Phone call | SIP number | ❌ No (PSTN to SIP) |
| SIP call | SIP number | ✅ Yes |
| SIP call | Phone number | ✅ Yes |
Web-to-phone transfers are not supported. The call will always drop in this
scenario.
If the call shows `"assistant-forwarded-call"` but still drops, the issue is likely with your telephony provider.
**Get your telephony call ID** from the Vapi call object:
```json title="Extract telephony call ID"
{
"id": "ca123456xxxxx",
"endedReason": "assistant-forwarded-call",
"phoneCallProviderId": "CAabc123"
}
```
**Check your provider's dashboard:**
1. Go to [Twilio Console > Call Logs](https://console.twilio.com/us1/monitor/logs/calls)
2. Search using `phoneCallProviderId` (e.g., `CAabc123`)
3. Look for transfer-related errors in the call timeline
4. Check TwiML execution logs for failed transfers
1. Access [Vonage API Dashboard](https://dashboard.nexmo.com/) 2. Navigate to
Call Logs 3. Search using the telephony call ID and timestamp 4. Review call
flow details for transfer failures
1. Open [Telnyx Mission Control Portal](https://portal.telnyx.com/)
2. Go to Call Detail Records
3. Search using the telephony call ID
4. Examine call records for forwarding errors
For SIP trunking or bring-your-own-number setups, analyze the SIP signaling.
**Download the packet capture:**
```bash title="Get PCAP file"
curl -X GET "https://api.vapi.ai/call/{call_id}" \
-H "Authorization: Bearer YOUR_API_KEY"
```
The response includes a `pcapUrl` field. Download this file and open it in Wireshark.
**Filter for transfer packets:**
```text title="Wireshark filter"
sip.Method == "REFER"
```
**What to look for:**
* **REFER packet present** → Vapi sent the transfer request to your SIP provider
* **REFER packet missing** → Transfer wasn't initiated by Vapi
* **202 Accepted response** → SIP provider accepted the transfer
* **Error responses (4xx, 5xx)** → SIP provider rejected the transfer
**Important:** SIP transfers are handled by your telephony provider, not Vapi.
Once Vapi sends the REFER packet, your SIP provider manages the actual
transfer process.
For more details on SIP configuration, see our [SIP trunk documentation](https://docs.vapi.ai/advanced/sip/sip-trunk#inbound-call-test).
## Common solutions
Based on your findings, here are the most frequent fixes:
### Call shows successful forwarding but still drops
**Root cause:** Telephony provider couldn't complete the transfer
**Solution:** Check destination number format and availability
* Verify the destination number includes country code
* Test calling the destination directly outside of Vapi
* Check if destination has call blocking enabled
### endedReason is not 'assistant-forwarded-call'
**Root cause:** Transfer wasn't initiated due to configuration
**Solution:** Review assistant settings
* Remove `"phone-call-control"` from `serverMessages`
* Set `phoneCallProviderBypassEnabled` to `false`
* Verify your transfer function is properly configured
### SIP REFER packets missing in PCAP
**Root cause:** Vapi didn't send transfer request to SIP provider
**Solution:** Check Vapi configuration
* Verify SIP endpoint configuration
* Ensure destination format matches SIP addressing
* Check for conflicting call control settings
## Limitations
### Transfer scenario limitations
* **Web calls** cannot be transferred to phone numbers
* **PSTN-to-SIP** transfers are not supported
* Cross-provider transfers may have compatibility issues
### Configuration dependencies
* `phoneCallProviderBypassEnabled` must be `false` for Vapi-managed transfers
* `serverMessages` with `"phone-call-control"` overrides default behavior
* SIP configuration requires proper endpoint setup
## When to contact support
Escalate to support when you've completed all troubleshooting steps and:
* Provider logs show successful transfers but calls consistently fail
* SIP packet analysis indicates Vapi-side transfer issues
* Multiple destinations fail with the same configuration
* Configuration changes don't resolve recurring failures
**Include in your support request:**
* Call ID and timestamp
* Complete troubleshooting results from this guide
* Telephony provider error codes and logs
* Screenshots of configuration settings
## Next steps
Now that you can debug call forwarding drops:
* **Monitor call patterns:** Set up alerts for calls with unexpected `endedReason` values
* **Test systematically:** Verify transfers work across different destination types before production
* **Review SIP setup:** Ensure your SIP configuration follows our [advanced SIP guide](https://docs.vapi.ai/advanced/sip/sip-trunk)
# Call ended reasons
> All possible call ended reason codes and what they mean.
This guide will discuss all possible `endedReason` codes for a call.
For the full list of possible `endedReason` values, see the [API reference](/api-reference/calls/list#response.body.endedReason).
You can find these under the **"Ended Reason"** section of your [call logs](https://dashboard.vapi.ai/calls) (or under the `endedReason` field on the [Call Object](/api-reference/calls/get-call)).
#### Assistant-Related
* `assistant-ended-call`: The assistant intentionally ended the call based on the user's response.
* `assistant-ended-call-after-message-spoken`: The assistant intentionally ended the call after speaking a pre-defined message.
* `assistant-ended-call-with-hangup-task`: The assistant ended the call using a hangup task.
* `assistant-error`: This general error occurs within the assistant's logic or processing due to bugs, misconfigurations, or unexpected inputs.
* `assistant-forwarded-call`: The assistant successfully transferred the call to another number or service.
* `assistant-join-timed-out`: The assistant failed to join the call within the expected timeframe.
* `assistant-not-found`: The specified assistant cannot be located or accessed, possibly due to an incorrect assistant ID or configuration issue.
* `assistant-not-valid`: The assistant ID provided is not valid or recognized by the system.
* `assistant-not-provided`: No assistant ID was specified in the request, causing the system to fail.
* `assistant-request-failed`: The request to the assistant failed to complete successfully.
* `assistant-request-returned-error`: Communicating with the assistant resulted in an error, possibly due to network issues or problems with the assistant itself.
* `assistant-request-returned-forwarding-phone-number`: The assistant triggered a call forwarding action, ending the current call.
* `assistant-request-returned-invalid-assistant`: The assistant returned an invalid response or failed to fulfill the request properly.
* `assistant-request-returned-no-assistant`: The assistant didn't provide any response or action to the request.
* `assistant-request-returned-unspeakable-error`: The assistant returned an error that cannot be spoken to the user.
* `assistant-said-end-call-phrase`: The assistant recognized a phrase or keyword triggering call termination.
#### Pipeline and LLM
These relate to issues within the AI processing pipeline or the Large Language Models (LLMs) used for understanding and generating text:
* `call.in-progress.error-vapifault-*`: Various error codes indicate specific failures within the processing pipeline, such as function execution, LLM responses, or external service integration. Examples include OpenAI, Azure OpenAI, Together AI, and several other LLMs or voice providers.
* `call.in-progress.error-providerfault-*`: Similar to `call.in-progress.error-vapifault-*`. However, these error codes are surfaced when Vapi receives an error that has occured on the provider's side. Examples include internal server errors, or service unavailability.
* `pipeline-error-*`: Similar to `call.in-progress.error-vapifault-*`. However, these error codes are surfaced when you are using your own provider keys.
* `pipeline-no-available-llm-model`: No suitable LLM was available to process the request. Previously `pipeline-no-available-model`.
* `call.in-progress.error-pipeline-no-available-llm-model`: No suitable LLM was available to process the request during the call.
#### Phone Calls and Connectivity
* `customer-busy`: The customer's line was busy.
* `customer-ended-call`: The customer (end human user) ended the call for both inbound and outbound calls.
* `customer-did-not-answer`: The customer didn't answer the call. If you're looking to build a use case where you need the bot to talk to automated IVRs, set `assistant.voicemailDetectionEnabled=false`.
* `customer-did-not-give-microphone-permission`: The user didn't grant the necessary microphone access for the call.
* `call.in-progress.error-assistant-did-not-receive-customer-audio`: Similar to `customer-did-not-give-microphone-permission`, but more generalized to situations where no customer audio was received.
* `phone-call-provider-closed-websocket`: The connection with the call provider was unexpectedly closed.
* `phone-call-provider-bypass-enabled-but-no-call-received`: The phone call provider bypass was enabled but no call was received.
* `twilio-failed-to-connect-call`: The Twilio service, responsible for managing calls, failed to establish a connection.
* `twilio-reported-customer-misdialed`: Twilio reported that the customer dialed an invalid or incomplete number.
* `vonage-disconnected`: The call was disconnected by Vonage, another call management service.
* `vonage-failed-to-connect-call`: Vonage failed to establish the call connection.
* `vonage-rejected`: The call was rejected by Vonage due to an issue or configuration problem.
* `vonage-completed`: The call was completed successfully by Vonage.
* `call.in-progress.error-sip-telephony-provider-failed-to-connect-call`: The SIP telephony provider failed to establish the call connection.
#### Call Start Errors
* `call-start-error-neither-assistant-nor-server-set`: Neither an assistant nor server was configured for the call.
* `call.start.error-get-org`: Error retrieving organization information during call start.
* `call.start.error-get-subscription`: Error retrieving subscription information during call start.
* `call.start.error-get-assistant`: Error retrieving assistant information during call start.
* `call.start.error-get-phone-number`: Error retrieving phone number information during call start.
* `call.start.error-get-customer`: Error retrieving customer information during call start.
* `call.start.error-get-resources-validation`: Error validating resources during call start.
* `call.start.error-vapi-number-international`: Error with international Vapi number during call start.
* `call.start.error-vapi-number-outbound-daily-limit`: Outbound daily limit reached for Vapi number.
* `call.start.error-get-transport`: Error retrieving transport information during call start.
#### Call Forwarding and Hooks
* `call.forwarding.operator-busy`: The operator was busy during call forwarding.
* `call.ringing.hook-executed-say`: A say hook was executed during the ringing phase.
* `call.ringing.hook-executed-transfer`: A transfer hook was executed during the ringing phase.
#### Other Reasons
* `database-error`: A database error occurred during the call.
* `exceeded-max-duration`: The call reached its maximum allowed duration and was automatically terminated.
* `manually-canceled`: The call was manually canceled.
* `silence-timed-out`: The call was ended due to prolonged silence, indicating inactivity.
* `voicemail`: The call was diverted to voicemail.
* `worker-shutdown`: The worker handling the call was shut down.
#### Unknown
* `unknown-error`: An unexpected error occurred, and the cause is unknown. For this, please [contact support](/support) with your `call_id` and account email address, & we will investigate.
# Call analysis
> Summarize and evaluate calls automatically
## Overview
Call analysis automatically summarizes and evaluates every call for insights and quality control. As soon as a call ends, analysis is triggered in the background and typically completes within a few seconds. The system uses the latest version of Anthropic's Claude Sonnet (with OpenAI GPT-4o as fallback) to:
* Summarize the call
* Extract structured data
* Evaluate call success
Results are attached to the call record and can be viewed in the call instance dashboard or retrieved via the API. You can customize the analysis using prompts and schemas in your assistant's `analysisPlan`.
## Customization
You can customize the following properties in your assistant's `analysisPlan`:
### Summary prompt
* Used to create a concise summary of the call, stored in `call.analysis.summary`.
* **Default prompt:**
```text
You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences, if applicable.
```
* **Customize:**
```json
{
"summaryPrompt": "Custom summary prompt text"
}
```
* **Disable:**
```json
{
"summaryPrompt": ""
}
```
### Structured data prompt
* Extracts specific data from the call, stored in `call.analysis.structuredData`.
* **Default prompt:**
```text
You are an expert data extractor. You will be given a transcript of a call. Extract structured data per the JSON Schema.
```
* **Customize:**
```json
{
"structuredDataPrompt": "Custom structured data prompt text"
}
```
### Structured data schema
* Defines the format of extracted data using JSON Schema.
* **Customize:**
```json
{
"structuredDataSchema": {
"type": "object",
"properties": {
"field1": { "type": "string" },
"field2": { "type": "number" }
},
"required": ["field1", "field2"]
}
}
```
### Success evaluation prompt
* Used to determine if the call was successful, stored in `call.analysis.successEvaluation`.
* **Default prompt:**
```text
You are an expert call evaluator. You will be given a transcript of a call and the system prompt of the AI participant. Determine if the call was successful based on the objectives inferred from the system prompt.
```
* **Customize:**
```json
{
"successEvaluationPrompt": "Custom success evaluation prompt text"
}
```
* **Disable:**
```json
{
"successEvaluationPrompt": ""
}
```
### Success evaluation rubric
* Defines the criteria for evaluating call success. Options:
* `NumericScale`: 1 to 10
* `DescriptiveScale`: Excellent, Good, Fair, Poor
* `Checklist`: List of criteria
* `Matrix`: Grid of criteria and performance
* `PercentageScale`: 0% to 100%
* `LikertScale`: Strongly Agree to Strongly Disagree
* `AutomaticRubric`: Auto breakdown by criteria
* `PassFail`: true/false
* **Customize:**
```json
{
"successEvaluationRubric": "NumericScale"
}
```
### Combine prompts and rubrics
* You can combine prompts and rubrics for detailed instructions:
```json
{
"successEvaluationPrompt": "Evaluate the call based on these criteria:...",
"successEvaluationRubric": "Checklist"
}
```
## Results
* Once analysis is complete, results are attached to the call record.
* View results in the call instance dashboard or retrieve them via the API.
* Results include:
* Call summary
* Structured data
* Success evaluation and rubric
By customizing these properties, you can tailor call analysis to your needs and gain valuable insights from every call.
# Call recording
> Learn how to record calls and store them for quality assurance and analysis
## Overview
Vapi provides comprehensive call recording capabilities that allow you to capture, store, and analyze voice conversations for quality assurance, training, and compliance purposes.
**Call recording enables you to:**
* Monitor conversation quality and assistant performance
* Train and improve your voice AI models
* Ensure compliance with regulatory requirements
* Analyze customer interactions for insights
## Recording Configuration
### Enable Recording
You can enable call recording at the assistant level or per individual call:
```json title="Assistant Configuration"
{
"name": "Customer Support Assistant",
"recordingEnabled": true,
"model": {
"provider": "openai",
"model": "gpt-4"
},
"voice": {
"provider": "11labs",
"voiceId": "harry"
}
}
```
```json title="Per-Call Configuration"
{
"assistant": {
"name": "Support Agent"
},
"recordingEnabled": true,
"phoneNumberId": "your-phone-number-id"
}
```
### Recording Options
Configure recording behavior with these options:
* **`recordingEnabled`**: Enable or disable recording for this assistant/call
* **`recordingChannelCount`**: Number of audio channels to record (1 for mono, 2 for stereo)
* **`recordingFormat`**: Audio format for recordings (mp3, wav, etc.)
## Storage Options
### Default Storage
By default, Vapi stores recordings securely in the cloud:
* Recordings are encrypted at rest and in transit
* Access is controlled through your API credentials
* Recordings are automatically cleaned up based on your retention policy
### Custom Storage
For advanced use cases, you can configure custom storage:
```json title="S3 Storage Configuration"
{
"recordingEnabled": true,
"recordingPath": "https://your-bucket.s3.amazonaws.com/recordings/",
"recordingCredentials": {
"provider": "aws",
"region": "us-east-1",
"accessKeyId": "your-access-key",
"secretAccessKey": "your-secret-key"
}
}
```
```json title="Google Cloud Storage"
{
"recordingEnabled": true,
"recordingPath": "gs://your-bucket/recordings/",
"recordingCredentials": {
"provider": "gcp",
"serviceAccountKey": "your-service-account-json"
}
}
```
## Accessing Recordings
### Via Dashboard
1. Navigate to **Calls** in your Vapi dashboard
2. Select a specific call from the list
3. Click on the **Recording** tab to play or download the audio
### Via API
Retrieve recording URLs programmatically:
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const client = new VapiClient({ token: "your-api-key" });
// Get call details including recording URL
const call = await client.calls.get("call-id");
console.log("Recording URL:", call.recordingUrl);
```
## Privacy and Compliance
### Legal Considerations
**Important**: Call recording laws vary by jurisdiction. Ensure compliance with:
* **Consent requirements** - Inform participants about recording
* **Data protection** regulations (GDPR, CCPA, etc.)
* **Industry standards** (PCI DSS, HIPAA, etc.)
### Best Practices
* **Inform callers** about recording at the start of conversations
* **Secure storage** with encryption and access controls
* **Retention policies** to automatically delete old recordings
* **Access logs** to track who accesses recordings
Always comply with local laws regarding call recording. Some jurisdictions require explicit consent from all parties before recording.
## Recording Analysis
### Transcription
Recorded calls are automatically transcribed for analysis:
```json
{
"callId": "call-123",
"transcript": [
{
"role": "assistant",
"message": "Hello! How can I help you today?",
"time": 0.5
},
{
"role": "user",
"message": "I need help with my account",
"time": 3.2
}
],
"recordingUrl": "https://api.vapi.ai/recordings/call-123.mp3"
}
```
### Call Analysis
Use recorded data for insights:
* **Conversation flow** analysis
* **Response quality** evaluation
* **Customer satisfaction** metrics
* **Assistant performance** tracking
## FAQ
Yes, all recordings are automatically transcribed and available through the API and dashboard.
Default retention is 30 days. You can configure custom retention policies for your account.
Yes, you can enable/disable recording at both the assistant level and per individual call.
Call recording is available in all supported Vapi regions with local data residency options.
## Next Steps
* **[Call Analysis](/assistants/call-analysis)** - Analyze recorded conversations for insights
* **[Privacy Compliance](/security-and-privacy/GDPR)** - Ensure GDPR and privacy compliance
* **[API Reference](/api-reference/calls/create)** - Explore recording configuration options
# Introduction to Squads (Multi-Assistant Conversations)
> Use Squads to handle complex workflows and tasks.
Sometimes, complex workflows are easier to manage with multiple assistants.
You can think of each assistant in a Squad as a leg of a conversation tree.
For example, you might have one assistant for lead qualification, which transfers to another for booking an appointment if they’re qualified.
Prior to Squads you would put all functionality in one assistant, but Squads were added to break up the complexity of larger prompts into smaller specialized assistants with specific tools and fewer goals.
Squads enable calls to transfer assistants mid-conversation, while maintaining full conversation context.
View all configurable properties in the [API Reference](/api-reference/squads/create-squad).
## Usage
To use Squads, you can create a `squad` when starting a call and specify `members` as a list of assistants and destinations.
The first member is the assistant that will start the call, and assistants can be either persistent or transient.
Each assistant should be assigned the relevant assistant transfer destinations.
Transfers are specified by assistant name and are used when the model recognizes a specific trigger.
```json
{
"squad": {
"members": [
{
"assistantId": "information-gathering-assistant-id",
"assistantDestinations": [{
"type": "assistant",
"assistantName": "Appointment Booking",
"message": "Please hold on while I transfer you to our appointment booking assistant.",
"description": "Transfer the user to the appointment booking assistant after they say their name."
}],
},
{
"assistant": {
"name": "Appointment Booking",
...
},
}
]
}
}
```
## Best Practices
The following are some best practices for using Squads to reduce errors:
* Group assistants by closely related tasks
* Create as few assistants as possible to reduce complexity
* Make sure descriptions for transfers are clear and concise
# Configuring Inbound and Outbound Calls for Squads
> Configuring assistants for inbound/outbound calls.
This guide details how to set up and manage inbound and outbound call functionality within Squads, leveraging AI assistants.
### Key Concepts
* **Transient Assistant:** A temporary assistant configuration passed directly in the request payload.
* **Assistant ID:** A unique identifier referring to a pre-existing assistant configuration.
When using Assistant IDs, ensure the
`name`
property in the payload matches the associated assistant's name accurately.
### Inbound Call Configuration
When your server receives a request of type `assistant-request`, respond with a JSON payload structured as follows:
```json
{
"squad": {
"members": [
{
"assistant": {
"name": "Emma",
"model": { "model": "gpt-4o", "provider": "openai" },
"voice": { "voiceId": "emma", "provider": "azure" },
"transcriber": { "provider": "deepgram" },
"firstMessage": "Hi, I am Emma, what is your name?",
"firstMessageMode": "assistant-speaks-first"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Mary",
"message": "Please hold on while I transfer you to our appointment booking assistant Mary.",
"description": "Transfer the user to the appointment booking assistant."
}
]
},
{
"assistantId": "your-assistant-id"
}
]
}
}
```
**In this example:**
* The first `members` entry is a **transient assistant** (full configuration provided).
* The second `members` entry uses an **Assistant ID**.
* `assistantDestinations` defines how to **transfer the call** to another assistant.
### Outbound Call Configuration
To initiate an outbound call, send a POST request to the API endpoint /call/phone with a JSON payload structured as follows:
```json
{
"squad": {
"members": [
{
"assistant": {
"name": "Emma",
"model": { "model": "gpt-4o", "provider": "openai" },
"voice": { "voiceId": "emma", "provider": "azure" },
"transcriber": { "provider": "deepgram" },
"firstMessage": "Hi, I am Emma, what is your name?",
"firstMessageMode": "assistant-speaks-first"
},
"assistantDestinations": [
{
"type": "assistant",
"assistantName": "Mary",
"message": "Please hold on while I transfer you to our appointment booking assistant Mary.",
"description": "Transfer the user to the appointment booking assistant."
}
]
},
{
"assistantId": "your-assistant-id"
}
]
},
"customer": {
"number": "your-phone-number"
},
"phoneNumberId": "your-phone-number-id"
}
```
**Key points:**
* `customer.number` is the phone number to call.
* `phoneNumberId` is a unique identifier for the phone number (obtain this from your provider).
# Silent Transfers
* **The Problem**: In traditional AI call flows, when transferring from one agent to another, announcing the transfer verbally can confuse or annoy callers and disrupt the conversation's flow.
* **The Solution**: Silent transfers keep the call experience *uninterrupted*, so the user doesn’t know multiple assistants are involved. The conversation flows more naturally, boosting customer satisfaction.
If you want to allow your call flow to move seamlessly from one assistant to another *without* the caller hearing `Please hold while we transfer you` here’s what to do:
1. **Update the Destination Assistant’s First Message**
* Set the assistant's `firstMessage` to an *empty string*.
* Set the assistant's `firstMessageMode` to `assistant-speaks-first-with-model-generated-message`.
2. **Update the Squad's assistant destinations messages**
* For every `members[*].assistantDestinations[*]`, set the `message` property to an *empty string*.
3. **Trigger the Transfer from the Source Assistant**
* In that assistant’s prompt, include a line instructing it to transfer to the desired assistant:
```json
trigger the transferCall tool with 'assistantName' Assistant.
```
* Replace `'assistantName'` with the exact name of the next assistant.
4. **Direct the Destination Assistant’s Behavior**
* In that assistant’s prompt, include a line instructing it to *`Proceed directly to the Task section without any greetings or small talk.`*
* This ensures there’s no awkward greeting or “Hello!” when the next assistant begins speaking.
### **Example Usage Scenario**
* **HPMA (Main Assistant)** is talking to the customer. They confirm the order details and then quietly passes the conversation to **HPPA (Payment Assistant)**.
* **HPPA** collects payment details without the customer ever hearing, `We’re now transferring you to the Payment Assistant.` It feels like one continuous conversation.
* Once payment is done, **HPPA** transfers the call again—this time to **HPMA-SA (Main Sub Assistant)**—which takes over final shipping arrangements.
Everything happens smoothly behind the scenes!
## **Squad and Assistant Configurations**
Below are the key JSON examples you’ll need. These show how to structure your assistants and squads so they work together for silent transfers.
### **HP Payment Squad With SubAgent**
Make sure the `members[*].assistantDestinations[*].message` properties are set to an *empty string*.
```json
{
"members": [
{
"assistantId": "2d8e0d13-1b3c-4358-aa72-cf6204d6244e",
"assistantDestinations": [
{
"message": " ",
"description": "Transfer call to the payment agent",
"type": "assistant",
"assistantName": "HPPA"
}
]
},
{
"assistantId": "ad1c5347-bc32-4b31-8bb7-6ff5fcb131f4",
"assistantDestinations": [
{
"message": " ",
"description": "Transfer call to the main sub agent",
"type": "assistant",
"assistantName": "HPMA-SA"
}
]
},
{
"assistantId": "f1c258bc-4c8b-4c51-9b44-883ab5e40b2f",
"assistantDestinations": []
}
],
"name": "HP Payment Squad With SubAgent"
}
```
### **HPMA Assistant (Main Assistant)**
```json
{
"name": "HPMA",
"voice": {
"voiceId": "248be419-c632-4f23-adf1-5324ed7dbf1d",
"provider": "cartesia",
"fillerInjectionEnabled": false
},
"createdAt": "2024-11-04T17:15:08.980Z",
"updatedAt": "2024-11-30T13:04:58.401Z",
"model": {
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "[Identity]\nYou are the Main Assistant..."
}
],
"provider": "openai",
"maxTokens": 50,
"temperature": 0.3
},
"firstMessage": "",
"firstMessageMode": "assistant-speaks-first-with-model-generated-message",
"transcriber": {
"model": "nova-2",
"language": "en",
"provider": "deepgram"
},
"backchannelingEnabled": false,
"backgroundDenoisingEnabled": false,
"isServerUrlSecretSet": false
}
```
(Similar JSON information for the HPPA and HPMA-SA assistants can follow, just like in the original text.)
## **Assistant Prompts (In Plain Text)**
Each assistant has its own system prompt outlining identity, context, style, and tasks. These prompts ensure the conversation is smooth, customer-centric, and aligned with your call flow needs. Here’s a streamlined version for reference:
### **HPMA (Main Assistant Prompt)**
```
[Identity]
You are the Main Assistant, a friendly and helpful agent assisting customers
in purchasing widgets over the phone.
[Context]
You're engaged with the customer to book an appointment.
Stay focused on this context and provide relevant information.
Once connected to a customer, proceed to the Task section.
Do not invent information not drawn from the context.
Answer only questions related to the context.
[Style]
- Be polite and professional.
- Use a conversational and engaging tone.
- Keep responses concise and clear.
[Response Guidelines]
- Ask one question at a time and wait for the customer's response before
proceeding.
- Confirm the customer's responses when appropriate.
- Use simple language that is easy to understand.
- Never say the word 'function' nor 'tools' nor the name of the
Available functions.
- Never say ending the call.
- Never say transferring.
[Task]
1.Greet the customer and ask if they are interested in purchasing widgets.
- Wait for the customer's response.
2. If the customer is interested, ask for their name.
- Wait for the customer's response.
3.Ask how many widgets the customer would like to purchase.
- Wait for the customer's response.
4.Confirm the order details with the customer.
- trigger the transferCall tool with Payment `HPPA` Assistant.
```
### **HPPA (Payment Assistant Prompt)**
```
[Identity]
You are the Payment Assistant, operating in secure mode to collect payment information from customers safely and confidentially.
[Context]
You're engaged with the customer to collect payment details. Stay focused
on this context and provide relevant information.
Do not invent information not drawn from the context.
Answer only questions related to the context.
Once connected to a customer, proceed to the Task section without
any greetings or small talk.
[Style]
- Be professional and reassuring.
- Maintain confidentiality at all times.
- Speak clearly and calmly.
[Response Guidelines]
- Collect the customer's credit card number, expiration date, and CVV.
- Confirm each piece of information after it is provided.
- Ensure the customer feels secure during the transaction.
- Do not record or log any information.
- Never say the word 'function' nor 'tools' nor the name of the
Available functions.
- Never say ending the call.
- Never say transferring.
[Task]
1. Ask for the credit card number.
- Wait for the customer's response.
2. Ask for the expiration date of the card.
- Wait for the customer's response.
3. Ask for the CVV number.
- Wait for the customer's response.
4. Confirm that the payment has been processed successfully.
- trigger the transferCall tool with Payment `HPMA-SA` Assistant.
```
### **HPMA-SA (Main Sub Assistant Prompt)**
```
[Identity]
You are the Main Assistant, a friendly and helpful agent assisting customers
in purchasing widgets over the phone.
[Context]
You're engaged with the customer to book an appointment.
Stay focused on this context and provide relevant information.
Do not invent information not drawn from the context.
Answer only questions related to the context.
Once connected to a customer, proceed to the Task section without any greetings
or small talk.
[Style]
- Be professional and reassuring.
- Maintain confidentiality at all times.
- Speak clearly and calmly.
[Response Guidelines]
- Collect the customer's credit card number, expiration date, and CVV.
- Confirm each piece of information after it is provided.
- Ensure the customer feels secure during the transaction.
- Do not record or log any information.
- Never say the word 'function' nor 'tools' nor the name of the
Available functions.
- Never say ending the call.
- Never say transferring.
[Task]
1.Ask for the customer's shipping address to deliver the widgets.
- Wait for the customer's response.
2.Confirm the shipping address and provide an estimated delivery date.
3.Ask if the customer has any additional questions or needs further assistance.
- Wait for the customer's response.
4.Provide any additional information or assistance as needed.
5.Thank the customer for their purchase and end the call politely.
```
## **Conclusion**
By following these steps and examples, you can configure your call system to conduct **silent transfers** ensuring that callers experience a single, uninterrupted conversation. Each assistant does its job smoothly, whether it’s capturing payment, finalizing a shipping address, or collecting basic info.
Enjoy setting up your silent transfers!
# Outbound campaigns quickstart
> Build a simple personalized outbound campaign that conducts post-service feedback and follow-up calls to improve customer experience
## Overview
Build a simple personalized outbound campaign using Vapi that conducts post-service feedback and follow-up calls to improve customer experience and gather valuable insights from your customers.
**In this quickstart, you'll learn to:**
* Set up an outbound campaign with customer data
* Configure personalized feedback collection calls
* Launch and monitor campaign performance
* Access detailed call outcomes and analytics
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai)
* Phone number set up in your organization with a provider like Twilio (Vapi free numbers do not work for Outbound Campaigns)
* Recipient information ready in CSV format
* An existing Assistant configured in your account
***
## 1. Launch a Campaign
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click `Outbound Campaigns` in the left sidebar to access the campaigns section.
* Click **Create Campaign**
* Enter a **Campaign Name** (e.g., "Post-Service Feedback Campaign")
* Select **Campaign Type** based on your feedback collection needs
Select a phone number from your available numbers. This must be a number from your phone provider (like Twilio), not a Vapi free number.
Upload your customer list:
* Click **Manage Recipients**
* Upload your CSV file with customer information
* Review the recipient list for accuracy
* Follow [best practices](/outbound-campaigns/overview#required-information) on how to format your CSV file
Choose the Assistant that will conduct the feedback calls:
* Select from your existing Assistants
* Review all campaign settings
* Verify recipient count and Assistant configuration
* Click **Launch Campaign** to start the outbound calls
***
## 2. Monitor Your Campaign
Once launched, monitor your campaign performance in real-time through the Campaign Dashboard.
* View completion rates and call statuses
* Track progress of scheduled campaigns
* Cancel campaigns you no longer want to run
See call logs for each customer contact, including:
* Call duration and outcome
* Transcript and recordings
# Outbound campaigns overview
> Learn how to efficiently schedule calls, manage recipients, analyze performance metrics, and review detailed call logs and transcripts with Vapi's Outbound Call Campaigns
## Overview
Outbound Call Campaigns allow users to efficiently create, execute, and manage outbound phone campaigns directly within the Vapi Dashboard. It enables users to efficiently schedule calls, manage recipients, analyze performance metrics, and review detailed call logs and transcripts.
## Key benefits
* **Intuitive UI**: Quickly set up campaigns in an easy-to-follow setup page
* **Personalized**: Use dynamic variables to personalized outreach
* **Analytics**: Get real-time monitoring and detailed analysis of call performance and outcomes
## Common use cases
* **Conversion Optimization**: Re-engage potential customers via targeted follow-up calls for abandoned carts
* **Appointment Reminders**: Reduce missed appointments with timely reminder calls
* **Customer Satisfaction**: Conduct post-service feedback and follow-up calls to enhance customer experiences
* **Subscription Renewals**: Facilitate timely renewals with proactive call reminders
* **Insurance Updates**: Verify and update policy details through targeted calls
## Campaign setup process
Outbound Call Campaigns follow a structured process:
Set campaign name and type.
Choose outbound phone numbers (recommend Twilio).
Upload recipients via CSV, supported with dynamic variables.
Select an existing assistant to handle the call.
Review campaign and initiate or schedule calls for later.
## Campaign analytics
The Campaign Dashboard provides comprehensive insights:
* **Campaign Overview**: Monitor status, completed calls, pick up rate, and voicemail
* **Detailed Call Reports**: Access individual call details, customer information, call duration, outcome statuses, and transcripts
## Required information
Outbound Campaigns only require a number to work. `number` column is required and needs to be spelled in lowercase.
| number | |
| ------------ | - |
| +14151231234 | |
| +14153455678 | |
Phone numbers must be formatted in E.164 format: \[+] \[country code] \[subscriber number including area code]
* Example: +14151234567
* Maximum 15 digits total
* No spaces or special characters
## Tips for Clean Data
* Use UTF-8 encoding when saving your CSV.
* Avoid blank rows or duplicated headers.
* Double-check that your column names match the variables used in your assistant.
## Avoiding Spam
To maximize call answer rates and establish trust with recipients, you should implement proper caller identification and trusted calling standards. This involves several key components that work together to verify your identity and build caller reputation.
Learn more about [Trusted Calling](/calls/outbound-calling#trusted-calling-and-caller-id)
## Dynamic variables
Outbound Campaigns allows users to specify dynamic variables to pass to Assistants via additional columns in the CSV file. Outbound Campaigns can take one more additional columns.
| number | name | customer\_issue |
| ------------ | ---- | --------------- |
| +14151231234 | John | password reset |
| +14153455678 | Mary | address update |
`{{name}}` and `{{customer_issue}}` can be used in the Assistant prompt as dynamic variables, based on this CSV file.
* Column names cannot have spaces. Use `{{customer_issue}}` instead of `{{customer issue}}`
* Column names must start with a letter
* Users can use the same [Default Variables](/assistants/dynamic-variables#default-variables) as they can within Assistants
## Concurrency
Check concurrency limits in your Vapi organization. If your org has a concurrency limit of 10, a maximum of 10 calls will be started at a single time. The rest of the calls will be queued and retried a few minutes later as your concurrency slots become available. To increase call rate, you need you increase your Vapi org concurrency limit.
Note that concurrency limits are on the Vapi side. Your telephony provider (e.g. Twilio) may have other rate limits.
# Chat quickstart
> Build your first text-based conversation with a Vapi assistant in 5 minutes
## Overview
Build a customer service chat bot that can handle text-based conversations through your application. Perfect for adding AI chat to websites, mobile apps, or messaging platforms.
**What You'll Build:**
* A working chat integration that responds to user messages
* Context-aware conversations that remember previous messages
* Both one-shot and multi-turn conversation patterns
**Agent Capabilities:**
* Instant text responses without voice processing
* Maintains conversation context across multiple messages
* Compatible with existing OpenAI workflows
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/)
* An existing assistant or willingness to create one
* Basic knowledge of making API requests
## Scenario
We'll create a customer support chat for "TechFlow", a software company that wants to handle common questions via text chat before escalating to human agents.
***
## 1. Get Your API Credentials
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click on your profile in the top right, then select `Vapi API Keys`.
Copy your Private API Key. You'll need this for all chat requests.
Keep this key secure - never expose it in client-side code.
***
## 2. Create or Select an Assistant
In your Vapi dashboard, click `Assistants` in the left sidebar.
* Click `Create Assistant` if you need a new one
* Select `Blank Template` as your starting point
* Name it `TechFlow Support`
* Set the first message to: `Hello! I'm here to help with TechFlow questions. What can I assist you with today?`
Update the system prompt to:
```txt title="System Prompt" maxLines=8
You are a helpful customer support agent for TechFlow, a software company.
Your role:
- Answer common questions about our products
- Help troubleshoot basic issues
- Escalate complex problems to human agents
Keep responses concise and helpful. Always maintain a friendly, professional tone.
```
After publishing, copy the Assistant ID from the URL or assistant details. You'll need this for API calls.
***
## 3. Send Your First Chat Message
Replace `YOUR_API_KEY` and `your-assistant-id` with your actual values:
```bash title="First Chat Request"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "Hi, I need help with my TechFlow account"
}'
```
You should receive a JSON response like:
```json title="Chat Response"
{
"id": "chat_abc123",
"assistantId": "your-assistant-id",
"messages": [
{
"role": "user",
"content": "Hi, I need help with my TechFlow account"
}
],
"output": [
{
"role": "assistant",
"content": "I'd be happy to help with your TechFlow account! What specific issue are you experiencing?"
}
],
"createdAt": "2024-01-15T09:30:00Z",
"updatedAt": "2024-01-15T09:30:00Z"
}
```
***
## 4. Build a Multi-Turn Conversation
Use the `previousChatId` from the first response to maintain context:
```bash title="Follow-up Message"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"previousChatId": "chat_abc123",
"input": "I forgot my password and can't log in"
}'
```
Send another message to verify the assistant remembers the conversation:
```bash title="Context Test"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"previousChatId": "chat_abc123",
"input": "What was my original question?"
}'
```
***
## 5. Pass Dynamic Variables
In your assistant's system prompt, you can reference dynamic variables using `{{variableName}}` syntax:
```txt title="System Prompt with Variables"
You are a helpful customer support agent for {{companyName}}.
Your role:
- Answer questions about {{companyName}}'s products
- Help customers with their {{serviceType}} needs
- Escalate to human agents when needed
Current customer tier: {{customerTier}}
```
Use `assistantOverrides.variableValues` to pass dynamic data:
```bash title="Chat Request with Variables"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "I need help with my account",
"assistantOverrides": {
"variableValues": {
"companyName": "TechFlow Solutions",
"serviceType": "software",
"customerTier": "Premium"
}
}
}'
```
***
## 6. Integrate with TypeScript
Here's a TypeScript function you can use in your application:
```typescript title="chat.ts"
interface ChatMessage {
role: 'user' | 'assistant';
content: string;
}
interface ChatApiResponse {
id: string;
assistantId: string;
messages: ChatMessage[];
output: ChatMessage[];
createdAt: string;
updatedAt: string;
orgId?: string;
sessionId?: string;
name?: string;
}
interface ChatResponse {
chatId: string;
response: string;
fullData: ChatApiResponse;
}
async function sendChatMessage(
message: string,
previousChatId?: string
): Promise {
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistantId: 'your-assistant-id',
input: message,
...(previousChatId && { previousChatId })
})
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const chat: ChatApiResponse = await response.json();
return {
chatId: chat.id,
response: chat.output[0].content,
fullData: chat
};
}
// Usage example
const firstMessage = await sendChatMessage("Hello, I need help");
console.log(firstMessage.response);
const followUp = await sendChatMessage("Tell me more", firstMessage.chatId);
console.log(followUp.response);
```
Run your TypeScript code to verify the chat integration works correctly.
***
## 7. Test Your Chat Bot
Try these test cases to ensure your chat bot works correctly:
```bash title="Test Case 1: General Question"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "What are your business hours?"
}'
```
```bash title="Test Case 2: Technical Issue"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "My app keeps crashing when I try to export data"
}'
```
Send follow-up messages using `previousChatId` to ensure context is maintained.
## Limitations
**Current chat functionality limitations:**
* "Query" tool for knowledge-base searches is not yet supported
* Server webhook events (status updates, end-of-call reports, etc.) are not supported
## Next Steps
Take your chat bot to the next level:
* **[Streaming responses](/chat/streaming)** - Add real-time typing indicators and progressive responses
* **[Non-streaming responses](/chat/non-streaming)** - Learn about sessions and complex conversation flows
* **[Session management](/chat/session-management)** - Learn advanced context management with sessions and previousChatId
* **[OpenAI compatibility](/chat/openai-compatibility)** - Integrate with existing OpenAI workflows
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Streaming chat
> Build real-time chat experiences with token-by-token responses like ChatGPT
## Overview
Build a real-time chat interface that displays responses as they're generated, creating an engaging user experience similar to ChatGPT. Perfect for interactive applications where users expect immediate visual feedback.
**What You'll Build:**
* Real-time streaming chat interface with progressive text display
* Context management across multiple messages
* Basic TypeScript implementation ready for production use
## Prerequisites
* Completed [Chat quickstart](/chat/quickstart) tutorial
* Basic knowledge of TypeScript/JavaScript and async/await
## Scenario
We'll enhance the TechFlow support chat from the quickstart to provide real-time streaming responses. Users will see text appear progressively as the AI generates it.
***
## 1. Enable Streaming in Your Requests
Modify your chat request to enable streaming by adding `"stream": true`:
```bash title="Streaming Chat Request"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "Explain how to set up API authentication in detail",
"stream": true
}'
```
Instead of a single JSON response, you'll receive Server-Sent Events (SSE):
```typescript title="SSE Event Format"
// Example SSE events received:
data: {"id":"stream_123","path":"chat.output[0].content","delta":"Hello"}
data: {"id":"stream_123","path":"chat.output[0].content","delta":" there!"}
data: {"id":"stream_123","path":"chat.output[0].content","delta":" How can"}
data: {"id":"stream_123","path":"chat.output[0].content","delta":" I help?"}
// TypeScript interface for SSE events:
interface SSEEvent {
id: string;
path: string;
delta: string;
}
```
***
## 2. Basic TypeScript Streaming Implementation
Here's a basic streaming implementation:
```typescript title="streaming-chat.ts"
async function streamChatMessage(
message: string,
previousChatId?: string
): Promise {
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistantId: 'your-assistant-id',
input: message,
stream: true,
...(previousChatId && { previousChatId })
})
});
const reader = response.body?.getReader();
if (!reader) throw new Error('No reader available');
const decoder = new TextDecoder();
let fullResponse = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('\n').filter(line => line.trim());
for (const line of lines) {
if (line.startsWith('data: ')) {
const data = JSON.parse(line.slice(6));
if (data.path && data.delta) {
fullResponse += data.delta;
process.stdout.write(data.delta);
}
}
}
}
return fullResponse;
}
```
Try it out:
```typescript title="Test Streaming"
const response = await streamChatMessage("Explain API rate limiting in detail");
console.log('\nComplete response:', response);
```
***
## 3. Streaming with Context Management
Maintain context across multiple streaming messages:
```typescript title="context-streaming.ts"
async function createStreamingConversation() {
let lastChatId: string | undefined;
async function sendMessage(input: string): Promise {
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistantId: 'your-assistant-id',
input: input,
stream: true,
...(lastChatId && { previousChatId: lastChatId })
})
});
const reader = response.body?.getReader();
if (!reader) throw new Error('No reader available');
const decoder = new TextDecoder();
let fullContent = '';
let currentChatId: string | undefined;
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
const lines = chunk.split('\n').filter(line => line.trim());
for (const line of lines) {
if (line.startsWith('data: ')) {
const event = JSON.parse(line.slice(6));
if (event.id && !currentChatId) {
currentChatId = event.id;
}
if (event.path && event.delta) {
fullContent += event.delta;
process.stdout.write(event.delta);
}
}
}
}
if (currentChatId) {
lastChatId = currentChatId;
}
return fullContent;
}
return { sendMessage };
}
```
```typescript title="Test Context"
const conversation = await createStreamingConversation();
await conversation.sendMessage("My name is Alice");
console.log('\n---');
await conversation.sendMessage("What's my name?"); // Should remember Alice
```
***
## Next Steps
Enhance your streaming chat further:
* **[OpenAI compatibility](/chat/openai-compatibility)** - Use OpenAI SDK for streaming with familiar syntax
* **[Non-streaming patterns](/chat/non-streaming)** - Learn about sessions and complex conversation management
* **[Session management](/chat/session-management)** - Learn about context management with sessions and previousChatId in streaming
* **[Add tools](/tools)** - Enable your assistant to call external APIs while streaming
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Non-streaming chat
> Build reliable chat integrations with complete response patterns for batch processing and simple UIs
## Overview
Build a chat integration that receives complete responses after processing, perfect for batch processing, simple UIs, or when you need the full response before proceeding. Ideal for integrations where real-time display isn't essential.
**What You'll Build:**
* Simple request-response chat patterns with immediate complete responses
* Context management using `previousChatId` for linked conversations
* Basic integration with predictable response timing
For comprehensive context management options including sessions, see **[Session management](/chat/session-management)**.
## Prerequisites
* Completed [Chat quickstart](/chat/quickstart) tutorial
* Understanding of basic HTTP requests and JSON handling
* Familiarity with JavaScript/TypeScript promises or async/await
## Scenario
We'll build a help desk system for "TechFlow" that processes support messages through text chat and maintains conversation history using `previousChatId`.
***
## 1. Basic Non-Streaming Implementation
Start with a basic non-streaming chat implementation:
```bash title="Basic Non-Streaming Request"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "I need help resetting my password"
}'
```
Non-streaming responses come back as complete JSON objects:
```json title="Complete Chat Response"
{
"id": "chat_123456",
"orgId": "org_789012",
"assistantId": "assistant_345678",
"name": "Password Reset Help",
"sessionId": "session_901234",
"messages": [
{
"role": "user",
"content": "I need help resetting my password"
}
],
"output": [
{
"role": "assistant",
"content": "I can help you reset your password. First, let me verify your account information..."
}
],
"createdAt": "2024-01-15T09:30:00Z",
"updatedAt": "2024-01-15T09:30:01Z"
}
```
Create a reusable function for non-streaming chat:
```typescript title="non-streaming-chat.ts"
async function sendChatMessage(
message: string,
previousChatId?: string
): Promise<{ chatId: string; response: string }> {
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistantId: 'your-assistant-id',
input: message,
...(previousChatId && { previousChatId })
})
});
const chat = await response.json();
return {
chatId: chat.id,
response: chat.output[0].content
};
}
```
***
## 2. Context Management with previousChatId
Use `previousChatId` to maintain context across multiple chats:
```typescript title="conversation-chain.ts"
async function createConversation() {
let lastChatId: string | undefined;
async function sendMessage(input: string): Promise {
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistantId: 'your-assistant-id',
input: input,
...(lastChatId && { previousChatId: lastChatId })
})
});
const chat = await response.json();
lastChatId = chat.id;
return chat.output[0].content;
}
return { sendMessage };
}
// Usage
const conversation = await createConversation();
const response1 = await conversation.sendMessage("Hello, I'm Alice");
console.log(response1);
const response2 = await conversation.sendMessage("What's my name?");
console.log(response2); // Should remember "Alice"
```
***
## 3. Custom Assistant Configuration
Instead of pre-created assistants, define configuration per request:
```bash title="Custom Assistant Request"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "I need help with enterprise features",
"assistant": {
"model": {
"provider": "openai",
"model": "gpt-4o",
"temperature": 0.7,
"messages": [
{
"role": "system",
"content": "You are a helpful technical support agent specializing in enterprise features."
}
]
}
}
}'
```
Build different chat handlers for different types of requests:
```typescript title="specialized-handlers.ts"
async function createSpecializedChat(systemPrompt: string) {
return async function(userInput: string): Promise {
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
input: userInput,
assistant: {
model: {
provider: 'openai',
model: 'gpt-4o',
temperature: 0.3,
messages: [{ role: 'system', content: systemPrompt }]
}
}
})
});
const chat = await response.json();
return chat.output[0].content;
};
}
const technicalSupport = await createSpecializedChat(
"You are a technical support specialist. Ask clarifying questions and provide step-by-step troubleshooting."
);
const billingSupport = await createSpecializedChat(
"You are a billing support specialist. Be precise about billing terms and always verify account information."
);
// Usage
const techResponse = await technicalSupport("My API requests are returning 500 errors");
const billingResponse = await billingSupport("I was charged twice this month");
```
***
## Next Steps
Enhance your non-streaming chat system further:
* **[Add streaming capabilities](/chat/streaming)** - Upgrade to real-time responses for better UX
* **[OpenAI compatibility](/chat/openai-compatibility)** - Use familiar OpenAI SDK patterns
* **[Integrate tools](/tools)** - Enable your assistant to call external APIs and databases
* **[Session management](/chat/session-management)** - Learn about advanced context management with sessions
* **[Add voice capabilities](/calls/outbound-calling)** - Extend your text chat to voice interactions
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# OpenAI compatibility
> Seamlessly migrate existing OpenAI integrations to Vapi with zero code changes
## Overview
Migrate your existing OpenAI chat applications to Vapi without changing a single line of code. Perfect for teams already using OpenAI SDKs, third-party tools expecting OpenAI API format, or developers who want to leverage existing OpenAI workflows.
**What You'll Build:**
* Drop-in replacement for OpenAI chat endpoints using Vapi assistants
* Migration path from OpenAI to Vapi with existing codebases
* Integration with popular frameworks like LangChain and Vercel AI SDK
* Production-ready server implementations with both streaming and non-streaming
## Prerequisites
* Completed [Chat quickstart](/chat/quickstart) tutorial
* Existing OpenAI integration or familiarity with OpenAI SDK
## Scenario
We'll migrate "TechFlow's" existing OpenAI-powered customer support chat to use Vapi assistants, maintaining all existing functionality while gaining access to Vapi's advanced features like custom voices and tools.
***
## 1. Quick Migration Test
If you don't already have it, install the OpenAI SDK:
```bash title="npm"
npm install openai
```
```bash title="yarn"
yarn add openai
```
```bash title="pnpm"
pnpm add openai
```
```bash title="bun"
bun add openai
```
Use your existing OpenAI code with minimal changes:
```bash title="Test OpenAI Compatibility"
curl -X POST https://api.vapi.ai/chat/responses \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"input": "Hello, I need help with my account",
"stream": false,
"assistantId": "your-assistant-id"
}'
```
The response follows OpenAI's structure with Vapi enhancements:
```json title="OpenAI-Compatible Response"
{
"id": "response_abc123",
"object": "chat.response",
"created": 1642678392,
"model": "gpt-4o",
"output": [
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello! I'd be happy to help with your account. What specific issue are you experiencing?"
}
]
}
],
"usage": {
"prompt_tokens": 12,
"completion_tokens": 23,
"total_tokens": 35
}
}
```
***
## 2. Migrate Existing OpenAI Code
Change only the base URL and API key in your existing code:
```typescript title="Before (OpenAI)"
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: 'your-openai-api-key'
});
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello!' }],
stream: true
});
```
### With Vapi (No Code Changes)
```typescript title="After (Vapi)"
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: 'YOUR_VAPI_API_KEY',
baseURL: 'https://api.vapi.ai/chat',
});
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: 'Hello!' }],
stream: true
});
```
Change `chat.completions.create` to `responses.create` and add `assistantId`:
```typescript title="Before (OpenAI Chat Completions)"
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [
{ role: 'user', content: 'What is the capital of France?' }
],
stream: false
});
console.log(response.choices[0].message.content);
```
```typescript title="After (Vapi Compatibility)"
const response = await openai.responses.create({
model: 'gpt-4o',
input: 'What is the capital of France?',
stream: false,
assistantId: 'your-assistant-id'
});
console.log(response.output[0].content[0].text);
```
Run your updated code to verify the migration works:
```typescript title="migration-test.ts"
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: 'YOUR_VAPI_API_KEY',
baseURL: 'https://api.vapi.ai/chat'
});
async function testMigration() {
try {
const response = await openai.responses.create({
model: 'gpt-4o',
input: 'Hello, can you help me troubleshoot an API issue?',
stream: false,
assistantId: 'your-assistant-id'
});
console.log('Migration successful!');
console.log('Response:', response.output[0].content[0].text);
} catch (error) {
console.error('Migration test failed:', error);
}
}
testMigration();
```
***
## 3. Implement Streaming with OpenAI SDK
Update your streaming code to use Vapi's streaming format:
```bash title="Streaming via curl"
curl -X POST https://api.vapi.ai/chat/responses \
-H "Authorization: Bearer YOUR_VAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"input": "Explain how machine learning works in detail",
"stream": true,
"assistantId": "your-assistant-id"
}'
```
Adapt your existing streaming implementation:
```typescript title="streaming-migration.ts"
async function streamWithVapi(userInput: string): Promise {
const stream = await openai.responses.create({
model: 'gpt-4o',
input: userInput,
stream: true,
assistantId: 'your-assistant-id'
});
let fullResponse = '';
const reader = stream.body?.getReader();
if (!reader) return fullResponse;
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
// Parse and process SSE events
const lines = chunk.split('\n').filter(line => line.trim());
for (const line of lines) {
if (line.startsWith('data: ')) {
try {
const event = JSON.parse(line.slice(6));
if (event.path && event.delta) {
process.stdout.write(event.delta);
fullResponse += event.delta;
}
} catch (e) {
console.error('Invalid JSON line:', line);
continue;
}
}
}
}
console.log('\n\nComplete response received.');
return fullResponse;
}
streamWithVapi('Write a detailed explanation of REST APIs');
```
Implement context management using Vapi's approach:
```typescript title="context-management.ts"
function createContextualChatSession(apiKey: string, assistantId: string) {
const openai = new OpenAI({
apiKey: apiKey,
baseURL: 'https://api.vapi.ai/chat'
});
let lastChatId: string | null = null;
async function sendMessage(input: string, stream: boolean = false) {
const requestParams = {
model: 'gpt-4o',
input: input,
stream: stream,
assistantId: assistantId,
...(lastChatId && { previousChatId: lastChatId })
};
const response = await openai.responses.create(requestParams);
if (!stream) {
lastChatId = response.id;
return response.output[0].content[0].text;
}
return response;
}
return { sendMessage };
}
// Usage example
const session = createContextualChatSession('YOUR_VAPI_API_KEY', 'your-assistant-id');
const response1 = await session.sendMessage("My name is Sarah and I'm having login issues");
console.log('Response 1:', response1);
const response2 = await session.sendMessage("What was my name again?");
console.log('Response 2:', response2); // Should remember "Sarah"
```
***
## 4. Framework Integrations
Use Vapi with LangChain's OpenAI integration:
```typescript title="langchain-integration.ts"
import { ChatOpenAI } from "langchain/chat_models/openai";
import { HumanMessage } from "langchain/schema";
const chat = new ChatOpenAI({
openAIApiKey: "YOUR_VAPI_API_KEY",
configuration: {
baseURL: "https://api.vapi.ai/chat"
},
modelName: "gpt-4o",
streaming: false
});
async function chatWithVapi(message: string, assistantId: string): Promise {
const response = await fetch('https://api.vapi.ai/chat/responses', {
method: 'POST',
headers: {
'Authorization': `Bearer YOUR_VAPI_API_KEY`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-4o',
input: message,
assistantId: assistantId,
stream: false
})
});
const data = await response.json();
return data.output[0].content[0].text;
}
// Usage
const response = await chatWithVapi(
"What are the best practices for API design?",
"your-assistant-id"
);
console.log(response);
```
Use Vapi with Vercel's AI SDK:
```typescript title="vercel-ai-integration.ts"
import { openai } from '@ai-sdk/openai';
import { generateText, streamText } from 'ai';
const vapiOpenAI = openai({
apiKey: 'YOUR_VAPI_API_KEY',
baseURL: 'https://api.vapi.ai/chat'
});
// Non-streaming text generation
async function generateWithVapi(prompt: string, assistantId: string): Promise {
const response = await fetch('https://api.vapi.ai/chat/responses', {
method: 'POST',
headers: {
'Authorization': `Bearer YOUR_VAPI_API_KEY`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-4o',
input: prompt,
assistantId: assistantId,
stream: false
})
});
const data = await response.json();
return data.output[0].content[0].text;
}
// Streaming implementation
async function streamWithVapi(prompt: string, assistantId: string): Promise {
const response = await fetch('https://api.vapi.ai/chat/responses', {
method: 'POST',
headers: {
'Authorization': `Bearer YOUR_VAPI_API_KEY`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: 'gpt-4o',
input: prompt,
assistantId: assistantId,
stream: true
})
});
const reader = response.body?.getReader();
if (!reader) return;
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value);
// Parse and process SSE events
const lines = chunk.split('\n').filter(line => line.trim());
for (const line of lines) {
if (line.startsWith('data: ')) {
try {
const event = JSON.parse(line.slice(6));
if (event.path && event.delta) {
process.stdout.write(event.delta);
}
} catch (e) {
console.error('Invalid JSON line:', line);
continue;
}
}
}
}
}
// Usage examples
const text = await generateWithVapi(
"Explain the benefits of microservices architecture",
"your-assistant-id"
);
console.log(text);
```
Build a simple server that exposes Vapi through OpenAI-compatible endpoints:
```typescript title="simple-server.ts"
import express from 'express';
const app = express();
app.use(express.json());
app.post('/v1/chat/completions', async (req, res) => {
const { messages, model, stream = false, assistant_id } = req.body;
if (!assistant_id) {
return res.status(400).json({
error: 'assistant_id is required for Vapi compatibility'
});
}
const lastMessage = messages[messages.length - 1];
const input = lastMessage.content;
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
assistantId: assistant_id,
input: input,
stream: stream
})
});
if (stream) {
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
const reader = response.body?.getReader();
if (!reader) {
return res.status(500).json({ error: 'Failed to get stream reader' });
}
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) {
res.write('data: [DONE]\n\n');
res.end();
break;
}
const chunk = decoder.decode(value);
res.write(chunk);
}
} else {
const chat = await response.json();
const openaiResponse = {
id: chat.id,
object: 'chat.completion',
created: Math.floor(Date.now() / 1000),
model: model || 'gpt-4o',
choices: [{
index: 0,
message: {
role: 'assistant',
content: chat.output[0].content
},
finish_reason: 'stop'
}]
};
res.json(openaiResponse);
}
});
app.listen(3000, () => {
console.log('Vapi-OpenAI compatibility server running on port 3000');
});
```
***
## Next Steps
Enhance your migrated system:
* **[Explore Vapi-specific features](/chat/quickstart)** - Leverage advanced assistant capabilities
* **[Add voice capabilities](/calls/outbound-calling)** - Extend beyond text to voice interactions
* **[Integrate tools](/tools/custom-tools)** - Give your assistant access to external APIs
* **[Optimize for streaming](/chat/streaming)** - Improve real-time user experience
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Session management
> Maintain conversation context using previousChatId vs sessionId
## Overview
Vapi provides two approaches for maintaining conversation context across multiple chat interactions.
**Two Context Management Methods:**
* **`previousChatId`** - Links individual chats in sequence
* **`sessionId`** - Groups multiple chats under a persistent session
`previousChatId` and `sessionId` are **mutually exclusive**. You cannot use both in the same request.
## Prerequisites
* Completed [Chat quickstart](/chat/quickstart) tutorial
* Basic understanding of chat requests and responses
***
## Method 1: Using previousChatId
Link chats together by referencing the ID of the previous chat.
```bash title="Initial Chat"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"input": "Hello, my name is Sarah"
}'
```
```json title="Response"
{
"id": "chat_abc123",
"output": [{"role": "assistant", "content": "Hello Sarah!"}]
}
```
```bash title="Follow-up Chat"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"assistantId": "your-assistant-id",
"previousChatId": "chat_abc123",
"input": "What was my name again?"
}'
```
Here's a TypeScript implementation of the conversation chain:
```typescript title="conversation-chain.ts"
function createConversationChain() {
let lastChatId: string | null = null;
return async function sendMessage(assistantId: string, input: string) {
const requestBody = {
assistantId,
input,
...(lastChatId && { previousChatId: lastChatId })
};
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(requestBody)
});
const chat = await response.json();
lastChatId = chat.id;
return chat.output[0].content;
};
}
// Usage
const sendMessage = createConversationChain();
await sendMessage("asst_123", "Hi, I'm Alice");
await sendMessage("asst_123", "What's my name?"); // Remembers Alice
```
***
## Method 2: Using sessionId
Create a persistent session that groups multiple chats.
```bash title="Create Session"
curl -X POST https://api.vapi.ai/session \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"assistantId": "your-assistant-id"}'
```
```json title="Session Response"
{
"id": "session_xyz789",
"assistantId": "your-assistant-id"
}
```
```bash title="First Chat in Session"
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "session_xyz789",
"input": "Hello, I need help with billing"
}'
```
Here's a TypeScript implementation of the session manager:
```typescript title="session-manager.ts"
async function createSession(assistantId: string) {
const response = await fetch('https://api.vapi.ai/session', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ assistantId })
});
const session = await response.json();
return function sendMessage(input: string) {
return fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ sessionId: session.id, input })
})
.then(response => response.json())
.then(chat => chat.output[0].content);
};
}
// Usage
const sendMessage = await createSession("asst_123");
await sendMessage("I need help with my account");
await sendMessage("What was my first question?"); // Remembers context
```
***
## When to use each approach
Use `previousChatId` when:
* Dealing with simple back-and-forth conversations
* Looking for a minimal setup
Use `sessionId` when:
* Building complex multi-step workflows
* Long-running conversations
* Error resilience needed
Sessions are tied to one assistant. You cannot specify `assistantId` when using `sessionId`.
***
## Multi-Assistant Workflows
For workflows with multiple assistants, create separate sessions for each assistant.
```typescript title="multi-assistant-workflow.ts"
function createMultiAssistantWorkflow() {
const sessions = new Map();
return async function sendToAssistant(assistantId: string, input: string) {
let sessionId = sessions.get(assistantId);
if (!sessionId) {
const response = await fetch('https://api.vapi.ai/session', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ assistantId })
});
const session = await response.json();
sessionId = session.id;
sessions.set(assistantId, sessionId);
}
const response = await fetch('https://api.vapi.ai/chat', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.VAPI_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ sessionId, input })
});
const chat = await response.json();
return chat.output[0].content;
};
}
// Usage
const sendToAssistant = createMultiAssistantWorkflow();
await sendToAssistant("support_agent", "I have a billing issue");
await sendToAssistant("billing_agent", "Can you help with this?");
```
***
## Next Steps
* **[Streaming responses](/chat/streaming)** - Add real-time responses to session-managed chats
* **[OpenAI compatibility](/chat/openai-compatibility)** - Use familiar OpenAI patterns with sessions
* **[Custom tools](/tools/custom-tools)** - Give assistants access to external APIs within sessions
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Web widget
> Add AI chat and voice capabilities to any website with a simple embeddable 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
View the complete source code and examples on [GitHub](https://github.com/VapiAI/client-sdk-react).
## Prerequisites
* A [Vapi account](https://dashboard.vapi.ai/) with a public API key
* 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
Go to [dashboard.vapi.ai](https://dashboard.vapi.ai) and log in to your account.
Click on your profile in the top right, then select `Vapi API Keys`.
Copy your **Public API Key**. This is safe to use in client-side code.
Unlike private keys, public keys are safe to expose in your website code.
Navigate to `Assistants` in the left sidebar and copy the ID of the assistant you want to use.
***
## 2. Install the Widget
Add the widget script to your HTML page:
```html title="index.html"
Your Website
```
Install the React package and use it as a component:
```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
```
```tsx title="App.tsx"
import { VapiWidget } from '@vapi-ai/client-sdk-react';
function App() {
return (
{/* Your app content */}
);
}
```
***
## 3. Configure Widget Modes
The widget supports two interaction modes:
**Voice Mode** - Voice-only conversations
```html
```
**Chat Mode** - Text-only conversations
```html
```
Open your website and click the floating widget button to test the integration.
***
## 4. Customize Appearance
Customize the widget to match your website's design:
```html title="Custom Styling"
```
Set custom text for better user experience:
```html title="Custom Labels"
```
***
## 5. Handle Events and Callbacks
Handle widget events to integrate with your application:
```html title="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 (
);
}
```
***
## 6. Advanced Configuration
Configure the assistant directly without pre-creating it:
The `assistant` configuration is only supported in **voice mode**. For chat mode, use `assistant-id` with optional `assistant-overrides`.
```html title="Inline Assistant Configuration"
```
Modify existing assistant behavior with overrides:
```html title="Assistant Overrides"
```
Implement consent requirements for compliance:
```html title="Consent Management"
```
***
## 7. Production Considerations
Consider these optimizations for production:
```html title="Performance Optimizations"
```
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.');
}
});
});
```
***
## 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) |
You must provide either `assistant-id`, `assistant`, or both `assistant-id` and `assistant-overrides`. The `assistant` prop is only supported in voice mode.
### 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
## 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
* **[Custom tools](/tools/custom-tools)** - Give your assistant access to external APIs
* **[Assistant customization](/assistants)** - Fine-tune your assistant's behavior
The widget automatically handles microphone permissions, audio processing, and cross-browser compatibility. For custom implementations, consider using the [Web SDK](/sdk/web) directly.
Need help? Chat with the team on our [Discord](https://discord.com/invite/pUFNcf2WmH) or mention us on [X/Twitter](https://x.com/Vapi_AI).
# Server URLs
> Learn how to set up your server to receive and respond to messages from Vapi.
Server URLs allow your application to **receive data** & **communicate with Vapi** during conversations. Conversation events can include:
* **Status Updates:** updates on the status of a call
* **Transcript Updates**: call transcripts
* **Function Calls:** payloads delivered when your assistant wants certain actions executed
* **Assistant Requests:** in certain circumstances, Vapi may ping your server to get dynamic configuration for an assistant handling a specific call
* **End of Call Report:** call summary data at the end of a call
* **Hang Notifications:** get notified when your assistant fails to reply for a certain amount of time
In our [quickstart guides](/quickstart) we learned how to setup a basic back-and-forth conversation with a Vapi assistant.
To build more complex & custom applications, we're going to need to get real-time conversation data to our backend. **This is where server URLs come in.**
If you're familiar with functional programming, Server URLs are like callback functions. But
instead of specifying a function to get data back on, we specify a URL to a server (to POST data
back to).
## Get Started
To get started using server URLs, read our guides:
Server URLs can be set in multiple places. Learn where here.
Read about the different types of events Vapi can send to your server.
Learn about receiving server events in your local development environment.
Forward webhooks to your local server with the Vapi CLI.
**Quick local testing with Vapi CLI + tunneling:**
```bash
# Terminal 1: Create tunnel
ngrok http 4242
# Terminal 2: Start webhook forwarder
vapi listen --forward-to localhost:3000/webhook
```
This setup forwards webhook events to your local server. Remember to update your Vapi webhook URLs to use the ngrok public URL.
## FAQ
The server URL can be any publicly accessible URL pointing to an HTTP endpoint. This can be a:
* **Cloud Server:** your application might be deployed on a cloud platform like [Railway](https://railway.app), [AWS](https://aws.com), [GCP](https://cloud.google.com/gcp), etc — as a persistent web server.
* **Serverless Function:** services like [Vercel](https://vercel.com/docs/functions), [AWS Lambda](https://aws.amazon.com/lambda/), [Google Cloud Functions](https://cloud.google.com/functions), [Cloudflare](https://developers.cloudflare.com/workers/), etc — allow you to host on-demand cloud functions.
* **Workflow Orchestrator:** platforms like [Pipedream](https://pipedream.com) & [Make](https://www.make.com) allow you to program workflows (often without code) that can receive events via HTTP triggers.
The main idea is that Vapi needs a location on the Internet that it can drop data to & converse with your application.
[Webhooks](/glossary#webhook) are traditionally unidirectional & stateless, with the target endpoint usually only replying with a status code to acknowledge message reception. Certain server URL events (like assistant requests) may require a meaningful reply from your server.
"Server URL" is a more general term that encompasses both webhooks & bidirectional communication.
# Setting server URLs
> Learn about where you can set server URLs to handle call events.
Server URLs can be set in multiple places in Vapi. Each level has a different priority.
The server URL with the highest priority for a relevant event will be the one that Vapi uses to send the event to.
Server URLs can be set at **4 levels** in Vapi:
* **Account-wide:** you can set a server URL for your broader account
* **Phone Number:** server URLs can be attached to phone numbers themselves
* **Assistant:** assistants can be configured with a server URL
* **Function:** function calls themselves (under an assistant) can have a corresponding server URL
## Setting Server URLs
Here's a breakdown of where you can set server URLs in Vapi:
You can set an organization-wide server URL in the [organization section](https://dashboard.vapi.ai/vapi-api) of your dashboard.
If no other server URL is set, Vapi will use this one.
Phone numbers can have a server URL attached to them via the [phone number API](/api-reference/phone-numbers).
The server URL for phone numbers can be set **3 ways**:
* **At Time of Creation:** when you [create a free number](/api-reference/phone-numbers/create) through Vapi
* **At Import:** when you [import from Twilio](/api-reference/phone-numbers/import-twilio-number) or [Vonage](/api-reference/phone-numbers/import-vonage-number)
* **Via Update:** you can [update a number](/api-reference/phone-numbers/update-phone-number) already in your account
The field `phoneNumber.serverUrl` will contain the server URL for the phone number.
Assistants themselves can have a server URL attached to them.
There are **2 ways** this can be done:
If you go to the [assistant section](https://dashboard.vapi.ai/assistants) of your dashboard, in the **"Advanced"** tab you will see a setting to set the assistant's server URL:
At [assistant creation](/api-reference/assistants/create-assistant) (or via an [update](/api-reference/assistants/update-assistant)) you can set the assistant's server URL.
The server URL for an assistant is stored in the `assistant.serverUrl` field.
The most granular level server URLs can be set is at the function call level. This can also be done either in the dashboard, or via code.
In the [assistant section](https://dashboard.vapi.ai/assistants) of your dashboard, in the **"Functions"** tab you can add function calls & optionally give each a specific server URL:
The server URL for a function call can be found on an assistant at `assistant.model.functions[].serverUrl`.
You can either set the URL for a function call at [assistant creation](/api-reference/assistants/create-assistant), or in an [assistant update](/api-reference/assistants/update-assistant).
## URL Priority
Events are only sent/assigned to 1 server URL in the priority stack. Here's the order of priority:
1. **Function:** if a function call has a server URL, the function call event will be sent to that URL
2. **Assistant:** assistant server URLs are the next highest priority
3. **Phone Number:** if a phone number has a server URL, it will be used over the account-wide URL
4. **Account-wide:** Default / "lowest" importance. It will be used if no other server URL is set.
You will most commonly set a server URL on your account, and/or on specific assistants.
# Server events
> Learn about different events that can be sent to a Server URL.
All messages sent to your Server URL will be `POST` requests with the following body:
```json
{
"message": {
"type": "function-call",
"call": { Call Object },
...other message properties
}
}
```
They include the type of message, the call object, and any other properties that are relevant to the message type. Below are the different types of messages that can be sent to your Server URL.
### Function Calling
Vapi fully supports [OpenAI's function calling
API](https://platform.openai.com/docs/guides/gpt/function-calling), so you can have assistants
ping your server to perform actions like sending emails, retrieve information, and more.
With each response, the assistant will automatically determine what functions to call based on the directions provided in the system message in `messages`. Here's an example of what the assistant might look like:
```json
{
"name": "Ryan's Assistant",
"model": {
"provider": "openai",
"model": "gpt-4o",
"functions": [
{
"name": "sendEmail",
"description": "Used to send an email to a client.",
"parameters": {
"type": "object",
"properties": {
"color": { "type": "string" }
}
}
}
]
}
}
```
Once a function is triggered, the assistant will send a message to your Server URL with the following body:
```json
{
"message": {
"type": "function-call",
"call": { Call Object },
"functionCall": {
"name": "sendEmail",
"parameters": "{ \"emailAddress\": \"john@example.com\"}"
}
}
}
```
Your server should respond with a JSON object containing the function's response, like so:
```json
{ "result": "Your email has been sent." }
```
Or if it's an object:
```json
{
"result": "{ \"message\": \"Your email has been sent.\", \"email\": \"test@email.com\" }"
}
```
The result will be appended to the conversation, and the assistant will decide what to do with the response based on its system prompt.
If you don't need to return a response, you can use the `async: true` parameter in your assitant's
function configuration. This will prevent the assistant from waiting for a response from your
server.
### Retrieving Assistants
For inbound phone calls, you may want to specify the assistant based on the caller's phone number. If a PhoneNumber doesn't have an `assistantId`, Vapi will attempt to retrieve the assistant from your server.
```json
{
"message": {
"type": "assistant-request",
"call": { Call Object },
}
}
```
If you want to use an existing saved assistant instead of creating a transient assistant for each request, you can respond with the assistant's ID:
```json
{
"assistantId": "your-saved-assistant-id"
}
```
Alternatively, if you prefer to define a transient assistant dynamically, your server should respond with the [assistant](/api-reference/webhooks/server-message#response.body.messageResponse.Server%20Message%20Response%20Assistant%20Request.assistant) object directly:
```json
{
"assistant": {
"firstMessage": "Hey Ryan, how are you?",
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You're Ryan's assistant..."
}
]
}
}
}
```
If you'd like to play an error message instead, you can respond with:
```json
{ "error": "Sorry, not enough credits on your account, please refill." }
```
### Call Status Updates
During the call, the assistant will make multiple `POST` requests to the Server URL with the following body:
```json
{
"message": {
"type": "status-update",
"call": { Call Object },
"status": "ended",
}
}
```
* `in-progress`: The call has started. - `forwarding`: The call is about to be forwarded to
`forwardingPhoneNumber`. - `ended`: The call has ended.
### End of Call Report
When a call ends, the assistant will make a `POST` request to the Server URL with the following body:
```json
{
"message": {
"type": "end-of-call-report",
"endedReason": "hangup",
"call": { Call Object },
"recordingUrl": "https://vapi-public.s3.amazonaws.com/recordings/1234.wav",
"summary": "The user picked up the phone then asked about the weather...",
"transcript": "AI: How can I help? User: What's the weather? ...",
"messages":[
{
"role": "assistant",
"message": "How can I help?",
},
{
"role": "user",
"message": "What's the weather?"
},
...
]
}
}
```
`endedReason` can be any of the options defined on the [Call Object](/api-reference/calls/get-call).
### Hang Notifications
Whenever the assistant fails to respond for 5+ seconds, the assistant will make a `POST` requests to the Server URL with the following body:
```json
{
"message": {
"type": "hang",
"call": { Call Object },
}
}
```
You can use this to display an error message to the user, or to send a notification to your team.
# Developing locally
> Learn how to receive server events in your local development environment.
## Quick solution: Vapi CLI + Tunneling
Use the Vapi CLI webhook forwarder along with a tunneling service to test webhooks locally:
```bash
# Terminal 1: Set up tunnel (example with ngrok)
ngrok http 4242
# Terminal 2: Install and run Vapi CLI
curl -sSL https://vapi.ai/install.sh | bash
vapi listen --forward-to localhost:3000/webhook
```
**Important:** The `vapi listen` command is a local forwarder only - it does NOT provide a public URL or tunnel. You must use a separate tunneling service (like ngrok) to expose the CLI's port (default 4242) to the internet, then configure your Vapi webhook URLs to use the tunnel's public URL.
[Learn more about the Vapi CLI →](/cli/webhook)
## Manual setup with ngrok
If you prefer to skip the CLI and connect ngrok directly to your application, follow the guide below.
## The Problem
When Vapi dispatches events to a server, it must be able to reach the server via the open Internet.
If your API is already live in production, it will be accessible via a publicly known URL. But, during development, your server will often be running locally on your machine.
`localhost` is an alias for the IP address `127.0.0.1`. This address is called the "loopback"
address and forwards the network request within the machine itself.
To receive server events locally, we will need a public address on the Internet that can receive traffic and forward it to our local machine.
## Tunneling Traffic
We will be using a service called [ngrok](https://ngrok.com/) to create a secure tunnel to our local machine. The flow will look like the following:
We will start our server locally so it is listening for http traffic. We will take note of the port our server is running on.
We will use the `ngrok` command to start the [ngrok agent](https://ngrok.com/docs/agent) on our
machine. This will establish a connection from your local machine to ngrok's servers.
Ngrok will give us a public forwarding URL that can receive traffic. We will use this as a server URL
during development.
We will conduct normal calls on Vapi to trigger events. These events will go to the Ngrok URL & get tunnelled to our local machine.
We will see the event payloads come through locally & log them in our terminal.
#### Starting Our API Locally
First, ensure that your API is running locally. This could be a Node.js server, a Python server, or any other server that can receive HTTP requests.
Take note of the port that your server is running on. For example, if your server is running on port `8080`, you should be able to access it at `http://localhost:8080` in your browser.
#### Starting Ngrok Agent
Next we will install & run Ngrok agent to establish the forwarding pathway for Internet traffic:
Install the Ngrok agent by following Ngrok's [quickstart
guide](https://ngrok.com/docs/getting-started). Once complete, we will have the `ngrok` command
available in our terminal.
Run the command `ngrok http 8080`, this will create the tunnel with Ngrok's servers.
Replace `8080` with the port your server is running on.
#### Copy Ngrok Forwarding URL
You will see an output from the Ngrok Agent CLI that looks like the following:
Copy this public URL that Ngrok provides. This URL will be accessible from the open Internet and will forward traffic to your local machine.
You can now use this as a server URL in the various places you can [set server URLs](/server-url/setting-server-urls) in Vapi.
This URL will change every time that you run the `ngrok` command. If you'd like this URL to be the
same every Ngrok session, look into [static domains on
Ngrok](https://ngrok.com/docs/getting-started#step-4-always-use-the-same-domain).
#### Trigger Call Events
We will now be able to see call events come through as `POST` requests, & can log payloads to our terminal.
Feel free to follow any of our [quickstart](/quickstart) guides to get started with building assistants & conducting calls.
## Troubleshooting
Here's a list of a few things to recheck if you face issues seeing payloads:
* Ensure that your local server is running on the port you expect
* Ensure that you input the correct port to the `ngrok http {your_port}` command
* Ensure your route handling server URL events is a `POST` endpoint
* Ensure your path on top of the base forwarding url is set correctly (ex: `/callbacks/vapi`)
# Server authentication
When configuring webhooks for your assistant, you can authenticate your server endpoints using either a secret token, custom headers, or OAuth2. This ensures that only authorized requests from Vapi are processed by your server.
## Credential Configuration
Credentials can be configured at multiple levels:
1. **Tool Call Level**: Create individual credentials for each tool call
2. **Assistant Level**: Set credentials directly in the assistant configuration
3. **Phone Number Level**: Configure credentials for specific phone numbers
4. **Organization Level**: Manage credentials in the [API Keys page](https://dashboard.vapi.ai/keys)
The order of precedence is:
1. Tool call-level credentials
2. Assistant-level credentials
3. Phone number-level credentials
4. Organization-level credentials from the API Keys page
## Authentication Methods
### Secret Token Authentication
The simplest way to authenticate webhook requests is using a secret token. Vapi will include this token in the `X-Vapi-Signature` header of each request.
#### Configuration
```json
{
"server": {
"url": "https://your-server.com/webhook",
"secret": "your-secret-token"
}
}
```
### Custom Headers Authentication
For more complex authentication scenarios, you can configure custom headers that Vapi will include with each webhook request.
This could include short lived JWTs/API Keys passed along via the Authorization header, or any other header that your server checks for.
#### Configuration
```json
{
"server": {
"url": "https://your-server.com/webhook",
"headers": {
"Authorization": "Bearer your-api-key",
"Custom-Header": "custom-value"
}
}
}
```
### OAuth2 Authentication
For OAuth2-protected webhook endpoints, you can configure OAuth2 credentials that Vapi will use to obtain and refresh access tokens.
#### Configuration (at the assistant-level)
```json
{
"server": {
"url": "https://your-server.com/webhook"
},
"credentials": [
{
"provider": "webhook",
"authenticationPlan": {
"type": "oauth2",
"url": "https://your-server.com/oauth/token",
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"scope": "optional, only needed to specify which scopes to request access for"
}
}
]
}
```
#### Configuration (via our Dashboard)
Go to [https://dashboard.vapi.ai/keys](https://dashboard.vapi.ai/keys) to manage your OAuth2 credentials.
#### OAuth2 Flow
1. Vapi makes a request to your token endpoint with client credentials (Content-Type `application/x-www-form-urlencoded`)
2. Your server validates the credentials and returns an access token
3. Vapi includes the access token in the Authorization header for webhook requests
4. Your server validates the access token before processing the webhook
5. When the token expires, Vapi automatically requests a new one
#### OAuth2 Token Response Format
Your server should return a JSON response with the following format:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
```
Example error response:
```json
{
"error": "invalid_client",
"error_description": "Invalid client credentials"
}
```
Common error types:
* `invalid_client`: Invalid client credentials
* `invalid_grant`: Invalid or expired refresh token
* `invalid_scope`: Invalid scope requested
* `unauthorized_client`: Client not authorized for this grant type
If using the OAuth2 flow for authenticating tool calls, make sure the server for the tool is the URL that should be hit
*after*
we have completed the token exchange.
# Frequently Asked Questions
> Frequently asked questions about Vapi.
If you are **a developer building a voice AI application simulating human conversation** (w/ LLMs — to whatever degree of application complexity) — Vapi is built for you.
Whether you are building for a completely "turn-based" use case (like appointment setting), all the way to robust agentic voice applications (like virtual assistants), Vapi is tooled to solve for your voice AI workflow.
Vapi runs on any platform: the web, mobile, or even embedded systems (given network access).
Not a problem, we can likely already support it. Vapi is designed to be modular at every level of the voice pipeline: Text-to-speech, LLM, Speech-to-text.
You can bring your own custom models for any part of the pipeline.
* **If they’re hosted with one of our providers:** you just need to add your [provider keys](customization/provider-keys), then specify the custom model in your API requests.
* **If they are hosted elsewhere:** you can use the `Custom LLM` provider and specify the [URL to your model](customization/custom-llm/fine-tuned-openai-models) in your API request.
Everything is interchangeable, mix & match to suit your usecase.
You could (and the person writing this right now did, from scratch) — but there are good reasons for not doing so.
Writing a great realtime voice AI application from scratch is a fairly challenging task (more on those challenges [here](/challenges-of-realtime-conversation)). Most of these challenges are not apparent until you face them, then you realize you are 3 weeks into a rabbit hole that may take months to properly solve out of.
Think of Vapi as hiring a software engineering team for this hard problem, while you focus on what uniquely generates value for your voice AI application.
***
But to address cost, the vast majority of cost in running your application will come from provider cost (Speect-to-text, LLM, Text-to-speech) direct with vendors (Deepgram, OpenAI, ElevenLabs, etc) — where we add no fee (vendor cost passes-through). These would have to be incurred anyway.
Vapi only charges its small fee on top of these for the continuous maintenance & improvement of these hardest components of your system (which would have costed you time to write/maintain).
No matter what, some cost is inescapable (in money, time, etc) to solve this challenging technical problem.
Our focus is solely on foundational Voice AI orchestration, & it’s what we put our full time and resources into.
To learn more about Vapi’s pricing, you can visit our [pricing page](/pricing).
No — in fact, the setup could not be easier:
* **Web Dashboard:** It can take minutes to get up & running with our [dashboard](https://dashboard.vapi.ai/).
* **Client SDKs:** You can start calls with 1 line of code with any of our [client SDKs](/sdks).
For more advanced features like function calling, you will have to set up a [Server URL](/server-url) to receive and respond to messages.
Vapi focuses on developers. Giving developers modular, simple, & robust tooling to build any voice AI application imaginable.
Vapi also has some of the lowest latency & (equally important) highest reliability amongst any other voice AI platform built for developers.
Yes, Vapi is designed to achieve low latency, typically around 800 milliseconds for end-to-end voice processing. Our infrastructure is optimized for real-time communication, and we continuously work to minimize latency through various optimizations in our pipeline.
Yes, we offer volume-based pricing discounts for customers with consistent monthly usage. The more minutes you commit to, the better the per-minute rate. We're happy to discuss custom pricing plans based on your specific volume requirements and use case.
Absolutely. Our platform is built to handle high concurrency, and 1000+ concurrent sessions is well within our capacity. We've designed our infrastructure to scale horizontally, ensuring reliable performance even during peak usage periods. For enterprise customers with specific scaling needs, we can discuss custom solutions.
Yes, we take compliance seriously. Vapi is:
* HIPAA compliant for healthcare applications
* SOC 2 Type II certified
* GDPR compliant for handling EU data
* Regularly audited to maintain these certifications
For detailed compliance documentation and reports, please visit our [security portal](https://security.vapi.ai/).
We implement multiple layers of security for PII and PHI:
* End-to-end encryption for all data in transit
* Secure storage with encryption at rest
* Strict access controls and audit logging
* Regular security assessments and penetration testing
* Data minimization practices
* Secure data deletion protocols
All data handling practices are documented in our security policies and compliance frameworks.
Yes, we offer both white-labeling and on-premise deployment options:
* **White-labeling:** Custom branding, domain, and UI customization
* **On-premise:** Full deployment within your infrastructure
These options are available for enterprise customers. Please contact our sales team to discuss your specific requirements.
# Core Models
> Learn about the three core components to Vapi's voice AI pipeline.
At it's core, Vapi is an orchestration layer over three modules: the **transcriber**, the **model**, and the **voice**.
These three modules can be swapped out with **any provider** of your choosing; OpenAI, Groq, Deepgram, ElevenLabs, PlayHT, etc. You can even plug in your server to act as the LLM.
Vapi takes these three modules, optimizes the latency, manages the scaling & streaming, and orchestrates the conversation flow to make it sound human.
When a person speaks, the client device (whether it is a laptop, phone,
etc) will record raw audio (1’s & 0’s at the core of it).
This raw audio will have to either be transcribed on the client device
itself, or get shipped off to a server somewhere to turn into
transcription text.
That transcript text will then get fed into a prompt & run through an LLM
([LLM inference](/glossary#inference)). The LLM is the core intelligence
that simulates a person behind-the-scenes.
The LLM outputs text that now must be spoken. That text is turned back
into raw audio (again, 1’s & 0’s), that is playable back at the user’s
device.
This process can also either happen on the user’s device itself, or on a
server somewhere (then the raw speech audio be shipped back to the user).
The idea is to perform each phase in realtime (sensitive down to 50-100ms level), streaming between every layer. Ideally the whole flow
[voice-to-voice](/glossary#voice-to-voice)
clocks in at <500-700ms.
Vapi pulls all these pieces together, ensuring a smooth & responsive conversation (in addition to providing you with a simple set of tools to manage these inner-workings).
# Orchestration Models
> Learn about the real-time models Vapi runs on top of STT, LLM, and TTS.
On top of speech-to-text, a language model, and text-to-speech, we run a suite of real-time models that make conversations feel fast, fluid, and human.
These models are part of what we call the **orchestration layer**.
## Overview
The following are the models we currently run, with many more coming soon:
* **Endpointing** – Detects exactly when the user finishes speaking.
* **Interruptions** – Lets users cut in and interrupt the assistant.
* **Background noise filtering** – Cleans up ambient noise in real-time.
* **Background voice filtering** – Ignores speech from TVs, echoes, or other people.
* **Backchanneling** – Adds affirmations like “yeah” or “got it” at the right moments.
* **Emotion detection** – Detects user tone and passes emotion to the LLM.
* **Filler injection** – Adds “um”, “like”, “so” and other natural fillers to assistant responses.
### Endpointing
Endpointing is a fancy word for knowing when the user is done speaking. Traditional methods use silence detection with a timeout. Unfortunately, if we want sub-second response-times, that's not going to work.
Vapi's uses a custom fusion audio-text model to know when a user has completed their turn. Based on both the user's tone and what they're saying, it decides how long to pause before hitting the LLM.
This is critical to make sure the user isn't interrupted mid-thought while still providing sub-second response times when they're done speaking.
### Interruptions (Barge-in)
Interruptions (aka. barge-in in research circles) is the ability to detect when the user would like to interject and stop the assistant's speech.
Vapi uses a custom model to distinguish when there is a true interruption, like "stop", "hold up", "that's not what I mean, and when there isn't, like "yeah", "oh gotcha", "okay."
It also keeps track of where the assistant was cut off, so the LLM knows what it wasn't able to say.
### Background Noise Filtering
Many of our models, including the transcriber, are audio-based. In the real world, things like music and car horns can interfere with model performance.
We use a proprietary real-time noise filtering model to ensure the audio is cleaned without sacrificing latency, before it reaches the inner models of the pipeline.
### Background Voice Filtering
We rely quite heavily on the transcription model to know what's going on, for interruptions, endpointing, backchanneling, and for the user's statement passed to the LLM.
Transcription models are built to pick up everything that sounds like speech, so this can be a problem. As you can imagine, having a TV on in the background or echo coming back into the mic can severely impact the conversation ability of a system like Vapi.
Background noise cancellation is a well-researched problem. Background voice cancellation is not. To solve this, we built proprietary audio filtering model that's able to **focus in** on the primary speaker and block everything else out.
### Backchanneling
Humans like to affirm each other while they speak with statements like "yeah", "uh-huh", "got it", "oh no!"
They're not considered interruptions, they're just used to let the speaker know that their statement has been understood, and encourage the user to continue their statement.
A backchannel cue used at the wrong moment can derail a user's statement. Vapi uses a proprietary fusion audio text model to determine the best moment to backchannel and to decide which backchannel cue is most appropriate to use.
### Emotion Detection
How a person says something is just as important as what they're saying. So we've trained a real-time audio model to extract the emotional inflection of the user's statement.
This emotional information is then fed into the LLM, so knows to behave differently if the user is angry, annoyed, or confused.
### Filler Injection
The output of LLMs tends to be formal, and not conversational. People speak with phrases like "umm", "ahh", "i mean", "like", "so", etc.
You can prompt the model to output like this, but we treat our user's prompts as **sacred**. Making a change like this to a prompt can change the behavior in unintended ways.
To ensure we don't add additional latency transforming the output, we've built a custom model that's able to convert streaming input and make it sound conversational in real-time.
# Vapi Voices
> Our curated selection of high-quality voices
## What are Vapi Voices?
Vapi Voices is our carefully curated selection of high-quality voices designed to simplify your voice AI implementation. We offer a small handful of exceptional voices that you can immediately use in your applications.
## Why Choose Vapi Voices?
* **Simple**: Skip testing dozens of voices
* **Quality**: Each voice is vetted for natural sound
* **Ready to Use**: Pre-optimized for your applications
* **Consistent**: Reliable quality in all interactions
## Available Voices
### Rohan
* **Gender**: Male
* **Accent**: Indian American
* **Age**: 24 years old
* **Characteristics**: Bright, optimistic, cheerful, energetic
* **Sample Audio**:
### Neha
* **Gender**: Female
* **Accent**: Indian American
* **Age**: 30 years old
* **Characteristics**: Professional, charming
* **Sample Audio**:
### Hana
* **Gender**: Female
* **Accent**: American
* **Age**: 22 years old
* **Characteristics**: Soft, soothing, gentle
* **Sample Audio**:
### Harry
* **Gender**: Male
* **Accent**: American
* **Age**: 24 years old
* **Characteristics**: Clear, energetic, professional
* **Sample Audio**:
### Elliot
* **Gender**: Male
* **Accent**: Canadian
* **Age**: 25 years old
* **Characteristics**: Soothing, friendly, professional
* **Sample Audio**:
### Lily
* **Gender**: Female
* **Accent**: Asian American
* **Age**: 25 years old
* **Characteristics**: Bright personality, bubbly, cheerful
* **Sample Audio**:
### Paige
* **Gender**: Female
* **Accent**: American
* **Age**: 26 years old
* **Characteristics**: Deeper tone, calming, professional
* **Sample Audio**:
### Cole
* **Gender**: Male
* **Accent**: American
* **Age**: 22 years old
* **Characteristics**: Deeper tone, calming, professional
* **Sample Audio**:
### Savannah
* **Gender**: Female
* **Accent**: American (Southern)
* **Age**: 25 years old
* **Characteristics**: Southern American accent
* **Sample Audio**:
### Spencer
* **Gender**: Female
* **Accent**: American
* **Age**: 26 years old
* **Characteristics**: Energetic, quippy, lighthearted, cheeky, amused
* **Sample Audio**:
## How to Use
1. Select a voice from our collection
2. Integrate it into your assistant or squad
3. Start creating voice interactions immediately
## Common Use Cases
* Customer service virtual agents
* Content voiceovers and narration
* Interactive conversational applications
By choosing Vapi Voices, you can focus on building great applications rather than spending time selecting and testing voices.
# ElevenLabs
> How Vapi Integrates Text-to-Speech Platforms?
# How Vapi Integrates Text-to-Speech Platforms: ElevenLabs
In the realm of voice AI development, integrating cutting-edge text-to-speech (TTS) platforms is crucial for creating natural and engaging conversational experiences. This guide explores how developers can leverage our voice AI platform to seamlessly incorporate advanced TTS services like ElevenLabs, enabling the creation of sophisticated voice-driven applications with remarkable efficiency.
## Understanding the Voice AI Platform
Our platform serves as a comprehensive toolkit for developers, designed to simplify the complexities inherent in voice AI development. By abstracting intricate technical details, it allows developers to focus on crafting the core business logic of their applications rather than grappling with low-level implementation challenges.
### Key Components of the Voice AI Architecture
At the heart of our platform lies a robust architecture comprising three essential components:
1. Automatic Speech Recognition (ASR)
2. Large Language Model (LLM) processing
3. Text-to-Speech (TTS) integration
These components work in concert to facilitate seamless voice interactions. The ASR module captures and processes audio inputs, converting spoken words into digital data. The LLM processing unit analyzes this data, interpreting context and generating appropriate responses. Finally, the TTS integration transforms these responses back into natural-sounding speech.
## Integration with Text-to-Speech Platforms
Our approach to integrating external TTS services, such as ElevenLabs, is designed to be both flexible and powerful. By incorporating advanced TTS platforms, developers can significantly enhance the quality and versatility of their voice AI applications.
### ElevenLabs Integration: A Technical Deep Dive
The integration with ElevenLabs' AI speech synthesis exemplifies our commitment to providing developers with state-of-the-art tools. This integration process involves several key technical aspects:
1. **API Integration**: Our platform seamlessly connects with ElevenLabs' API, allowing for efficient data exchange and real-time speech synthesis.
2. **Voice Model Selection**: Developers can choose from a range of voice models provided by ElevenLabs, each with unique characteristics and tonal qualities.
3. **Parameter Control**: Fine-tuning of speech parameters such as speed, pitch, and emphasis is made accessible through our intuitive interface.
4. **Data Flow Optimization**: We've implemented efficient data handling mechanisms to ensure smooth transmission between our platform and ElevenLabs' servers, minimizing latency and maintaining high-quality output.
## Advanced Features of the Integration
The integration of ElevenLabs' technology brings forth a suite of advanced features that elevate the capabilities of voice AI applications.
### Contextual Awareness in Speech Synthesis
By leveraging ElevenLabs' sophisticated algorithms, our platform enables AI-generated speech that demonstrates a high degree of contextual awareness. This results in more natural-sounding conversations that can adapt to the nuances of different scenarios and user interactions.
### Enhanced Voice Modulation and Emotional Expression
The integration allows for precise control over voice modulation and emotional expression. Developers can craft AI voices that convey a wide range of emotions, from excitement to empathy, enhancing the overall user experience and making interactions more engaging and human-like.
### Real-time Audio Streaming Capabilities
One of the most compelling features of our integration is the ability to leverage ElevenLabs' streaming capabilities for real-time applications. This functionality is crucial for creating responsive voice AI systems that can engage in dynamic, live interactions.
Implementing low-latency voice synthesis presents several technical challenges, including:
* **Network Latency Management**: Minimizing delays in data transmission between our platform, ElevenLabs' servers, and the end-user's device.
* **Buffer Optimization**: Balancing audio quality with real-time performance through careful buffer management.
* **Adaptive Bitrate Streaming**: Implementing techniques to adjust audio quality based on network conditions, ensuring consistent performance across various environments.
Our platform addresses these challenges through advanced streaming protocols and optimized data handling, enabling developers to create voice AI applications that respond with near-human speed and fluidity.
## Developer Tools and Resources
To facilitate the integration process, we provide a comprehensive set of developer tools and resources:
* **SDKs**: Open-source software development kits available on GitHub, supporting multiple programming languages.
* **Documentation**: Detailed API references and conceptual guides covering key aspects of voice AI development.
* **Quickstart Guides**: Step-by-step tutorials to help developers get up and running quickly.
* **End-to-End Examples**: Sample implementations of common voice workflows, including outbound sales calls, inbound support interactions, and web-based voice interfaces.
### Building Custom Voice AI Applications
Developers can follow these steps to create voice AI applications with integrated TTS:
1. **Define the Use Case**: Clearly outline the objectives and scope of the voice AI application.
2. **Select the Appropriate Voice Model**: Choose an ElevenLabs voice that aligns with the application's tone and purpose.
3. **Implement Core Logic**: Utilize our SDKs to implement the application's business logic and conversation flow.
4. **Configure TTS Parameters**: Fine-tune speech synthesis settings to achieve the desired voice characteristics.
5. **Test and Iterate**: Conduct thorough testing to ensure natural conversation flow and appropriate responses.
6. **Optimize Performance**: Leverage our platform's analytics tools to identify and address any performance bottlenecks.
Best practices for optimizing voice AI performance and user experience include:
* Implementing effective error handling and fallback mechanisms
* Designing clear and concise conversation flows
* Regularly updating and refining language models based on user interactions
* Optimizing for low-latency responses to maintain natural conversation cadence
## Use Cases and Applications
The integration of advanced TTS platforms opens up a myriad of possibilities across various industries:
* **Customer Service**: Creating empathetic and efficient AI-powered support agents.
* **Education**: Developing interactive language learning tools with native-speaker quality pronunciation.
* **Healthcare**: Building voice-based assistants for patient engagement and medical information delivery.
* **Entertainment**: Crafting immersive storytelling experiences with dynamically generated character voices.
Developers can leverage this integration to create unique voice-based solutions that were previously challenging or impossible to implement with traditional TTS technologies.
## Future Developments and Potential
As the field of voice AI continues to advance, our platform is poised to incorporate new features and improvements in TTS integration capabilities. Upcoming developments may include:
* Enhanced multilingual support for global applications
* More sophisticated emotional intelligence in voice synthesis
* Improved personalization capabilities, allowing for voice adaptation based on user preferences
The future of voice AI development is likely to see increased focus on natural language understanding, context-aware responses, and seamless multi-modal interactions. Our platform is well-positioned to address these trends, providing developers with the tools they need to stay at the forefront of voice technology innovation.
## Conclusion
The integration of advanced text-to-speech platforms like ElevenLabs into our voice AI development ecosystem represents a significant leap forward for developers seeking to create sophisticated, natural-sounding voice applications. By abstracting complex technical challenges and providing robust tools and resources, we enable developers to focus on innovation and creativity in their voice AI projects. As the technology continues to evolve, our platform will remain at the cutting edge, empowering developers to build the next generation of voice-driven experiences.
# PlayHT
> What is PlayHT?
**What is PlayHT?**
In the dynamic world of artificial intelligence, PlayHT emerges as a leading provider of voice AI solutions. Specializing in text-to-speech (TTS) and voice cloning technologies, PlayHT delivers highly realistic and versatile AI-generated voices that cater to a wide array of applications. From enhancing marketing videos to making content more accessible, PlayHT’s innovative tools empower users to create engaging and professional-grade audio content effortlessly.
**The Evolution of AI Voice Technology:**
AI voice technology has significantly evolved over the past decade. Initially limited to robotic and monotone outputs, advancements in machine learning and neural networks have paved the way for natural and expressive voice synthesis. PlayHT has harnessed these advancements to offer superior AI voices that are nearly indistinguishable from human speech, setting a new standard in the industry.
**Overview of PlayHT’s Offerings:**
PlayHT provides a robust suite of voice AI tools designed to meet diverse needs:
**Text to Speech:**
* PlayHT’s TTS technology converts written text into highly realistic speech, making it ideal for creating voiceovers, audiobooks, and other spoken content. This technology supports over 142 languages and accents, allowing users to generate audio content that is not only clear and engaging but also linguistically diverse.
**Voice Cloning:**
* PlayHT’s voice cloning feature enables users to create digital replicas of voices with high accuracy. This is particularly useful for preserving voices, personalizing digital assistants, and generating unique character voices for media and entertainment. The cloned voices maintain the nuances and emotional expressiveness of the original, ensuring a lifelike audio experience.
**Voice Generation API:**
* PlayHT offers a Voice Generation API that allows developers to integrate AI voice capabilities into their applications. This API supports real-time voice synthesis and cloning, providing a flexible and powerful solution for various interactive applications, including chatbots, virtual assistants, and gaming.
**Use Cases for PlayHT:**
* The applications of PlayHT’s technology are extensive and impactful:
**Marketing:**
* In the marketing sector, PlayHT’s realistic AI voices enhance the quality of promotional videos, explainer videos, and advertisements. Brands can create consistent and professional voiceovers that captivate audiences and convey messages effectively.
**E-Learning:**
* For educational content, PlayHT provides voices capable of pronouncing complex terminologies and acronyms, making e-learning materials more engaging and easier to understand. This helps in creating comprehensive and interactive training modules.
**Accessibility:**
* PlayHT’s TTS technology is a boon for accessibility, converting text into speech to assist individuals with visual impairments or reading difficulties. This promotes inclusivity and ensures that information is accessible to all.
**Gaming:**
* In the gaming industry, PlayHT’s voice cloning and TTS capabilities bring characters to life, enhancing the overall gaming experience. Developers can quickly generate high-quality voiceovers for dialogues, narration, and character interactions.
**Impact on Content Creation:**
* PlayHT is revolutionizing content creation by offering tools that are both powerful and user-friendly. By enabling creators to produce high-quality audio content quickly and efficiently, PlayHT reduces the time and costs associated with traditional recording methods. This democratizes access to professional-grade audio production, fostering innovation and creativity across various domains.
**Innovation and Research:**
Committed to pushing the boundaries of voice AI, PlayHT invests in continuous research and development. Their team of experts focuses on enhancing the quality, expressiveness, and versatility of AI-generated voices, exploring new applications, and refining existing technologies.
**AI Safety and Ethics:**
PlayHT prioritizes the ethical use of AI technology. They have implemented stringent safeguards to prevent misuse and are actively engaged in discussions about the responsible development and deployment of AI. Ensuring the privacy and security of users’ data is a core aspect of their operations.
**Integrations and Compatibility:**
PlayHT’s Voice Generation API enables seamless integration with various platforms and applications. This flexibility ensures that users can incorporate PlayHT’s voice AI capabilities into their existing systems without any hassle, streamlining workflows and enhancing functionality.
# Azure
> What is Microsoft Azure?
**What is Microsoft Azure?**
Microsoft Azure is a comprehensive cloud computing platform that provides a wide array of services, including computing power, storage solutions, and advanced analytics. As a leader in cloud technology, Azure enables businesses and developers to build, manage, and deploy applications on a global network. With its robust infrastructure and extensive suite of tools, Azure supports diverse workloads, from simple web apps to complex AI and machine learning models.
**The Evolution of Cloud Computing:**
Cloud computing has revolutionized how businesses operate by providing scalable and flexible IT resources over the internet. Early cloud solutions were limited in scope and performance, but advances in virtualization, networking, and storage have transformed the cloud into a versatile and powerful platform. Microsoft Azure has been at the forefront of this evolution, continually enhancing its capabilities to meet the growing demands of modern enterprises.
**Overview of Azure’s Offerings:**
Azure offers a broad range of services designed to support various business needs:
**Cloud Services:**
* Azure’s cloud services include virtual machines, storage solutions, and databases, allowing businesses to host applications, store data, and perform complex computations. These services provide the scalability and flexibility needed to handle dynamic workloads and ensure business continuity.
**AI and Machine Learning:**
* Azure’s AI and machine learning offerings include Azure AI, Cognitive Services, and Azure Machine Learning. These tools enable developers to build intelligent applications that can see, hear, speak, and understand. Azure AI provides pre-built models and APIs for tasks like natural language processing, computer vision, and speech recognition.
**DevOps and Development:**
* Azure DevOps integrates with GitHub and other development tools to streamline the software development lifecycle. It offers continuous integration and continuous delivery (CI/CD) pipelines, version control, and project management tools, helping teams collaborate more effectively and deliver high-quality software faster.
**Cloud Services:**
* Azure’s cloud services are designed to meet the needs of businesses of all sizes:
**Compute:**
* Azure provides a range of compute options, including virtual machines, containers, and serverless computing. These services allow businesses to run applications and workloads in the cloud without worrying about underlying hardware.
**Storage:**
* Azure offers scalable and secure storage solutions, including Blob Storage, Disk Storage, and File Storage. These services ensure that businesses can store and manage large volumes of data efficiently and reliably.
**Databases:**
* Azure’s database services include SQL Database, Cosmos DB, and Database for PostgreSQL. These managed database solutions offer high availability, security, and performance, making it easy to build and scale data-driven applications.
**AI and Machine Learning:**
* Azure’s AI and machine learning services empower developers to create intelligent applications:
**Azure AI:**
* Azure AI provides a suite of pre-built AI models and APIs that can be easily integrated into applications. These models cover a wide range of AI capabilities, from language understanding to image recognition.
**Cognitive Services:**
* Azure Cognitive Services offer APIs for vision, speech, language, and decision-making. These services allow developers to add sophisticated AI features to their applications with minimal effort.
**Azure Machine Learning:**
* Azure Machine Learning is a cloud-based service that enables data scientists and developers to build, train, and deploy machine learning models. It supports a variety of frameworks and tools, making it a versatile solution for AI projects.
**DevOps and Development:**
* Azure provides comprehensive tools for DevOps and software development:
**Azure DevOps:**
* Azure DevOps offers a suite of tools for managing the entire software development lifecycle. It includes services for version control, build automation, release management, and project tracking, enabling teams to deliver software more efficiently.
**GitHub Integration:**
Azure integrates seamlessly with GitHub, allowing developers to use their preferred version control platform while taking advantage of Azure’s CI/CD capabilities. This integration supports collaboration and accelerates the development process.
**Development Tools:**
* Azure offers a range of development tools, including Visual Studio and Visual Studio Code. These tools provide robust features for coding, debugging, and deploying applications, making it easier for developers to build high-quality software.
**Use Cases for Azure:**
* Azure’s versatile platform supports a wide range of use cases:
**Business Solutions:**
* Azure provides solutions for various business needs, including enterprise resource planning (ERP), customer relationship management (CRM), and business intelligence (BI). These solutions help businesses optimize operations and make data-driven decisions.
**Application Development:**
* Azure supports the development of modern applications with services like App Service, Kubernetes Service, and Functions. These services enable developers to build, deploy, and scale applications quickly and efficiently.
**Data Analytics:**
* Azure offers powerful data analytics tools, including Synapse Analytics, Data Factory, and Databricks. These tools help businesses process and analyze large volumes of data, uncovering insights and driving better outcomes.
**Impact on Digital Transformation**
Azure plays a crucial role in digital transformation by providing the tools and infrastructure needed to innovate and stay competitive. Its cloud services enable businesses to scale rapidly, improve operational efficiency, and deliver new products and services to market faster. Azure’s AI and machine learning capabilities also drive innovation by enabling businesses to leverage advanced analytics and automation.
**Innovation and Research:**
Microsoft is committed to continuous innovation and research in cloud computing and AI. Azure regularly introduces new features and enhancements, ensuring that businesses have access to the latest technologies. Microsoft also invests in research to advance the state of the art in AI, security, and cloud infrastructure.
**AI Safety and Ethics:**
Ensuring the safe and ethical use of AI is a top priority for Microsoft. Azure implements robust security measures to protect data and prevent misuse. Microsoft is also actively involved in developing ethical guidelines and best practices for AI, promoting transparency, accountability, and fairness in AI development and deployment.
**Integrations and Compatibility:**
Azure’s API and platform integrations ensure compatibility with a wide range of applications and services. This flexibility allows businesses to integrate Azure’s capabilities into their existing workflows and systems, enhancing functionality and improving user experience.
# OpenAI
> What is OpenAI?
**What is OpenAI?**
OpenAI is a leading artificial intelligence research and deployment company dedicated to ensuring that artificial general intelligence (AGI) benefits all of humanity. Founded with the mission to create safe and highly capable AI systems, OpenAI has made significant strides in AI research, producing groundbreaking models like GPT-4o, DALL-E, and Codex. These innovations have not only advanced the field of AI but also transformed various industries by providing powerful tools for natural language processing, image generation, and programming assistance.
**The Evolution of AI Research:**
The field of AI has evolved rapidly over the past few decades. From early rule-based systems to modern deep learning models, AI technology has made significant progress in mimicking human intelligence. OpenAI has been at the forefront of this evolution, pushing the boundaries of what AI can achieve through continuous research and development. Their work on large language models and neural networks has set new benchmarks for performance and capability in AI systems.
**Overview of OpenAI’s Offerings:**
OpenAI offers a range of AI-driven products and services designed to meet diverse needs:
**GPT Models:**
* OpenAI’s Generative Pre-trained Transformer (GPT) models, including the latest GPT-4o, are state-of-the-art in natural language processing. These models can generate human-like text, answer questions, summarize information, and perform various language tasks with high accuracy. GPT-4o, in particular, represents a significant leap in AI capabilities, offering improved coherence, context understanding, and creativity.
**DALL-E:**
* DALL-E is OpenAI’s revolutionary image generation model that creates detailed and imaginative images from text descriptions. By combining deep learning with creative processes, DALL-E can produce unique artwork, design concepts, and visual content that aligns with the given textual input. This technology opens new possibilities for artists, designers, and content creators.
**Codex:**
* Codex is an AI model that assists with programming by understanding and generating code. Integrated into tools like GitHub Copilot, Codex can help developers write code faster and more efficiently by suggesting code snippets, debugging errors, and automating repetitive tasks. This enhances productivity and reduces the barrier to entry for learning programming languages.
**GPT-4 Technology:**
* GPT-4 is the latest and most advanced language model developed by OpenAI. It excels in generating coherent and contextually relevant text, making it a powerful tool for various applications, including chatbots, content creation, and automated customer support. With enhanced capabilities for understanding and generating human language, GPT-4 sets a new standard in AI-driven communication.
**DALL-E Image Generation:**
* DALL-E takes text-to-image generation to new heights, allowing users to create visually stunning and highly specific images based on textual descriptions. This technology is particularly valuable for creative industries, where generating unique visuals quickly and accurately is essential. From concept art to marketing materials, DALL-E provides a versatile tool for visual content creation.
**Codex and Programming Assistance:**
* Codex transforms the way developers interact with code by providing intelligent suggestions and automating routine programming tasks. This AI-powered assistant understands multiple programming languages and can generate code snippets, making coding more accessible and efficient. Integrated into platforms like GitHub Copilot, Codex helps streamline the development process and accelerates software production.
**Use Cases for OpenAI:**
OpenAI’s technologies are versatile and applicable across various sectors:
**Education:**
In education, GPT-4 and Codex can enhance learning experiences by providing personalized tutoring, generating educational content, and assisting with coding exercises. These tools help students grasp complex concepts and improve their programming skills.
**Business:**
Businesses leverage OpenAI’s models for automating customer support, generating marketing content, and analyzing large volumes of text data. GPT-4’s ability to understand and generate human-like text enhances customer interactions and drives operational efficiency.
**Creative Industries:**
In the creative sector, DALL-E and GPT-4 enable artists and writers to generate new ideas, create unique visuals, and produce high-quality content. These tools expand creative possibilities and streamline content production workflows.
**Innovation and Research:**
OpenAI is committed to advancing AI through continuous research and innovation. Their team of researchers and engineers works on developing new models, improving existing technologies, and exploring novel applications of AI. This commitment to innovation ensures that OpenAI remains at the cutting edge of the field.
**AI Safety and Ethics:**
Ensuring the safe and ethical use of AI is a core principle at OpenAI. They implement rigorous safety measures to prevent misuse and ensure that their technologies are used responsibly. OpenAI is also involved in global discussions about AI ethics and governance, contributing to the development of best practices and standards for the industry.
**Integrations and Compatibility:**
OpenAI’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate OpenAI’s AI capabilities into their existing systems, enhancing functionality and improving user experience. The API is designed to be flexible and user-friendly, accommodating a wide range of use cases.
# Cartesia
> What is Cartesia.ai?
**What is Cartesia.ai?**
Cartesia.ai is an advanced AI platform dedicated to developing real-time multimodal intelligence that operates across various devices. Specializing in ultrafast, realistic speech synthesis and voice API solutions, Cartesia.ai combines state-of-the-art AI technology with practical applications, empowering users to create high-quality, interactive voice content efficiently.
**The Evolution of Multimodal AI:**
AI technology has evolved from single-modal applications to sophisticated multimodal systems capable of processing and generating text, audio, video, and images. These advancements have paved the way for more integrated and interactive AI solutions. Cartesia.ai leverages these developments to offer comprehensive AI services that cater to diverse needs.
**Overview of Cartesia.ai’s Offerings:**
Cartesia.ai provides a range of AI-driven tools designed to support various applications:
**Real-time Voice API:**
Cartesia.ai’s real-time voice API is engineered for speed and efficiency, offering low latency and high-quality voice generation. This makes it ideal for applications requiring immediate feedback, such as virtual assistants, interactive games, and live conversations.
**Multimodal Intelligence:**
Cartesia.ai’s multimodal intelligence capabilities extend beyond voice synthesis, encompassing text, audio, video, and images. This enables users to create more interactive and engaging content by integrating multiple forms of media into a single platform.
**Ultrafast Voice Synthesis:**
Cartesia.ai’s ultrafast voice synthesis technology offers several key features and benefits:
**Features:**
* Low Latency Streaming: Ensures quick response times for real-time applications.
* High Availability: Delivers reliable performance even under heavy loads.
* Expressive Voices: Provides a wide range of emotions and nuances, enhancing the naturalness of generated speech.
**Benefits:**
* Engagement: Enhances user interactions with immediate and natural responses.
* Scalability: Manages large volumes of requests without compromising quality.
* Versatility: Suitable for various applications, from customer service to entertainment.
**Multimodal Intelligence:**
Cartesia.ai’s multimodal intelligence capabilities provide comprehensive solutions for creating interactive and engaging content:
Text, Audio, Video, Images
* Integrated Media: Combine text, audio, video, and images for more immersive experiences.
* Advanced AI Models: Utilize state-of-the-art AI models for high-quality media processing.
**Developer API:**
Cartesia.ai offers a robust API with comprehensive documentation and SDKs, facilitating seamless integration:
**Integration:**
* SDKs: Available for multiple programming languages.
* Low Latency: Supports real-time applications with quick response times.
* Documentation: Detailed guides and support for easy implementation.
**Use Cases:**
* Interactive Applications: Real-time voice generation for chatbots and virtual assistants.
* On-demand Voice Generation: Seamlessly integrate into content creation workflows.
**Use Cases for Cartesia.ai:**
Cartesia.ai’s versatile platform supports a wide range of applications:
**Marketing:**
Create engaging marketing content with high-quality voiceovers, transforming scripts into professional audio quickly and efficiently.
**Real-time Applications:**
Build real-time conversational experiences with ultrafast voice synthesis, ensuring every interaction is instant and engaging.
**Content Creation:**
Simplify content creation and produce high-quality audio for videos and other media at scale, reducing the time and effort required for traditional recording methods.
**Impact on Content Creation:**
Cartesia.ai is revolutionizing content creation by providing tools that enhance productivity and engagement. By automating voice generation and integrating multimodal intelligence, creators can focus on producing high-quality content without the time-consuming task of manual media creation. This boosts productivity and allows for greater creative freedom and innovation.
**Innovation and Research:**
Cartesia.ai is committed to continuous innovation and research in AI technology. Their team of experts focuses on advancing the capabilities of multimodal AI, exploring new applications, and refining existing technologies to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Cartesia.ai. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
Cartesia.ai’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Cartesia.ai’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# LMNT
> What is LMNT?
**What is LMNT?**
LMNT is a cutting-edge AI platform that specializes in ultrafast and lifelike speech synthesis. By leveraging advanced AI technology, LMNT offers solutions for creating high-quality, natural-sounding speech from text. Their innovative voice cloning technology allows users to generate studio-quality voice replicas with minimal input, transforming the way businesses and developers create and use voice content.
**The Evolution of AI Speech Synthesis:**
AI speech synthesis has come a long way from its early, rudimentary forms to the sophisticated, lifelike voices we have today. Advances in deep learning, neural networks, and data processing have enabled the creation of speech that is virtually indistinguishable from human voices. LMNT has harnessed these advancements to provide fast, reliable, and highly expressive speech synthesis solutions.
**Overview of LMNT’s Offerings:**
LMNT provides a range of AI-driven speech synthesis tools designed to meet diverse needs:
**Ultrafast Speech Synthesis:**
* LMNT’s speech synthesis technology is designed for speed and efficiency, delivering low latency streaming that is ideal for conversational applications, virtual agents, and interactive games. This technology ensures that every interaction is immediate and engaging, enhancing user experience and operational efficiency.
**Voice Cloning:**
* LMNT offers advanced voice cloning capabilities, allowing users to create lifelike and expressive voice replicas with as little as a 5-minute recording. Instant voice clones can be generated from just 15 seconds of audio. Users can also choose from a library of pre-built voices, making it easy to find the perfect match for any project.
**Developer API:**
* LMNT provides a robust API with SDKs for Python and Node.js, enabling seamless integration of their voice synthesis capabilities into various applications. The API supports ultrafast, low-latency streaming, making it perfect for real-time voice generation and playback scenarios. Comprehensive documentation and support are available to assist developers through every step of the integration process.
**Ultrafast Speech Synthesis:**
* LMNT’s ultrafast speech synthesis technology offers several key features and benefits:
**Features:**
* Low Latency Streaming: Designed for real-time applications, ensuring quick response times.
* High Availability: Reliable performance under high loads, making it suitable for large-scale deployments.
* Expressive Voices: Capable of conveying a wide range of emotions and nuances, enhancing the naturalness of generated speech.
**Benefits:**
* Engagement: Immediate and natural interactions improve user engagement and satisfaction.
* Scalability: Handle large volumes of requests without compromising on performance or quality.
* Versatility: Suitable for a wide range of applications, from customer service to entertainment.
**Voice Cloning:**
* LMNT’s voice cloning technology sets a new standard in creating lifelike and expressive voices:
**Creating Lifelike Voices:**
* Studio-quality Cloning: Generate high-fidelity voice clones with minimal recording input.
* Instant Voice Cloning: Create usable voice clones from just a few seconds of audio.
* Voice Library: Access a diverse library of pre-built voices for immediate use.
**Applications:**
* Personalization: Create unique voices for digital assistants, characters, and branding.
* Content Creation: Generate consistent and professional voiceovers for videos, podcasts, and more.
**Developer API:**
* LMNT’s developer API simplifies the integration of voice synthesis capabilities into various projects:
**Integration:**
* SDKs: Ready-to-use SDKs for Python and Node.js.
* Low Latency: Real-time voice synthesis for interactive applications.
* Documentation: Comprehensive guides and support for easy implementation.
**Use Cases:**
* Interactive Applications: Real-time voice generation for chatbots and virtual assistants.
* On-demand Voice Generation: Seamless integration into content creation workflows.
**Use Cases for LMNT:**
* LMNT’s versatile platform supports a wide range of applications:
**Marketing:**
Create engaging product marketing videos with captivating voiceovers, turning scripts into high-quality audio content quickly and efficiently.
**Real-time Conversations:**
Build lightning-fast conversational experiences with ultrafast speech synthesis, ensuring every interaction is instant and engaging.
**Content Creation:**
Simplify content creation and produce high-quality audio for videos and avatars at scale, reducing the time and effort required for traditional recording methods.
**Impact on Content Creation:**
LMNT is revolutionizing content creation by providing tools that enhance productivity and engagement. By automating voice generation, creators can focus on producing high-quality content without the time-consuming task of manual voice recording. This not only boosts productivity but also allows for more creative freedom and innovation.
**Innovation and Research:**
LMNT is committed to continuous innovation and research in the field of AI speech synthesis. Their team of experts is dedicated to improving the naturalness, expressiveness, and versatility of AI-generated voices. By exploring new applications and refining existing technologies, LMNT aims to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at LMNT. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
LMNT’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate LMNT’s voice synthesis capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# RimeAI
> What is Rime.ai?
**What is Rime.ai?**
Rime.ai is a pioneering platform in the field of speech synthesis, offering real-time, lifelike voice generation. Specializing in creating natural-sounding voices tailored to demographic specifics, Rime.ai provides tools that allow businesses and developers to engage their audiences more effectively. By leveraging advanced AI, Rime.ai delivers high-quality audio that is indistinguishable from human speech, setting a new standard in the industry.
**The Evolution of AI Speech Synthesis:**
AI speech synthesis has come a long way from its early days of robotic-sounding outputs. Advances in machine learning, neural networks, and data processing have transformed synthetic speech into highly realistic and expressive audio. Rime.ai has harnessed these technological advancements to create voices that sound natural and convey the desired emotions and nuances.
**Overview of Rime.ai’s Offerings:**
Rime.ai provides a comprehensive suite of speech synthesis tools designed to meet various needs:
**Real-time Speech Synthesis:**
* Rime.ai’s real-time speech synthesis technology enables instant generation of lifelike voices. This is particularly useful for applications requiring immediate feedback, such as interactive voice response (IVR) systems, live virtual assistants, and real-time translation services. The technology boasts sub-300 millisecond response times, ensuring seamless and efficient communication.
**Demographically Specific Voice Control:**
* One of Rime.ai’s standout features is its ability to generate voices that are demographically specific. This means businesses can tailor their audio output to match the cultural, regional, and social characteristics of their target audience. With over 200 distinct voices available, Rime.ai allows for precise customization, enhancing user engagement and relatability.
**Use Cases for Rime.ai:**
* Rime.ai’s technology is versatile and applicable across multiple sectors:
**IVR Systems:**
* Interactive voice response systems benefit greatly from Rime.ai’s real-time speech synthesis. By providing natural and clear voices, IVR systems can improve user interactions, reduce call handling times, and enhance overall customer satisfaction.
**Newsreading:**
In the media industry, Rime.ai’s lifelike voices can be used for automated newsreading, delivering news updates in a natural and engaging manner. This ensures consistency and professionalism in audio content delivery.
**Narration:**
* For audiobooks, educational materials, and other forms of narration, Rime.ai offers high-quality voice generation that enhances the listening experience. The ability to match voices to the content’s demographic audience further adds to the personalization and effectiveness of the narration.
**Impact on Content Creation:**
Rime.ai is revolutionizing content creation by providing tools that allow for quick and efficient production of high-quality audio. By eliminating the need for traditional recording methods, creators can save time and resources while still producing professional-grade content. This democratization of audio production opens up new opportunities for innovation and creativity.
**Innovation and Research:**
Rime.ai is committed to continuous innovation and research in speech synthesis technology. Their team of experts is dedicated to improving the naturalness, expressiveness, and versatility of AI-generated voices. By exploring new applications and refining existing technologies, Rime.ai aims to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a top priority for Rime.ai. They have implemented robust safeguards to prevent misuse of their technology and are actively involved in discussions about responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their approach.
**Integrations and Compatibility:**
Rime.ai’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Rime.ai’s speech synthesis capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# Deepgram
> What is Deepgram?
**What is Deepgram?**
Deepgram is a leading AI company specializing in advanced speech recognition and transcription technology. With their state-of-the-art speech-to-text solutions, Deepgram provides fast, accurate, and scalable transcription services for various applications. By leveraging deep learning and neural networks, Deepgram delivers unparalleled audio intelligence capabilities, transforming how we interact with and analyze spoken content.
**The Evolution of Speech Recognition:**
Speech recognition technology has dramatically evolved from its early, basic forms to the sophisticated systems we have today. Initially, speech recognition systems were limited by their ability to accurately transcribe spoken language. However, advancements in machine learning, particularly deep learning, have revolutionized this field. Deepgram has harnessed these technological advancements to offer highly accurate and efficient speech recognition solutions that set a new industry standard.
**Overview of Deepgram’s Offerings:**
Deepgram offers a comprehensive suite of AI-driven speech recognition tools designed to meet diverse needs:
**Speech-to-Text:**
* Deepgram’s core offering is its speech-to-text technology, which converts spoken language into written text with high accuracy. This technology supports real-time transcription and batch processing, making it ideal for various applications, including media transcription, customer service, and accessibility enhancements.
**Audio Intelligence:**
* Deepgram’s audio intelligence capabilities go beyond simple transcription. Their technology can analyze audio to detect sentiment, intent, and topics, providing deeper insights into conversations and spoken content. This feature is particularly useful for businesses seeking to understand customer interactions and improve service delivery.
**Speech-to-Text Technology:**
* Deepgram’s speech-to-text technology stands out for its precision and speed. By utilizing end-to-end deep learning models, Deepgram achieves higher accuracy rates than traditional transcription methods. This technology can handle diverse accents, dialects, and noisy environments, ensuring reliable performance in real-world scenarios.
**Real-time Transcription:**
* Real-time transcription is one of Deepgram’s key features, enabling instant conversion of speech to text. This is particularly advantageous for applications such as live captioning, real-time customer support, and interactive voice response (IVR) systems. The ability to transcribe speech in real-time enhances user experience and operational efficiency.
**Audio Intelligence:**
* Deepgram’s audio intelligence features allow for advanced analysis of audio content. By detecting sentiment, intent, and topics within conversations, businesses can gain valuable insights into customer behavior and preferences. This information can be used to improve customer service, tailor marketing strategies, and enhance overall business intelligence.
**Use Cases for Deepgram:**
Deepgram’s technology is versatile and applicable across multiple industries:
**Media Transcription:**
In the media sector, Deepgram’s speech-to-text solutions are used to transcribe interviews, podcasts, and video content. This makes content searchable, accessible, and easier to manage, enhancing the efficiency of media production workflows.
**Contact Centers:**
* For contact centers, Deepgram provides real-time transcription and audio analysis to improve customer interactions. By transcribing calls and analyzing sentiment, businesses can identify trends, monitor agent performance, and enhance customer satisfaction.
**Healthcare:**
* In healthcare, accurate transcription is critical for maintaining patient records and documenting medical consultations. Deepgram’s speech-to-text technology ensures precise and timely transcription, aiding in effective communication and record-keeping.
**Impact on Content Creation:**
Deepgram is transforming content creation by providing tools that streamline the transcription process. By automating transcription, content creators can focus on producing high-quality material without the time-consuming task of manual transcription. This boosts productivity and opens new avenues for creative and professional work.
**Innovation and Research:**
Deepgram is committed to continuous innovation and research in the field of speech recognition and AI. Their team of experts is dedicated to enhancing the capabilities of their technology, exploring new applications, and pushing the boundaries of what speech AI can achieve.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Deepgram. They implement robust safeguards to prevent misuse of their technology and are actively engaged in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
Integrations and Compatibility
Deepgram’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Deepgram’s speech recognition capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# InworldAI
> What is Inworld.ai?
**What is Inworld.ai?**
Inworld.ai provides developers with tools to create lifelike voice agents. It supports zero-shot voice cloning, enabling the creation of personalized voices from short audio samples. The system is optimized for low-latency streaming, making it suitable for applications requiring immediate audio responses.
**The Evolution of AI Speech Synthesis:**
Advancements in deep learning and neural networks have significantly improved the quality of AI-generated speech. Inworld.ai leverages these developments to deliver natural-sounding, emotionally expressive voices suitable for various applications, including virtual assistants and interactive games.
**Overview of Inworld.ai's Offerings:**
Inworld.ai provides a comprehensive suite of features designed to meet diverse voice synthesis needs:
**Real-Time Speech Synthesis:**
Inworld.ai is engineered for low-latency performance, delivering the first two seconds of audio in approximately 200 milliseconds. This responsiveness is critical for real-time applications such as conversational agents and interactive gaming characters.
**Zero-Shot Voice Cloning:**
The platform offers zero-shot voice cloning, allowing developers to create custom voices from as little as 5 seconds of audio input. This feature facilitates the development of unique voice identities for various applications.
**Multilingual Support:**
Inworld.ai supports 11 languages, including English, Spanish, French, Korean, and Chinese. This multilingual capability enables developers to build applications for diverse global audiences.
**Audio Markup Controls:**
Developers can use audio markup tags such as \[happy], \[whispering], or \[sigh] to control the emotional tone and style of the synthesized speech. This feature enhances the expressiveness of voice agents.
**Developer API:**
Inworld.ai provides an API with comprehensive documentation, facilitating integration into various applications. The API supports real-time streaming and offers options for customizing voice parameters to suit specific use cases.
**Use Cases for Inworld.ai:**
Inworld.ai's versatile platform supports a wide range of applications:
**Interactive Applications:**
Developers can create responsive voice agents for customer service, virtual assistants, and interactive gaming characters, enhancing user engagement through natural-sounding speech.
**Content Creation:**
Content creators can utilize Inworld.ai to generate high-quality voiceovers for videos, podcasts, and other media, streamlining the production process.
**Education and Training:**
Educational platforms can employ Inworld.ai to provide clear and expressive narration for e-learning materials, improving the learning experience for users.
**Integration with Vapi:**
Inworld.ai's voice model is fully integrated with Vapi, giving developers an easy way to deploy expressive, low-latency voices in their assistants.
To use Inworld.ai's model, open your assistant in the Vapi dashboard, scroll to the Voice Configuration section, choose Inworld as the provider, select a language and voice, then hit publish. And you're live.
**Conclusion:**
Inworld.ai offers a combination of expressive voice synthesis, low-latency performance, and multilingual support, making it a valuable tool for developers seeking to enhance their applications with natural-sounding speech.
# Tavus
> What is Tavus?
**What is Tavus?**
Tavus is a leading generative AI video research company dedicated to advancing the field of personalized video communication through artificial intelligence. Founded with the mission to humanize AI interactions, Tavus has made significant strides in developing advanced AI models and APIs that enable developers to create sophisticated digital twin experiences and real-time conversational interfaces.
**The Evolution of AI in Video Personalization:**
The landscape of AI-driven video personalization has evolved significantly. Initially confined to text and static images, advancements in machine learning and deep learning have introduced dynamic, video-based personalization. Tavus leverages these technological strides to produce videos that not only replicate human likeness and voice but also deliver tailored content to each recipient.
**Overview of Tavus' Offerings:**
Tavus provides a comprehensive suite of AI-powered products and services designed to meet diverse video personalization needs:
**Automated Video Generation**
* Tavus' core video generation system represents the state-of-the-art in personalized video creation. Using advanced AI models, the platform can transform a single recording into numerous personalized versions, each tailored to individual recipients. This technology excels in maintaining natural speech patterns, facial expressions, and emotional authenticity while delivering customized content at scale.
**Conversational Video Interface (CVI):**
* The Conversational Video Interface is Tavus' breakthrough technology for real-time interactive experiences. With sub-second latency and sophisticated AI processing, CVI creates digital replicas capable of natural, dynamic interactions. This system enables applications ranging from interactive customer service to personalized educational experiences, all while maintaining human-like responsiveness.
**Integration Capabilities:**
* Tavus' robust API and integration capabilities allow seamless incorporation with existing business systems, including CRM platforms and marketing tools. This technical framework enables developers to enhance their applications with advanced video personalization features while maintaining workflow efficiency.
**Use Cases for Tavus:**
Tavus’ technologies are versatile and applicable across multiple sectors:
**Customer Experience:**
* Businesses leverage Tavus' video generation capabilities to create personalized customer interactions at scale. The system's ability to generate customized video content enhances engagement rates and improves customer satisfaction through more personal, direct communication.
**Innovation and Research:**
* Tavus is committed to ongoing innovation in AI and video technology. The platform continually evolves to improve the realism of generated videos and expand the range of customization options. Research efforts focus on enhancing the AI's capabilities while ensuring ethical standards are upheld.
**AI Safety and Ethics:**
* Ethical use of AI is a core principle for Tavus. The company implements strict guidelines and technical measures to prevent misuse of its technology, such as unauthorized impersonation. User consent and data protection are paramount, and Tavus complies with relevant regulations to safeguard personal information.
**Integrations and Compatibility:**
* Tavus' API allows seamless integration with various platforms and applications. This ensures that developers can incorporate Tavus' video generation and real-time interaction capabilities into their existing systems, enhancing functionality and improving user experience. The API is designed to be flexible and developer-friendly, accommodating a wide range of enterprise use cases.
# OpenAI
> What is OpenAI?
**What is OpenAI?**
OpenAI is a leading artificial intelligence research and deployment company dedicated to ensuring that artificial general intelligence (AGI) benefits all of humanity. Founded with the mission to create safe and highly capable AI systems, OpenAI has made significant strides in AI research, producing groundbreaking models like GPT-4o, DALL-E, and Codex. These innovations have not only advanced the field of AI but also transformed various industries by providing powerful tools for natural language processing, image generation, and programming assistance.
**The Evolution of AI Research:**
The field of AI has evolved rapidly over the past few decades. From early rule-based systems to modern deep learning models, AI technology has made significant progress in mimicking human intelligence. OpenAI has been at the forefront of this evolution, pushing the boundaries of what AI can achieve through continuous research and development. Their work on large language models and neural networks has set new benchmarks for performance and capability in AI systems.
**Overview of OpenAI’s Offerings:**
OpenAI offers a range of AI-driven products and services designed to meet diverse needs:
**GPT Models:**
* OpenAI’s Generative Pre-trained Transformer (GPT) models, including the latest GPT-4o, are state-of-the-art in natural language processing. These models can generate human-like text, answer questions, summarize information, and perform various language tasks with high accuracy. GPT-4o, in particular, represents a significant leap in AI capabilities, offering improved coherence, context understanding, and creativity.
**DALL-E:**
* DALL-E is OpenAI’s revolutionary image generation model that creates detailed and imaginative images from text descriptions. By combining deep learning with creative processes, DALL-E can produce unique artwork, design concepts, and visual content that aligns with the given textual input. This technology opens new possibilities for artists, designers, and content creators.
**Codex:**
* Codex is an AI model that assists with programming by understanding and generating code. Integrated into tools like GitHub Copilot, Codex can help developers write code faster and more efficiently by suggesting code snippets, debugging errors, and automating repetitive tasks. This enhances productivity and reduces the barrier to entry for learning programming languages.
**GPT-4 Technology:**
* GPT-4 is the latest and most advanced language model developed by OpenAI. It excels in generating coherent and contextually relevant text, making it a powerful tool for various applications, including chatbots, content creation, and automated customer support. With enhanced capabilities for understanding and generating human language, GPT-4 sets a new standard in AI-driven communication.
**DALL-E Image Generation:**
* DALL-E takes text-to-image generation to new heights, allowing users to create visually stunning and highly specific images based on textual descriptions. This technology is particularly valuable for creative industries, where generating unique visuals quickly and accurately is essential. From concept art to marketing materials, DALL-E provides a versatile tool for visual content creation.
**Codex and Programming Assistance:**
* Codex transforms the way developers interact with code by providing intelligent suggestions and automating routine programming tasks. This AI-powered assistant understands multiple programming languages and can generate code snippets, making coding more accessible and efficient. Integrated into platforms like GitHub Copilot, Codex helps streamline the development process and accelerates software production.
**Use Cases for OpenAI:**
OpenAI’s technologies are versatile and applicable across various sectors:
**Education:**
In education, GPT-4 and Codex can enhance learning experiences by providing personalized tutoring, generating educational content, and assisting with coding exercises. These tools help students grasp complex concepts and improve their programming skills.
**Business:**
Businesses leverage OpenAI’s models for automating customer support, generating marketing content, and analyzing large volumes of text data. GPT-4’s ability to understand and generate human-like text enhances customer interactions and drives operational efficiency.
**Creative Industries:**
In the creative sector, DALL-E and GPT-4 enable artists and writers to generate new ideas, create unique visuals, and produce high-quality content. These tools expand creative possibilities and streamline content production workflows.
**Innovation and Research:**
OpenAI is committed to advancing AI through continuous research and innovation. Their team of researchers and engineers works on developing new models, improving existing technologies, and exploring novel applications of AI. This commitment to innovation ensures that OpenAI remains at the cutting edge of the field.
**AI Safety and Ethics:**
Ensuring the safe and ethical use of AI is a core principle at OpenAI. They implement rigorous safety measures to prevent misuse and ensure that their technologies are used responsibly. OpenAI is also involved in global discussions about AI ethics and governance, contributing to the development of best practices and standards for the industry.
**Integrations and Compatibility:**
OpenAI’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate OpenAI’s AI capabilities into their existing systems, enhancing functionality and improving user experience. The API is designed to be flexible and user-friendly, accommodating a wide range of use cases.
# Gemini by Google
> What is Gemini?
**What is Gemini?**
Gemini is Google's latest artificial intelligence (AI) initiative, developed by Google DeepMind, designed to enhance user experiences across various platforms by integrating advanced AI capabilities into everyday applications. It represents a significant advancement in AI technology, offering multimodal understanding and reasoning across text, images, audio, video, and code.
**The Evolution of AI Research:**
Over the years, AI research has progressed from simple rule-based systems to complex deep learning models capable of understanding and generating human-like content. Google has been at the forefront of this evolution, with Gemini marking a new era in AI development. Built from the ground up for multimodality, Gemini can seamlessly process and integrate various types of information, setting new benchmarks in AI performance and capability.
**Overview of Gemini’s Offerings:**
Gemini offers a range of AI-driven products and services designed to meet diverse user needs:
**Gemini Chat:**
* A conversational AI assistant that helps users with writing, planning, learning, and more. It enhances creativity and productivity by providing intelligent suggestions and assistance.
**Gemini Advanced:**
* A subscription-based service providing access to Google's most capable AI models, such as Gemini 1.5 Pro and Imagen 3. It offers a 1 million token context window, enabling the processing of extensive documents and complex tasks. Users can create custom AI experts, edit Python code, and receive priority access to new features.
**Gemini API:**
* A developer-focused platform that allows integration of Gemini's AI capabilities into applications. It supports multimodal inputs, including text, images, audio, and video, enabling developers to build innovative AI-powered solutions.
**Gemini 1.5 Technology:**
Gemini 1.5 is Google's latest foundation model, delivering enhanced performance and a breakthrough in long-context understanding across modalities. It utilizes a new Mixture-of-Experts architecture, allowing it to process up to 1 million tokens, enabling new capabilities and applications.
**Use Cases for Gemini:**
Gemini's technologies are versatile and applicable across various sectors:
**Education:**
* Gemini can assist in generating educational content, providing personalized tutoring, and aiding in research by analyzing large volumes of academic material.
**Business:**
* Businesses can leverage Gemini for automating customer support, generating marketing content, and analyzing data to gain insights, thereby enhancing operational efficiency.
**Creative Industries:**
* In the creative sector, Gemini enables artists and writers to generate new ideas, create unique visuals, and produce high-quality content, expanding creative possibilities.
**Innovation and Research:**
Google is committed to advancing AI through continuous research and innovation. Their team of researchers and engineers works on developing new models, improving existing technologies, and exploring novel applications of AI. This commitment to innovation ensures that Google remains at the cutting edge of the field.
**AI Safety and Ethics:**
Ensuring the safe and ethical use of AI is a core principle at Google. They implement rigorous safety measures to prevent misuse and ensure that their technologies are used responsibly. Google is also involved in global discussions about AI ethics and governance, contributing to the development of best practices and standards for the industry.
**Integrations and Compatibility:**
Gemini's API allows seamless integration with various platforms and applications, ensuring that users can incorporate Gemini's AI capabilities into their existing systems, enhancing functionality and improving user experience. The API is designed to be flexible and user-friendly, accommodating a wide range of use cases.
In summary, Gemini represents a significant advancement in AI technology, offering versatile and powerful tools that enhance creativity, productivity, and efficiency across various domains.
# Groq
> What is Groq?
**What is Groq?**
Groq is a pioneering technology company specializing in high-performance AI inference solutions. Known for its innovative GroqChip, Groq delivers unparalleled speed and efficiency in AI processing. Their platform is designed to handle complex AI workloads with low latency, making it ideal for a variety of applications, including autonomous systems, data centers, and real-time AI inference.
**The Evolution of AI Inference:**
AI inference has evolved significantly, from simple rule-based systems to advanced neural networks that require substantial computational power. Groq has harnessed cutting-edge advancements in hardware and software to create solutions that meet the growing demands for speed and accuracy in AI processing.
**Overview of Groq’s Offerings:**
Groq offers a suite of high-performance AI tools and solutions designed to support various industries:
**GroqChip:**
The GroqChip is the cornerstone of Groq’s offerings, providing unmatched performance for AI inference tasks. Its architecture is optimized for low latency and high throughput, making it ideal for demanding AI applications.
**GroqWare:**
GroqWare is a suite of software tools that support the deployment and management of AI models on Groq hardware. It includes drivers, compilers, and libraries designed to optimize performance and simplify integration.
**GroqCloud:**
GroqCloud offers cloud-based access to Groq’s high-performance computing resources. This service allows businesses to leverage Groq’s powerful AI infrastructure without the need for significant capital investment in hardware.
**High-Performance AI Inference:**
Groq’s AI inference technology offers several key features and benefits:
**Features:**
* Low Latency: Ensures rapid processing of AI workloads.
* High Throughput: Capable of handling large volumes of data efficiently.
* Scalability: Easily scales to meet the demands of growing applications.
**Benefits:**
* Efficiency: Reduces the time required to process AI tasks.
* Reliability: Delivers consistent performance even under heavy loads.
* Cost-Effectiveness: Offers a competitive advantage with efficient resource utilization.
**GroqChip Technology:**
The GroqChip stands out for its advanced architecture and performance capabilities:
**Architecture:**
* Optimized Design: Tailored for AI inference with specialized processing units.
* High Efficiency: Maximizes performance per watt, reducing energy consumption.
**Performance:**
* Unmatched Speed: Delivers top-tier performance for real-time AI applications.
* Low Latency: Ensures minimal delay in processing, critical for time-sensitive tasks.
**Applications:**
* Autonomous Systems: Enhances the performance of self-driving cars and drones.
* Data Centers: Boosts the efficiency and capacity of AI data centers.
**Low Latency AI:**
Groq’s low-latency AI solutions provide real-time processing capabilities essential for various applications:
**Real-time Processing:**
* Immediate Response: Critical for applications requiring instant decision-making.
* High Reliability: Ensures consistent performance with minimal delays.
**Use Cases:**
* AI Research: Accelerates experimentation and model testing.
* Autonomous Systems: Improves the safety and efficiency of autonomous vehicles.
**Developer API and Tools:**
Groq offers a comprehensive API and a range of development tools to facilitate integration and optimization:
**Integration:**
* SDKs: Available for multiple programming languages.
* Comprehensive Documentation: Guides and support for seamless implementation.
**Use Cases:**
Application Development: Streamline the integration of AI capabilities into applications.
* Application Development: Streamline the integration of AI capabilities into applications.
* Research and Experimentation: Provides tools for efficient AI model deployment and testing.
**Use Cases for Groq:**
Groq’s platform supports a wide range of applications across various industries:
**AI Research:**
Facilitates cutting-edge research with high-performance AI infrastructure.
**Autonomous Systems:**
Enhances the capabilities of autonomous vehicles and robotics with low-latency processing.
**Data Centers:**
Improves the efficiency and capacity of data centers handling AI workloads.
**Impact on AI Development:**
Groq is transforming AI development by providing tools that enhance productivity and efficiency. By automating and optimizing AI inference, developers can focus on innovation and application rather than infrastructure management.
**Innovation and Research:**
Groq is committed to continuous innovation and research in AI inference technology. Their team of experts focuses on advancing the capabilities of AI hardware and software, exploring new applications, and refining existing technologies to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Groq. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
Groq’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Groq’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# DeepInfra
> DeepInfra is a provider for Vapi.
**What is DeepInfra?**
DeepInfra is an innovative platform that provides scalable and cost-effective infrastructure for deploying machine learning models. By offering a simple API and autoscaling capabilities, DeepInfra allows businesses and developers to efficiently manage and deploy AI models, ensuring high performance and low latency. This platform supports a wide range of AI applications, making it an ideal solution for diverse industries.
**The Evolution of AI Infrastructure:**
AI infrastructure has advanced from on-premises solutions to cloud-based platforms that offer flexibility, scalability, and cost efficiency. DeepInfra leverages these advancements to provide robust and scalable infrastructure, enabling seamless deployment and management of machine learning models.
**Overview of DeepInfra’s Offerings:**
DeepInfra offers a comprehensive suite of tools and services designed to support various AI applications:
**Machine Learning Models:**
DeepInfra provides access to a wide range of pre-trained machine learning models, including text generation, text-to-image, automatic speech recognition, and embeddings. These models are optimized for performance and can be easily integrated into various applications.
**API:**
DeepInfra’s API allows for easy integration of machine learning models into applications, offering low latency and high availability. The API supports various programming languages, making it accessible to a broad range of developers.
**Scalability:**
DeepInfra’s infrastructure is designed to scale automatically based on demand, ensuring optimal performance and cost efficiency. This scalability is crucial for handling large volumes of requests and maintaining low latency.
**Machine Learning Model Deployment:**
DeepInfra’s model deployment capabilities offer several key features and benefits:
**Features:**
* Low Latency Streaming: Ensures quick response times for real-time applications.
* High Availability: Delivers reliable performance even under heavy loads.
* Expressive Models: Provides high-quality outputs for various AI tasks.
**Benefits:**
* Efficiency: Reduces the time and resources needed for model deployment.
* Scalability: Handles large volumes of requests without compromising performance.
* Cost-Effectiveness: Offers pay-per-use pricing, minimizing upfront costs.
**Scalable Infrastructure:**
DeepInfra’s scalable infrastructure provides several advantages:
**Autoscaling:**
* Dynamic Resource Allocation: Automatically adjusts resources based on demand.
* Consistent Performance: Maintains low latency and high availability during peak usage.
**Low Latency:**
* Optimized Network: Ensures fast data transmission and processing.
* Regional Deployment: Deploys models close to users for reduced latency.
**Cost Efficiency:**
* Pay-per-Use Pricing: Charges based on actual usage, avoiding unnecessary costs.
* Resource Sharing: Maximizes infrastructure utilization, reducing overall expenses.
**Developer API:**
DeepInfra offers a robust API with comprehensive documentation and SDKs, facilitating seamless integration:
**Integration:**
* SDKs: Available for multiple programming languages.
* Low Latency: Supports real-time applications with quick response times.
* Documentation: Detailed guides and support for easy implementation.
**Use Cases:**
* Research: Efficiently access and analyze vast amounts of data.
* Application Development: Integrate advanced AI capabilities into applications.
* Business Intelligence: Gain insights for strategic decision-making.
**Use Cases for DeepInfra:**
DeepInfra’s versatile platform supports a wide range of applications:
**Research:**
Facilitate academic and scientific research with efficient and accurate AI model deployment.
**Application Development:**
Streamline the development process by integrating high-performance AI models into applications.
**Business Intelligence:**
Enhance business operations with powerful AI models that provide valuable insights and data analysis.
**Impact on AI Development:**
DeepInfra is revolutionizing AI development by providing tools that enhance productivity and efficiency. By automating the deployment process and offering scalable infrastructure, developers can focus on innovation and optimization rather than infrastructure management.
**Innovation and Research:**
DeepInfra is committed to continuous innovation and research in AI infrastructure. Their team of experts focuses on advancing the capabilities of machine learning models and exploring new applications, ensuring that they remain at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at DeepInfra. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
DeepInfra’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate DeepInfra’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# Perplexity
> What is Perplexity.ai?
**What is Perplexity.ai?**
Perplexity.ai is an advanced AI-powered search engine that delivers precise and real-time answers to user queries. Utilizing state-of-the-art AI algorithms and knowledge graphs, Perplexity.ai enhances the search experience by providing structured and accurate information. This innovative platform is designed to cater to diverse needs, from research and education to business intelligence, making information retrieval more efficient and reliable.
**The Evolution of AI Search Engines:**
Search engines have significantly evolved from simple keyword-based systems to sophisticated AI-driven platforms capable of understanding and answering complex queries. Advances in natural language processing, machine learning, and data integration have revolutionized how search engines operate. Perplexity.ai leverages these advancements to offer a more intuitive and accurate search experience, setting a new standard in information retrieval.
**Overview of Perplexity.ai’s Offerings:**
Perplexity.ai provides a range of AI-driven tools designed to enhance search capabilities:
**AI-Powered Answers:**
Perplexity.ai’s core offering is its AI-powered search engine, which delivers accurate and relevant answers to user queries. The AI algorithms understand the context and intent behind each query, providing precise and comprehensive results.
**Knowledge Graphs:**
Perplexity.ai integrates knowledge graphs to enhance search results with structured and interconnected information. This feature helps users understand the relationships between different entities and access detailed insights quickly.
**Real-time Information:**
Perplexity.ai ensures that users receive the most up-to-date information by continuously updating its database. This real-time capability is crucial for queries requiring the latest data and developments.
**AI-Powered Search Technology:**
Perplexity.ai’s search technology offers several key features and benefits:
**Features:**
* Contextual Understanding: Interprets the context and intent behind queries for accurate answers.
* Comprehensive Results: Provides detailed and relevant information, enhancing the search experience.
* User-Friendly Interface: Intuitive design for easy navigation and quick access to information.
**Benefits:**
* Efficiency: Reduces the time needed to find accurate information.
* Reliability: Delivers precise and trustworthy results.
* Enhanced Insights: Offers deeper understanding through structured knowledge graphs.
**Knowledge Graphs:**
Perplexity.ai’s knowledge graphs enrich search results by organizing information into structured entities and relationships:
**Enhancing Search Results:**
* Interconnected Information: Displays related entities and their connections.
* Detailed Insights: Provides comprehensive information at a glance, improving understanding.
**Real-time Information:**
Perplexity.ai’s real-time information feature ensures users receive the latest data and updates:
**Providing Up-to-date Answers:**
* Continuous Updates: Regularly refreshes data to maintain accuracy.
* Timely Information: Crucial for time-sensitive queries and decisions.
**Developer API:**
Perplexity.ai offers a robust API for easy integration into various applications:
**Integration:**
* SDKs: Available for multiple programming languages.
* Documentation: Comprehensive guides and support for seamless implementation.
**Use Cases:**
* Research: Efficiently access and analyze vast amounts of data.
* Business Intelligence: Gain insights for strategic decision-making.
Use Cases for Perplexity.ai
Perplexity.ai’s versatile platform supports a wide range of applications:
**Research:**
Facilitate academic and scientific research with accurate and comprehensive information retrieval.
**Education:**
Enhance learning experiences by providing students and educators with reliable answers and insights.
**Business Intelligence:**
Support business decisions with precise data and detailed analyses.
**Impact on Information Retrieval:**
Perplexity.ai is revolutionizing information retrieval by providing tools that enhance productivity and accuracy. By automating the search process and integrating knowledge graphs, users can quickly access relevant information, reducing the time and effort required for manual data collection.
**Innovation and Research:**
Perplexity.ai is committed to continuous innovation and research in AI search technology. Their team of experts focuses on advancing the capabilities of AI algorithms and knowledge graphs, exploring new applications, and refining existing technologies to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Perplexity.ai. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
Perplexity.ai’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Perplexity.ai’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# TogetherAI
> TogetherAI is a provider for Vapi.
**What is Together AI?**
Together AI is a leading cloud platform designed for building and running generative AI models. It provides state-of-the-art AI inference, fine-tuning capabilities, and high-performance GPU clusters, enabling businesses and developers to harness the full potential of AI. Together AI focuses on speed, scalability, and cost-efficiency, making it an ideal solution for various AI applications.
**The Evolution of AI Cloud Platforms:**
AI cloud platforms have significantly evolved, offering more powerful and efficient solutions for AI model deployment and training. Advances in cloud computing, GPU technology, and AI algorithms have enabled platforms like Together AI to provide comprehensive services that cater to modern AI needs.
**Overview of Together AI’s Offerings:**
Together AI offers a range of AI-driven tools and services:
**AI Inference:**
Together AI provides the fastest AI inference stack available, ensuring quick and efficient processing of AI tasks. This service supports large-scale deployments and offers significant cost savings.
**Fine-Tuning:**
Together AI enables users to fine-tune leading open-source models with their private data, achieving greater accuracy for specific tasks. This service supports various models, including LLaMA-2, RedPajama, and more.
**GPU Clusters:**
Together AI offers high-performance GPU clusters for large-scale training and fine-tuning. These clusters are equipped with top-tier hardware like NVIDIA A100 and H10 GPUs, ensuring optimal performance and scalability.
**AI Inference Technology:**
Together AI’s inference technology offers several key features and benefits:
**Features:**
* High Speed: Provides the fastest inference on the market.
* Scalability: Easily scales to handle large volumes of requests.
* Cost Efficiency: Offers lower costs compared to traditional inference services.
**Benefits:**
* Efficiency: Reduces the time required for AI tasks.
* Reliability: Ensures consistent and high-quality performance.
* Flexibility: Adapts to various application needs.
**Fine-Tuning and Custom Models:**
Together AI’s fine-tuning capabilities allow users to personalize AI models with their private data:
**Personalizing AI Models:**
* Custom Data Integration: Fine-tune models with specific datasets for improved accuracy.
* Wide Model Support: Supports various open-source models for diverse applications.
**GPU Clusters:**
Together AI’s GPU clusters provide high-performance hardware for AI training:
**High-Performance Hardware:**
* NVIDIA A100 and H100 GPUs: Equipped with the latest GPU technology for optimal performance.
* Scalable Clusters: Available in configurations ranging from 16 to 2048 GPUs.
**Developer API:**
Together AI offers a comprehensive API for easy integration:
**Integration:**
* SDKs: Available for multiple programming languages.
* Comprehensive Documentation: Detailed guides and support for seamless implementation.
**Use Cases:**
* Business Solutions: Enhance operational efficiency and decision-making.
* Research: Facilitate academic and scientific research with advanced AI tools.
* Content Creation: Automate and optimize content production processes.
**Use Cases for Together AI:**
Together AI supports a wide range of applications across various sectors:
**Business Solutions:**
Leverage AI to improve business operations, enhance customer experiences, and drive innovation.
**Research:**
Utilize advanced AI tools to support academic and scientific research.
**Content Creation:**
Enhance content creation with high-quality AI-generated text, images, and more.
**Impact on AI Development:**
Together AI is transforming AI development by providing tools that enhance productivity and innovation. By offering scalable and cost-effective solutions, developers can focus on creating advanced AI applications without worrying about infrastructure constraints.
**Innovation and Research:**
Together AI is committed to continuous innovation and research in AI technology. Their team of experts focuses on advancing the capabilities of AI models and exploring new applications to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Together AI. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
Together AI’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Together AI’s capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# OpenRouter
> What is OpenRouter?
**What is OpenRouter?**
OpenRouter is a cutting-edge AI platform offering a unified interface for integrating multiple large language models (LLMs). Designed to streamline AI access, OpenRouter provides a comprehensive suite of tools and APIs that enable businesses and developers to leverage a variety of LLMs for diverse applications. This platform focuses on enhancing efficiency, scalability, and cost-effectiveness.
**The Evolution of AI Integration:**
AI integration has significantly evolved from isolated systems to unified platforms that provide seamless access to multiple AI models. Advances in API technology, cloud computing, and machine learning have enabled platforms like OpenRouter to offer comprehensive solutions that cater to modern AI needs.
**Overview of OpenRouter’s Offerings:**
OpenRouter provides a range of AI-driven tools and services:
**LLM Access:**
OpenRouter offers access to a wide variety of LLMs, including models specialized in different tasks such as roleplaying, programming, marketing, and more. This allows users to select the best models for their specific needs.
**APIs:**
OpenRouter’s robust APIs enable developers to integrate LLM capabilities into their applications, ensuring low latency and high availability. The APIs support multiple programming languages, making them accessible to a broad range of developers.
**Unified Interface:**
OpenRouter provides a unified interface that simplifies the process of accessing and managing multiple AI models. This interface enhances usability and efficiency, making it easier to deploy and utilize AI solutions.
**AI Integration Technology:**
OpenRouter’s AI integration technology offers several key features and benefits:
**Features:**
* Unified Access: Provides a single interface for managing multiple AI models.
* High Availability: Ensures reliable performance even under heavy loads.
* Scalability: Easily scales to meet the demands of growing applications.
**Benefits:**
* Efficiency: Reduces the time and resources needed for AI integration.
* Flexibility: Supports a wide range of applications and use cases.
* Cost-Effectiveness: Offers competitive pricing compared to traditional solutions.
**Unified Access to LLMs:**
OpenRouter excels in providing unified access to multiple LLMs:
**Combining Multiple Models in One Interface:**
* Streamlined Management: Simplifies the process of accessing and managing different AI models.
* Diverse Applications: Supports various tasks, from programming to marketing.
**Developer API:**
OpenRouter offers a comprehensive API for easy integration:\*\*
**Integration:**
* SDKs: Available for multiple programming languages.
* Comprehensive Documentation: Detailed guides and support for seamless implementation.
**Use Cases:**
* Business Solutions: Enhance operational efficiency and decision-making.
* Research: Facilitate academic and scientific research with advanced AI tools.
* Content Creation: Automate and optimize content production processes.
**Use Cases for OpenRouter:**
OpenRouter supports a wide range of applications across various sectors:
**Business Solutions:**
Leverage AI to improve business operations, enhance customer experiences, and drive innovation.
**Research:**
Utilize advanced AI tools to support academic and scientific research.
**Content Creation:**
Enhance content creation with high-quality AI-generated text, images, and more.
**Impact on AI Development:**
OpenRouter is transforming AI development by providing tools that enhance productivity and innovation. By offering scalable and cost-effective solutions, developers can focus on creating advanced AI applications without worrying about infrastructure constraints.
**Innovation and Research:**
OpenRouter is committed to continuous innovation and research in AI integration. Their team of experts focuses on advancing the capabilities of AI models and exploring new applications to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at OpenRouter. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
OpenRouter’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate OpenRouter’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# Deepgram
> What is Deepgram?
**What is Deepgram?**
Deepgram is a leading AI company specializing in advanced speech recognition and transcription technology. With their state-of-the-art speech-to-text solutions, Deepgram provides fast, accurate, and scalable transcription services for various applications. By leveraging deep learning and neural networks, Deepgram delivers unparalleled audio intelligence capabilities, transforming how we interact with and analyze spoken content.
**The Evolution of Speech Recognition:**
Speech recognition technology has dramatically evolved from its early, basic forms to the sophisticated systems we have today. Initially, speech recognition systems were limited by their ability to accurately transcribe spoken language. However, advancements in machine learning, particularly deep learning, have revolutionized this field. Deepgram has harnessed these technological advancements to offer highly accurate and efficient speech recognition solutions that set a new industry standard.
**Overview of Deepgram’s Offerings:**
Deepgram offers a comprehensive suite of AI-driven speech recognition tools designed to meet diverse needs:
**Speech-to-Text:**
* Deepgram’s core offering is its speech-to-text technology, which converts spoken language into written text with high accuracy. This technology supports real-time transcription and batch processing, making it ideal for various applications, including media transcription, customer service, and accessibility enhancements.
**Audio Intelligence:**
* Deepgram’s audio intelligence capabilities go beyond simple transcription. Their technology can analyze audio to detect sentiment, intent, and topics, providing deeper insights into conversations and spoken content. This feature is particularly useful for businesses seeking to understand customer interactions and improve service delivery.
**Speech-to-Text Technology:**
* Deepgram’s speech-to-text technology stands out for its precision and speed. By utilizing end-to-end deep learning models, Deepgram achieves higher accuracy rates than traditional transcription methods. This technology can handle diverse accents, dialects, and noisy environments, ensuring reliable performance in real-world scenarios.
**Real-time Transcription:**
* Real-time transcription is one of Deepgram’s key features, enabling instant conversion of speech to text. This is particularly advantageous for applications such as live captioning, real-time customer support, and interactive voice response (IVR) systems. The ability to transcribe speech in real-time enhances user experience and operational efficiency.
**Audio Intelligence:**
* Deepgram’s audio intelligence features allow for advanced analysis of audio content. By detecting sentiment, intent, and topics within conversations, businesses can gain valuable insights into customer behavior and preferences. This information can be used to improve customer service, tailor marketing strategies, and enhance overall business intelligence.
**Use Cases for Deepgram:**
Deepgram’s technology is versatile and applicable across multiple industries:
**Media Transcription:**
In the media sector, Deepgram’s speech-to-text solutions are used to transcribe interviews, podcasts, and video content. This makes content searchable, accessible, and easier to manage, enhancing the efficiency of media production workflows.
**Contact Centers:**
* For contact centers, Deepgram provides real-time transcription and audio analysis to improve customer interactions. By transcribing calls and analyzing sentiment, businesses can identify trends, monitor agent performance, and enhance customer satisfaction.
**Healthcare:**
* In healthcare, accurate transcription is critical for maintaining patient records and documenting medical consultations. Deepgram’s speech-to-text technology ensures precise and timely transcription, aiding in effective communication and record-keeping.
**Impact on Content Creation:**
Deepgram is transforming content creation by providing tools that streamline the transcription process. By automating transcription, content creators can focus on producing high-quality material without the time-consuming task of manual transcription. This boosts productivity and opens new avenues for creative and professional work.
**Innovation and Research:**
Deepgram is committed to continuous innovation and research in the field of speech recognition and AI. Their team of experts is dedicated to enhancing the capabilities of their technology, exploring new applications, and pushing the boundaries of what speech AI can achieve.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Deepgram. They implement robust safeguards to prevent misuse of their technology and are actively engaged in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
Integrations and Compatibility
Deepgram’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Deepgram’s speech recognition capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# Google
## What is Gemini by Google?
Gemini is Google’s latest artificial intelligence (AI) initiative, developed by Google DeepMind, designed to enhance user experiences across various platforms by integrating advanced AI capabilities into everyday applications. It represents a significant advancement in AI technology, offering multimodal understanding and reasoning across text, images, audio, video, and code.
## How to use Google as transcriber
This guide details how to setup Google as a transcriber for your assistant.
**Head to the "Assistants" tab in your Vapi dashboard.**
**Click on your assistant and then the "Transcriber" tab.**
**Select "google" on the Provider dropdown.**
You can also adjust the model and language from the dropdown.
**Click on "Publish" and talking with your assistant.**
## Supported Languages
Gemini by default is "Multilingual" and supports a [wide range of languages](https://ai.google.dev/gemini-api/docs/models/gemini#available-languages). However, if you prefer to use a specific language, you can select an option from the dropdown.
# Gladia
> What is Gladia?
**What is Gladia?**
Gladia is an advanced AI platform specializing in real-time transcription, translation, and audio intelligence. By leveraging state-of-the-art ASR (Automatic Speech Recognition), NLP (Natural Language Processing), and GenAI (Generative AI) models, Gladia helps businesses extract valuable insights from unstructured audio data. Their enterprise-grade API offers scalable, secure, and efficient solutions for various applications, from virtual meetings to customer service.
**The Evolution of AI Transcription:**
AI transcription has significantly evolved, moving from basic speech recognition systems to advanced platforms capable of real-time transcription, translation, and audio intelligence. Innovations in machine learning and natural language processing have enhanced accuracy and efficiency. Gladia utilizes these advancements to deliver top-tier transcription services tailored for modern business needs.
**Overview of Gladia’s Offerings:**
Gladia provides a comprehensive suite of AI-driven tools:
**Speech-to-Text:**
Gladia’s core offering is its AI-powered speech-to-text technology, delivering highly accurate and real-time transcription. This service supports 99 languages and includes speaker diarization and code-switching.
**Audio Intelligence:**
Gladia’s audio intelligence add-ons offer features like summarization, chapterization, and sentiment analysis, providing deeper insights into audio data.
**API:**
Gladia’s robust API allows seamless integration of speech-to-text capabilities into applications, ensuring low latency and high availability.
**AI Transcription Technology:**
Gladia’s AI transcription technology offers several key features and benefits:
**Features:**
* High Accuracy: Industry-leading transcription accuracy.
* Real-time and Async Transcription: Instantaneous and batch processing options.
* Multilingual Support: Supports transcription and translation in 99 languages.
**Benefits:**
* Efficiency: Reduces the time needed for transcription and analysis.
* Scalability: Handles large volumes of data efficiently.
* Cost-Effective: Provides high performance at a competitive cost.
**Real-time Transcription and Translation:**
Gladia excels in providing real-time transcription and translation:
**Multilingual Support:**
* 99 Languages: Supports a wide range of languages and dialects.
* Real-time Translation: Near-instantaneous translation for diverse applications.
**Use Cases:**
* Virtual Meetings: Provides real-time transcriptions, note-taking, and video captions.
* Content Creation: Transcribes and translates videos and podcasts for global audiences.
**Developer API:**
Gladia offers a comprehensive API for easy integration:
**Integration:**
* SDKs: Available for multiple programming languages.
* Comprehensive Documentation: Detailed guides and support for seamless implementation.
**Use Cases:**
* Application Development: Enhance applications with advanced AI capabilities.
* Business Solutions: Improve operational efficiency and customer service.
**Use Cases for Gladia:**
Gladia supports a wide range of applications:
**Content Creation:**
Enhance content creation with high-quality transcription, translation, and subtitling.
**Customer Service:**
Improve customer service with accurate call transcriptions and emotion detection.
**Market Research:**
Gain valuable insights into market trends and customer preferences through advanced speech analysis.
**Impact on Business Operations:**
Gladia is revolutionizing business operations by providing tools that enhance productivity and insights. By automating transcription and audio intelligence, businesses can focus on innovation and strategy rather than manual processes.
**Innovation and Research:**
Gladia is committed to continuous innovation and research in AI transcription. Their team of experts focuses on advancing the capabilities of ASR and NLP technologies, exploring new applications, and refining existing tools to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Gladia. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
Gladia’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Gladia’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# Talkscriber
> What is Talkscriber?
**What is Talkscriber?**
Talkscriber is an advanced AI-powered speech-to-text platform designed to deliver high-accuracy transcription and emotion detection. Focused on enterprise-grade solutions, Talkscriber provides secure, cost-effective, and flexible deployment options. This platform enhances business operations by converting spoken language into text and analyzing customer interactions for deeper insights.
**The Evolution of Speech-to-Text:**
Speech-to-text technology has significantly evolved, from basic voice recognition to sophisticated AI-driven transcription systems. Innovations in machine learning and natural language processing have paved the way for more accurate and efficient speech-to-text solutions. Talkscriber leverages these advancements to offer state-of-the-art transcription services that cater to modern enterprise needs.
**Overview of Talkscriber’s Offerings:**
Talkscriber offers a suite of AI-driven tools designed to support various applications:
**AI Transcription:**
Talkscriber’s core service is its AI-powered transcription technology, which converts spoken language into text with high accuracy. This technology supports multiple languages and dialects, making it versatile for global applications.
**Emotion Detection:**
Talkscriber includes advanced emotion detection capabilities, identifying emotions such as anger, joy, sadness, and surprise. This feature provides deeper insights into customer interactions and helps businesses understand their clients better.
**API:**
Talkscriber provides a robust API that allows developers to integrate its speech-to-text capabilities into their applications, ensuring low latency and high availability.
**AI Transcription Technology:**
Talkscriber’s AI transcription technology offers several key features and benefits:
**Features:**
* High Accuracy: Industry-leading transcription accuracy with a Word Error Rate (WER) under 4%.
* Real-time Transcription: Instantaneous conversion of speech to text.
* Multilingual Support: Supports multiple languages and dialects.
**Benefits:**
* Efficiency: Reduces the time needed to transcribe and analyze speech.
* Scalability: Handles large volumes of data efficiently.
* Cost-Effective: Provides high performance at a lower cost compared to other solutions.
**Emotion and Intent Detection:**
Talkscriber’s emotion detection capabilities enhance the analysis of customer interactions:
**Enhancing Interaction Analysis:**
* Emotion Detection: Identifies emotions at the utterance level, providing deeper insights.
* Purchase Intent Detection: Recognizes customer purchase intent, helping businesses tailor their strategies.
**Developer API:**
Talkscriber offers a comprehensive API for easy integration of their capabilities into various applications:
**Integration:**
* SDKs: Available for multiple programming languages.
* Comprehensive Documentation: Detailed guides and support for seamless implementation.
**Use Cases:**
* Business Solutions: Enhance operational efficiency and customer service.
* Market Research: Gain insights into customer behavior and preferences.
**Use Cases for Talkscriber:**
Talkscriber’s platform supports a wide range of applications across various sectors:
**Business Solutions:**
Improve business operations with accurate transcription and emotion detection.
**Customer Service:**
Enhance customer service by understanding and responding to customer emotions and intents.
**Market Research:**
Gain valuable insights into market trends and customer preferences through advanced speech analysis.
**Impact on Business Operations:**
Talkscriber is revolutionizing business operations by providing tools that enhance productivity and insights. By automating transcription and emotion detection, businesses can focus on innovation and strategy rather than manual processes.
**Innovation and Research:**
Talkscriber is committed to continuous innovation and research in speech AI. Their team of experts focuses on advancing the capabilities of AI transcription and emotion detection, exploring new applications, and refining existing technologies to stay at the forefront of the industry.
**AI Safety and Ethics:**
Ensuring the ethical use of AI is a core principle at Talkscriber. They implement robust safeguards to prevent misuse of their technology and are actively involved in promoting responsible AI development. Protecting user data and maintaining transparency in AI operations are central to their mission.
**Integrations and Compatibility:**
Talkscriber’s API allows seamless integration with various platforms and applications. This ensures that users can incorporate Talkscriber’s AI capabilities into their existing systems effortlessly, enhancing functionality and improving user experience.
# AssemblyAI
## Universal-Streaming
Universal-Streaming is AssemblyAI's purpose-built speech-to-text model that delivers ultra-fast, immutable transcripts in \~300ms with intelligent endpointing and superior accuracy for voice agents. It eliminates common pain points like misheard account numbers, awkward pauses, and premature cutoffs, enabling more natural and successful voice interactions.
## How to use AssemblyAI as transcriber
This guide details how to setup AssemblyAI as a transcriber for your assistant.
**Head to the "Assistants" tab in your Vapi dashboard.**
**Click on your assistant and then the "Transcriber" tab.**
**Select "assembly-ai" on the Provider dropdown.**
## Supported Languages
Universal-Streaming currently supports English only.
# AWS S3
> Store recordings of chat conversations in AWS S3
Your assistants can be configured to record chat conversations and upload
the recordings to a bucket in AWS S3 when the conversation ends. You will
need to configure the credential and bucket settings in the "Cloud Providers"
section of the "Provider Credentials" page in the Vapi dashboard.
See these [instructions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html) for generating AWS access keys.
## Credential Settings
| Setting | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AWS Access Key ID | The access key id for AWS |
| AWS Secret Access Key | The secret access key for AWS |
| S3 Bucket Name | The name of the bucket to upload recordings to |
| Bucket Path Prefix | An optional path prefix for recordings uploaded to the bucket. Supports [LiquidJS Date format](https://liquidjs.com/filters/date.html) templating - for example, `{{ "now" \| date: "%Y/%m/%d" }}` renders as YYYY/MM/DD. |
## Example
# GCP Cloud Storage
> Store recordings of chat conversations in GCP Cloud Storage
Your assistants can be configured to record chat conversations and upload
the recordings to a bucket in GCP Cloud Storage when the conversation ends. You will
need to configure the credential and bucket settings in the "Cloud Providers"
section of the "Provider Credentials" page in the Vapi dashboard.
See these [instructions](https://cloud.google.com/iam/docs/keys-create-delete) for generating service account keys for GCP.
See these [instructions](https://cloud.google.com/storage/docs/authentication/hmackeys) for generating HMAC Keys for Cloud Storage.
## Credential Settings
| Setting | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Credential Reference Name | The credential reference name |
| GCP Service Account Key (JSON) | The service account key in JSON format |
| Bucket Name | The name of the bucket to upload recordings to |
| Bucket Region | The name of the region where the bucket is located |
| Bucket Path Prefix | An optional path prefix for recordings uploaded to the bucket. Supports [LiquidJS Date format](https://liquidjs.com/filters/date.html) templating - for example, `{{ "now" \| date: "%Y/%m/%d" }}` renders as YYYY/MM/DD. |
| HMAC Access Key | The HMAC access key for the GCP Cloud Storage API (This is a string of 24 characters when linked to a user account or a string of 61 characters when linked to a service account.) |
| HMAC Secret | The HMAC secret for the GCP Clodu Storage API (This is a 40-character base-64 encoded string.) |
## Example
# Cloudflare R2
> Store recordings of chat conversations in Cloudflare R2
Your assistants can be configured to record chat conversations and upload
the recordings to a bucket in Cloudflare R2 when the conversation ends. You will
need to configure the credential and bucket settings in the "Cloud Providers"
section of the "Provider Credentials" page in the Vapi dashboard.
See these [instructions](https://developers.cloudflare.com/r2/api/s3/tokens/) for generating R2 tokens and access keys.
## Credential Settings
| Setting | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloudflare Account ID | Your customer account id for Cloudflare |
| Cloudflare Account Email | The email address associated with the account id |
| Cloudflare API Key/Token | The value of an API Key/Token generated for the account (Cloudflare uses the terms API Key and API Token interchangeably) |
| Bucket Name | The name of the bucket in R2 to upload recordings to |
| Bucket URL | This is required only for buckets with a custom hostname or domain name. Enter the hostname for the bucket. You will need to set up a CORS policy in R2 for the hostname/domain name. See [instructions](https://developers.cloudflare.com/r2/buckets/cors/) for configuring CORS. |
| Bucket Path Prefix | An optional path prefix for recordings uploaded to the bucket. Supports [LiquidJS Date format](https://liquidjs.com/filters/date.html) templating - for example, `{{ "now" \| date: "%Y/%m/%d" }}` renders as YYYY/MM/DD. |
| Bucket Access Key ID | The access key id associated with the API token you generated for R2 (this a string of 32 characters) |
| Bucket Secret Access Key | The secret access key associated with the API token you generated for R2 (this is a string of 64 characters) |
## Example
# Supabase S3 Storage
> Store recordings of chat conversations in Supabase Storage
Your assistants can be configured to record chat conversations and upload
the recordings to a bucket in Supabase Storage when the conversation ends. You will
need to configure the credential and bucket settings in the "Cloud Providers"
section of the "Provider Credentials" page in the Vapi dashboard.
See these [instructions](https://supabase.com/docs/guides/storage/s3/authentication) for generating Supabase tokens and access keys, and finding your endpoint and region.
## Credential Settings
| Setting | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bucket Name | The name of the bucket in Supabase Storage to upload recordings to |
| Storage Region | The region of the Supabase project |
| Storage Endpoint | The endpoint of the Supabase Storage to upload recordings to |
| Bucket Path Prefix | An optional path prefix for recordings uploaded to the bucket. Supports [LiquidJS Date format](https://liquidjs.com/filters/date.html) templating - for example, `{{ "now" \| date: "%Y/%m/%d" }}` renders as YYYY/MM/DD. |
| Storage Access Key ID | The access key id for Supabase Storage |
| Storage Secret Access Key | The secret access key for Supabase Storage, associated with the access key id |
## Example
# Langfuse Integration with Vapi
> Integrate Vapi with Langfuse for enhanced voice AI telemetry monitoring, enabling improved performance and reliability of your AI applications.
# Langfuse Integration
Vapi natively integrates with Langfuse, allowing you to send traces directly to Langfuse for enhanced telemetry monitoring. This integration enables you to gain deeper insights into your voice AI applications and improve their performance and reliability.
## What is Langfuse?
[Langfuse](https://langfuse.com/) is an open source LLM engineering platform designed to provide better **[observability](/docs/tracing)** and **[evaluations](/docs/scores/overview)** into AI applications. It helps developers track, analyze, and visualize traces from AI interactions, enabling better performance tuning, debugging, and optimization of AI agents.
## Get Started
First, you'll need your Langfuse credentials:
* **Secret Key**
* **Public Key**
* **Host URL**
You can obtain these by signing up for [Langfuse Cloud](https://cloud.langfuse.com/) or [self-hosting Langfuse](https://langfuse.com/docs/deployment/self-host).
Log in to your Vapi dashboard and navigate to the [Provider Credentials page](https://dashboard.vapi.ai/keys).
Under the **Observability Providers** section, you'll find an option for **Langfuse**. Enter your Langfuse credentials:
* **Secret Key**
* **Public Key**
* **Host URL** (US data region: `https://us.cloud.langfuse.com`, EU data region: `https://cloud.langfuse.com`)
Click **Save** to update your credentials.
Once you've added your credentials, you should start seeing traces in your Langfuse dashboard for every conversation your agents have.
Example trace in Langfuse: [https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/50163c14-9784-4cb9-b18e-23e924d0bb66](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/50163c14-9784-4cb9-b18e-23e924d0bb66)
To make the most out of this integration, you can now use Langfuse's [evaluation](https://langfuse.com/docs/scores/overview) and [debugging](https://langfuse.com/docs/analytics/overview) tools to analyze and improve the performance of your voice AI agents.
## Enrich Traces
Vapi allows you to enrich Langfuse traces by integrating [Metadata](https://langfuse.com/docs/tracing-features/metadata) and [Tags](https://langfuse.com/docs/tracing-features/tags).
By default, we will add the following values to the metadata of each trace:
* `call.metadata`
* `assistant.metadata`
* `assistantOverrides.metadata`
* `assistantOverrides.variableValues`
### Usage
You can enhance your observability in Langfuse by adding metadata and tags:
**Metadata**
Use the [`assistant.observabilityPlan.metadata`](/api-reference/assistants/create#request.body.observabilityPlan.metadata) field to attach custom key-value pairs.
Examples:
* Track experiment versions ("experiment": "v2.1")
* Store user segments ("user\_type": "beta\_tester")
* Log environment details ("env": "production")
**Tags**
Use the [`assistant.observabilityPlan.tags`](/api-reference/assistants/create#request.body.observabilityPlan.tags) field to add searchable labels.
Examples:
* Mark important runs ("priority")
* Group related sessions ("onboarding", "A/B\_test")
* Filter by feature ("voice\_assistant")
Adding metadata and tags makes it easier to filter, analyze, and monitor your assistants activity in Langfuse.
### Example
# Voiceflow
> Vapi x Voiceflow
## Overview
Voiceflow is a conversational AI platform that helps teams build, manage, and deploy AI agents, especially chatbots, to enhance customer experiences. It enables users to create advanced AI chatbots without coding, using a user-friendly drag-and-drop flow builder. This feature allows businesses to customize chatbot interactions and efficiently automate customer support processes.
To link Vapi with Voiceflow, host a proxy using Voiceflow's AI features. This proxy handles requests from Voiceflow, sends them to Vapi's text completion API, and returns Vapi's responses to Voiceflow. You'll need to host this proxy on your server to manage communication between Vapi and Voiceflow.
## Workshop
The workshop conducted by Vapi in collaboration with Voiceflow provided an in-depth exploration of building voice agents using the Voiceflow platform, deployed through Vapi. During this session, participants learned how to create voice agents that leverage Voiceflow's user-friendly design tools alongside Vapi's voice capabilities. The workshop featured a live demonstration, where attendees could see the entire process of building a voice agent in real-time, including designing the agent, setting up necessary integrations, and testing functionality.
By the end of the workshop, participants gained insights into building and deploying voice agents, practical skills in designing conversational flows, and an understanding of voice agents.
# ChatDash Integration with Vapi
> ChatDash is a white-label dashboard platform that integrates with Vapi to provide analytics, call logs, and Stripe billing for AI agent agencies.
ChatDash is a white-label client dashboard platform designed for AI agent agencies. Our seamless integration with Vapi is engineered for simplicity—just enter your Vapi Agent ID and API Key, and your dashboard is up instantly with real-time analytics, detailed call logs, and comprehensive Stripe billing integration.
## Key Benefits
* **Quick Setup:**
Simply input your Vapi Agent ID and API Key, and ChatDash instantly pulls in data to configure your dashboard.
* **Instant Analytics & Call Logs:**
Gain immediate access to real-time analytics and detailed call logs from your Vapi agent, so you can monitor performance as soon as you're set up.
* **Custom Branding:**
Fully customize your dashboard with your own logo, domain, and color scheme. Deliver a professional, branded experience that aligns perfectly with your agency's identity.
* **Automated Stripe Billing:**
Enjoy seamless, usage-based billing through Stripe integration. ChatDash automates client invoicing and manages charges—such as call minutes—without any hassle.
## How It Works
1. **Enter Your Credentials:**
Provide your Vapi Agent ID and API Key in ChatDash.
2. **Dashboard Setup:**
ChatDash automatically configures your dashboard with live analytics and call logs.
3. **Customize Your Experience:**
Apply your custom branding elements to ensure your dashboard reflects your agency's professional look.
4. **Monitor & Optimize:**
Use your comprehensive dashboard to track performance, manage billing, and make data-driven decisions—all in one place.
## See It in Action
Watch our step-by-step tutorial video to see how easy it is to integrate Vapi into ChatDash and get your branded dashboard live with integrated billing:
[Watch the Tutorial Video](https://www.youtube.com/watch?v=Ah7eA88m1Xw)
## Get Started
Integrating Vapi with ChatDash is designed to be hassle-free, so you can start delivering a premium, branded client experience right away. For questions or support, please reach out to our team at [support@chatdash.com](mailto:support@chatdash.com).
# Vapify Integration with Vapi
> Vapify is a white-label dashboard for Vapi. It helps you turn your agency into a voice AI powerhouse—without writing a single line of code.
Vapify is a white-label platform for Vapi that simplifies how agencies sell and deliver Vapi-powered voice AI solutions. It provides a business infrastructure that helps drive agency growth and profitability.
## Key Benefits
* **Seamless Integration:**
Seamlessly integrate Vapify with your Vapi setup. To get started, all you need is a Vapi key - zero coding required.
* **Comprehensive Analytics:**
Get access to detailed call logs, recordings, and client-ready reporting.
* **White-Label Experience:**
Use your own professional branding — your logo, your domain, your own email address.
* **Batch Calling:** ✨
Batch calling capabilities for high-volume applications and efficient outreach campaigns.
* **Rebilling:** ✨
Set custom monthly pricing and markup voice assistant prices.
* **Rapid Implementation:**
Deploy your voice assistants and allow your clients to test them.
## How It Works
1. **Connect Your Vapi Account:**
Link your Vapi API credentials in one simple step.
2. **Configure Your Agency Hub:**
Customize your dashboard with your branding and pricing structure.
3. **Onboard Clients:**
Use our guided process to create tailored packages for each client.
4. **Scale Without Limits:**
Add clients without increasing technical overhead.
## Beyond Basic Integration
Vapify provides a complete agency growth system:
| Vapify Advantage | What This Means For Your Agency |
| ------------------------------ | ------------------------------------------------------------------------------ |
| Implementation Packages | Get expert guidance to compress weeks of learning into days |
| Strategic Support | Receive personalized guidance on pricing and positioning your services |
| Batch Calling Capabilities | Handle high-volume voice campaigns that basic integrations can't support |
| Deep Integration Possibilities | Integrate vapify into your custom agency setup using our customisation options |
## Get Started
Integrate Vapi with Vapify to build a profitable voice AI agency with minimal technical investment.
[Schedule a Demo](https://cal.com/kakoma/vapify-demo) | [Watch Tutorial Video](https://youtu.be/Zgsb_cAj_PU?si=2oxj4ZEyES_1650v)
For questions or support, please reach out to our team at [support@info.vapify.agency](mailto:support@info.vapify.agency).
*Visit [vapify.agency](https://vapify.agency) to learn how agencies are building profitable voice AI service lines with our platform.*
# Voicerr AI - Whitelabel AI Voice Agents
> Voicerr AI is a Vapi-powered voice platform that lets agencies brand dashboards, automate billing, launch campaigns, and run full call-center operations at unlimited scale.
## Overview
If you’ve been looking for a **vapi ai voice whitelabel** that does more than swap a logo, **Voicerr AI** is the answer.\
Built directly on Vapi’s voice APIs, it transforms raw call data into polished dashboards, automated Stripe billing, high-volume campaigns, and lead-generation workflows — all under **your** brand, domain, and pricing.
Key pillars:
* **Unlimited agents, clients & sites** – grow freely without per-tenant charges.
* **Real-time metrics & searchable call logs** – every conversation at your fingertips.
* **Batch-calling campaigns** – reach thousands of prospects in minutes.
* **Flexible pricing & markup** – flat-rate, usage, or hybrid plans with threshold charging.
* **Lead Finder + Automation Lab** – discover prospects, trigger workflows, and close the loop.
* **Human support on live chat** – our team is always one message away.
***
## Why Agencies Choose Voicerr AI
| Voicerr Advantage | What It Means for You |
| -------------------------- | ------------------------------------------------------------ |
| Instant white-label portal | Launch a branded site, logo, and domain in minutes. |
| Deep Vapi sync | Assistants, numbers, and recordings pulled with one API key. |
| Automated Stripe billing | Invoices, payments, and markup handled for you. |
| Growth tools included | Lead Finder, outbound calls, and multi-step workflows. |
| Unlimited scale | One flat price whether you serve 1 client or 1000. |
By branding Voicerr you can **whitelabel AI voice agents** for every client while keeping your margins intact.
***
## How It Works
1. **Connect Vapi** – Paste your Organization ID and Private Key; Voicerr syncs assistants, numbers, and minutes instantly.
2. **Brand & price** – Upload your logo, map a custom domain, and create plans with your desired markup.
3. **Onboard clients** – Add clients manually or let them self-sign-up; choose exactly what each client can see or edit.
4. **Scale & automate** – Use Lead Finder to gather prospects, trigger Batch Calling campaigns, and wire everything together with Automation Lab workflows.
Because everything updates in real time, you can confidently **sell AI voice agents** with dashboards that always reflect the latest data.
Need outbound power? Batch Calling makes it easy to **sell AI voice callers** for high-volume campaigns.\
Prefer a turnkey contact-center offer? Package dashboards, analytics, and billing together and **sell AI call center** solutions under your own domain.
***
## Platform Walk-through
***
[Visit Voicerr.ai](https://voicerr.ai) | Email [ritvik@voicerr.ai](mailto:ritvik@voicerr.ai)
Unlock unlimited agents, callers, automation workflows, and call-center revenue streams with **Voicerr AI + Vapi** today.
# Support
> We are open to all kinds of help inquiry, feedback and feature request, help inquiry.
## Our Support Options
We offer multiple ways to get support with your Vapi projects:
Email [support@vapi.ai](mailto:support@vapi.ai) with your request and our team will get back to you promptly.
Join our active developer community on [Discord](https://discord.com/invite/pUFNcf2WmH) for real-time collaboration and submit support tickets and questions in the #support channel.
Get 24/7 dedicated support from our forward-deployed engineering team with an enterprise plan.
For fastest response times and hands-on technical support, we recommend enterprise customers reach out through their dedicated support channels.
## Feature Requests and Bug Reports
We welcome feature requests and feedback from our users to help improve Vapi. You can:
Submit and vote on feature requests on our public roadmap board to help shape the future of Vapi.
Report any bugs or issues you encounter while using Vapi to help us improve the platform.
We actively monitor and prioritize feature requests based on user votes and feedback. Popular requests help inform our product roadmap.
## Additional Resources
Access helpful reference materials to better understand Vapi's platform and get answers to common questions:
Find definitions for common terms and concepts used throughout the Vapi platform.
Browse our frequently asked questions for quick answers to common inquiries.
# How to Report Issues Effectively
> Learn how to structure your issue reports for fast and accurate resolution
To help us assist you as quickly and accurately as possible, it's essential to provide specific and actionable details when reporting issues. Vague messages like "X is not working" slow down the resolution process.
This guide will help you structure your reports to get the best support experience.
## Types of Issues
We handle three main categories of issues. Choose the appropriate category and follow the specific guidelines for faster resolution:
Unexpected assistant behavior, voice issues, transcription errors, or call failures.
Interface problems, configuration errors, or dashboard functionality issues.
Login problems, account upgrades, billing issues, or verification needs.
## Assistant-Related Issues
If you're experiencing issues with assistant behavior, voice quality, transcription accuracy, or call connectivity, follow these guidelines:
### Required Information
When reporting assistant-related issues, always include:
* **Call ID** from the test call
* **Timestamp** where the issue occurred in the recording
* **Detailed description** of what happened
* **Expected behavior** vs. actual behavior
* **Screen recording** (for web-based calls showing the issue)
### Finding Your Call ID
Navigate to [https://dashboard.vapi.ai/calls](https://dashboard.vapi.ai/calls)
Find the specific call where the issue occurred
Copy the Call ID from the call details
### Example Report Format
```
Call ID: 9ac27e94-74a5-4061-8a0b-3c05389c63bd
Timestamp: 00:30
Issue: The assistant paused for 5 seconds before replying
Expected: The assistant should respond within 1 second without delay
Browser: Chrome 120.0 (if web call)
Screen Recording: [attached/linked]
```
If the call never connected or failed completely, simply share the Call ID and we'll investigate the connection logs.
### Iterative Debugging Process
Assistant issues often require multiple rounds of testing and refinement. After each change or suggestion from our team:
1. Test the updated configuration
2. Share the new Call ID
3. Describe the results and any improvements
4. Continue until the issue is resolved
This iterative feedback helps us identify and fix issues efficiently.
## Dashboard & UI Issues
For problems with the Vapi dashboard interface, configuration screens, or any visual/functional issues in the web application:
### Required Information
* **Screen recording** or screenshots showing the issue
* **Browser information** (Chrome, Firefox, Safari + version)
* **Operating system** (Windows, macOS, Linux)
* **Steps to reproduce** the issue
* **Console errors** (if any - press F12 to open developer tools)
* **URL** where the issue occurs
### Creating Effective Screen Recordings
* **macOS**: Press Cmd+Shift+5 for screen recording
* **Windows**: Use Xbox Game Bar (Win+G) or built-in screen recorder
* **Browser**: Use Loom, CloudApp, or similar tools
Start recording before the issue occurs and show the complete workflow
Explain what you're trying to do and what's going wrong
Open browser developer tools (F12) if you see any error messages
### Example Report Format
```
URL: https://dashboard.vapi.ai/assistants/create
Browser: Chrome 120.0.6099.109
OS: macOS 14.1
Issue: Save button becomes unresponsive after adding custom tools
Steps to reproduce:
1. Navigate to assistant creation page
2. Add 3+ custom tools
3. Click Save - button grays out but doesn't save
Console errors: TypeError: Cannot read property 'id' of undefined
Screen recording: [link to recording]
```
## Account-Related Issues
For issues related to your account, billing, login, or organization settings, provide the following information:
### Required Information
* **Email address** used for your account login
* **Organization ID** (for organization-level inquiries)
* **Detailed description** of the issue
* **Screenshots** of error messages or unexpected behavior
### Finding Your Organization ID
Go to [https://dashboard.vapi.ai/org/settings](https://dashboard.vapi.ai/org/settings)
Locate and copy your Organization ID from the settings page
### Example Report Format
```
Email: user@example.com
Organization ID: c6fba1b9-3e07-429e-b265-4ce3bbef1627
Issue: Unable to upgrade to the Pro plan - payment processing fails
Error message: "Payment method declined"
Screenshot: [attached]
```
## Quick Reference
Use this checklist to ensure you're providing the right information for your issue type:
| Issue Type | Required Information |
| --------------------------- | -------------------------------------------------------------------------- |
| Assistant behavior problems | Call ID, timestamp, issue description, expected behavior, screen recording |
| Call connection failures | Call ID only |
| Dashboard/UI issues | Screen recording, browser info, steps to reproduce, console errors |
| Login or authentication | Email address, screenshots of errors |
| Account upgrades or billing | Organization ID, email address, error screenshots |
| Feature requests | Detailed description of desired functionality |
## Best Practices
* **Be specific**: Instead of "it's not working," describe exactly what happened
* **Include context**: Mention what you were trying to accomplish
* **Test consistently**: Use the same configuration when reproducing issues
* **Document changes**: Keep track of what modifications you've made
* **Record everything**: Screen recordings are invaluable for UI and workflow issues
* **Check console**: Browser console errors provide crucial debugging information
Following these guidelines helps us resolve your issues faster and more accurately. Our support team can provide targeted assistance when we have the right information upfront.
# Vapi Enterprise
> Build and scale with Vapi.
If you're building a production application on Vapi, we can help you every step of the way from idea to full-scale deployment.
#### Enterprise Plans include:
* Unlimited concurrency and higher rate limits
* Reserved capacity on our weekly deployment cluster
* Hands-on support from a dedicated Forward-Deployed Engineer
* Shared Slack channel and regular check-in calls with our team
* HIPAA BAA and SOC 2 (Type II) certified
* Single Sign On (SSO) supported for Okta, Azure AD, SAML, and OIDC
# On-Prem Deployments
> Deploy Vapi in your private cloud.
Vapi On-Prem allows you to deploy Vapi's best in class enterprise voice infrastructure AI directly in your own cloud. It can be deployed in a dockerized format on any cloud provider, in any geographic location, running on your GPUs.
With On-Prem, your audio and text data stays in your cloud. Data never passes through Vapi's servers. If you're are handling sensitive data (e.g. health, financial, legal) and are under strict data requirements, you should consider deploying on-prem.
Your device regularly sends performance and usage information to Vapi's cloud. This data helps adjust your device's GPU resources and is also used for billing. All network traffic from your device is tracked in an audit log, letting your engineering or security team see what the device is doing at all times.
## Frequently Asked Questions
#### Can the appliance adjust to my needs?
Yes, the Vapi On-Prem appliance automatically adjusts its GPU resources to handle your workload as required by our service agreement. It can take a few minutes to adjust to changes in your workload. If you need quicker adjustments, you might want to ask for more GPUs by contacting [support@vapi.ai](mailto:support@vapi.ai).
#### What if I can’t get enough GPUs from my cloud provider?
If you're struggling to get more GPUs from your provider, contact [support@vapi.ai](mailto:support@vapi.ai) for help.
#### Can I access Vapi's AI models?
No, our AI models are on secure machines in your Isolated VPC and you can’t log into these machines or check their files.
#### How can I make sure my data stays within my cloud?
Your device operates in VPCs that you control. You can check the network settings and firewall rules, and look at traffic logs to make sure everything is as it should be. The Control VPC uses open source components, allowing you to make sure the policies are being followed. Performance data and model updates are sent to Vapi, but all other traffic leaving your device is logged, except for the data sent back to your API clients.
## Contact us
For more information about Vapi On-Prem, please contact us at [support@vapi.ai](mailto:support@vapi.ai)
# Definitions
> Useful terms and definitions for Vapi & voice AI applications.
## A
### At-cost
"At-cost" is often use when discussing pricing. It means "without profit to the seller". Vapi charges at-cost for requests made to [STT](/glossary#stt), [LLM](/glossary#large-language-model), & [TTS](/glossary#tts) providers.
## B
### Backchanneling
A [backchannel](https://en.wikipedia.org/wiki/Backchannel_\(linguistics\)) occurs when a listener provides verbal or non-verbal feedback to a speaker during a conversation.
Examples of backchanneling in English include such expressions as "yeah", "OK", "uh-huh", "hmm", "right", and "I see".
This feedback is often not semantically significant to the conversation, but rather serves to signify the listener's attention, understanding, sympathy, or agreement.
## E
### Endpointing
See [speech endpointing](/glossary#speech-endpointing).
## I
### Inbound Call
This is a call received by an assistant ***from*** another phone number (w/ the assistant being the "person" answering). The call comes **"in"**-ward to a number (from an external caller) — hence the term "inbound call".
### Inference
You may often hear the term "run inference" when referring to running a large language model against an input prompt to receive text output back out.
The process of running a prompt against an LLM for output is called "inference".
## L
### Large Language Model
Large Language Models (or "LLM", for short) are machine learning models trained on large amounts of text, & later used to generate text in a probabilistic manner, "token-by-token".
For further reading see [large language model wiki](https://en.wikipedia.org/wiki/Large_language_model).
### LLM
See [Large Language Model](/glossary#large-language-model).
## O
### Outbound Call
This is a call made by an assistant ***to*** another target phone number (w/ the assistant being the "person" dialing). The call goes **"out"**-ward to another number — hence the term "outbound call".
## S
### Server URL
A "server url" is an endpoint you expose to Vapi to receive conversation data in real-time. Server urls can reply with meaningful responses, distinguishing them from traditional [webhooks](/glossary#webhook).
See our [server url](/server-url) guide to learn more.
### SDK
Stands for "Software Development Kit" — these are pre-packaged libraries & platform-specific building tools that a software publisher creates to expedite & increase the ease of integration for developers.
### Speech Endpointing
Speech endpointing is the process of detecting the start and end of (a line of) speech in an audio signal. This is an important function in conversation turn detection.
A starting heuristic for the end of a user's speech is the detection of silence. If someone does not speak for a certain amount of milliseconds, the utterance can be considered complete.
A more robust & ideal approach is to actually understand what the user is saying (as well as the current conversation's state & the speech turn's intent) to determine if the user is just pausing for effect, or actually finished speaking.
Vapi uses a combination of silence detection and machine learning models to properly endpoint conversation speech (to prevent improper interruption & encourage proper [backchanneling](/glossary#backchanneling)).
Additional reading on speech endpointing can be found [here](https://en.wikipedia.org/wiki/Speech_segmentation) & on [Deepgram's docs](https://developers.deepgram.com/docs/endpointing).
### STT
An abbreviation used for "Speech-to-text". The process of converting physical sound waves into raw transcript text (a process called "transcription").
## T
### Telemarketing Sales Rule
The Telemarketing Sales Rule (or "TSR" for short) is a regulation established by the Federal Trade Commission ([ftc.gov](https://www.ftc.gov/)) in the United States to protect consumers from deceptive and abusive telemarketing practices.
**You may only conduct outbound calls to phone numbers which you have consent to contact.** Violating TSR rules can result in significant civil (or even criminal) penalties.
Learn more on the [FCC website](https://www.ftc.gov/legal-library/browse/rules/telemarketing-sales-rule).
### TTS
An abbreviation used for "Text-to-speech". The process of converting raw text into playable audio data.
## V
### Voice-to-Voice
"Voice-to-voice" is often a term brought up in discussing voice AI system latency — the time it takes to go from a user finishing their speech (however that endpoint is computed) → to the AI agent's first speech chunk/byte being played back on a client’s device.
Ideally, this process should happen in \<1s, better if closer to 500-700ms (responding too quickly can be an issue as well). Voice AI applications must closely watch this metric to ensure their applications stay responsive & usable.
## W
### Webhook
A webhook is a server endpoint you expose to external services with the intention of receiving external data in real-time. Your exposed URL is essentially a "drop-bin" for data to come in from external providers to update & inform your systems.
Traditionally, webhooks are unidirectional & stateless. Endpoints only reply with status code to signal acknowledgement.
To make the distinction clear, Vapi calls these "[server urls](/server-url)".
Certain requests made to your server (like assistant requests) require a reply
with meaningful data.
# RSS Feed
> Stay updated with the latest incidents from Vapi or third party providers
## RSS Feed
Vapi provides a RSS feed for the latest incidents. You can subscribe to the RSS feed to get the latest incidents from Vapi or underlying providers using the following URL.
```
https://status.vapi.ai/feed.rss
```
### Slack
You can subscribe to the RSS feed in any application that supports it. In this guide, we will show you how to use the Slack RSS app to subscribe to our RSS feed.
#### How to subscribe
1. **Install the Slack RSS App**
* Ensure the [Slack RSS app](https://slack.com/marketplace/A0F81R7U7) is installed in your Slack workspace.
2. **Open the Desired Channel**
* Go to the Slack channel where you wish to receive RSS updates.
3. **Subscribe to the RSS Feed**
* Enter the following command in the message input box:
```
/feed subscribe https://status.vapi.ai/feed.rss
```
* Press Enter to subscribe.
4. **Confirm Subscription**
* The Slack RSS app will confirm your subscription, and updates will start appearing in the channel.
You will now receive updates in your Slack channel whenever there is an incident.
#### How to unsubscribe
1. **Open the Desired Channel**
* Go to the Slack channel from which you want to unsubscribe.
2. **List Subscribed Feeds**
* Enter the command:
```
/feed list
```
* Press Enter to view all subscribed feeds.
3. **Identify the Feed ID**
* Note the ID of the feed you wish to unsubscribe from.
4. **Remove the Feed**
* Enter the command:
```
/feed remove
```
* Press Enter to remove the feed from the channel.
You will no longer receive updates in the specified Slack channel.
# JWT Authentication
> Secure API authentication guide
This documentation provides an overview of JWT (JSON Web Token) Authentication and demonstrates how to generate a JWT token and use it to authenticate API requests securely.
## Prerequisites
Before you proceed, ensure you have the following:
* An environment that supports JWT generation and API calls (e.g., a programming language or framework)
* An account with a service that requires JWT authentication
* Environment variables set up for the necessary credentials (e.g., organization ID and private key, both can be found in your Vapi portal)
## Generating a JWT Token
The following steps outline how to generate a JWT token:
1. **Define the Payload**: The payload contains the data you want to include in the token. In this case, it includes an `orgId`.
2. **Get the Private Key**: The private key (provided by Vapi) is used to sign the token. Ensure it is securely stored, often in environment variables.
3. **Set Token Options**: Define options for the token, such as the expiration time (`expiresIn`).
4. **Generate the Token**: Use a JWT library or built-in functionality to generate the token with the payload, key, and options.
### JWT Token Scopes
The generated JWT token can have one of two scopes: `private` or `public`. The scope of the token will determine the actions that can be performed using the token.
For example, it can be used to restrict which API endpoints the token can access.
As of writing, the only publicly scoped API endpoint is
[https://api.vapi.ai/call/web](https://api.vapi.ai/call/web), which is used for Web Call creation. All other
endpoints are privately scoped.
### Example (generating a private JWT token)
```js
// Define the payload
const payload = {
orgId: process.env.ORG_ID,
token: {
// This is the scope of the token
tag: "private",
},
};
// Get the private key from environment variables
const key = process.env.PRIVATE_KEY;
// Define token options
const options = {
expiresIn: "1h",
};
// Generate the token using a JWT library or built-in functionality
const token = generateJWT(payload, key, options);
```
### Example (generating a public JWT token)
```js
// Define the payload
const payload = {
orgId: process.env.ORG_ID,
// This is the scope of the token
token: {
tag: "public",
restrictions: {
enabled: true,
allowedOrigins: ["https://example.vapi.ai"],
allowedAssistantIds: ["1cbf8c70-5fd7-4f61-a220-376ab35be1b0"],
allowTransientAssistant: false,
},
},
};
// Get the private key from environment variables
const key = process.env.PRIVATE_KEY;
// Define token options
const options = {
expiresIn: "1h",
};
// Generate the token using a JWT library or built-in functionality
const token = generateJWT(payload, key, options);
```
### Explanation
* **Payload**: The payload includes the `orgId` representing the organization ID and the `token` object with the scope of the token.
* **Key**: The private key is used to sign the token, ensuring its authenticity.
* **Options**: The `expiresIn` option specifies that the token will expire in 1 hour.
* **Token Generation**: The `generateJWT` function (a placeholder for the actual JWT generation method) creates the token using the provided payload, key, and options.
## Usage (Making an Authenticated API Request)
If you set the scope to `private`, you can use it to make authenticated API requests. The following steps outline how to make an authenticated request:
1. **Define the API Endpoint**: Specify the URL of the API you want to call.
2. **Set the Headers**: Include the `Content-Type` and `Authorization` headers in your request. The `Authorization` header should include the generated JWT token prefixed with `Bearer`.
3. **Make the API Call**: Use an appropriate method to send the request and handle the response.
### Example
```js
async function getAssistants() {
const response = await fetch("https://api.vapi.ai/assistant", {
method: "GET",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${token}`,
},
});
const data = await response.json();
console.log(data);
}
fetchData().catch(console.error);
```
### Explanation
* **API Endpoint**: The URL of the API you want to call.
* **Headers**: The `Content-Type` is set to `application/json`, and the `Authorization` header includes the generated JWT token.
* **API Call**: The `fetchData` function makes an asynchronous GET request to the specified API endpoint and logs the response.
### Usage (Web Client)
If you set the scope to `public`, you can use it to make authenticated API requests using the Vapi Web Client.
```
import Vapi from '@vapi-ai/web';
const vapi = new Vapi('your-jwt-token');
vapi.start('your-assistant-id');
```
# GDPR Compliance
> Learn how Vapi ensures GDPR compliance for its voice assistant platform.
At Vapi, safeguarding your personal data is our top priority. In full alignment with the General Data Protection Regulation (GDPR), we maintain robust standards for data protection and privacy. This document provides an overview of our data processing practices, legal bases, data subject rights, and the security measures we employ—all designed to ensure that your data is managed with the utmost care.
## Data Processing & Legal Bases
Our operations involve the secure processing of various types of personal data to enhance and deliver the Vapi service. We process information such as email addresses, names, phone numbers, physical addresses, usage statistics, and location data. The legal grounds underpinning this processing are:
* **Consent:** Users voluntarily provide consent for non-essential data processing (e.g., location-based services and marketing communications). This consent can be withdrawn at any time.
* **Contractual Necessity:** We process the data essential for fulfilling the services offered through Vapi, as detailed in our terms of service.
* **Legitimate Interests:** Data is processed to improve service functionality, enhance security, and analyze usage patterns, provided that our legitimate interests do not override your rights.
## Data Subject Rights
Vapi ensures that every user benefits from the robust rights granted by the GDPR. These rights include:
* **Right to Access:** You can request and obtain a copy of your personal data.
* **Right to Rectification:** If your data is inaccurate or incomplete, you can request corrections.
* **Right to Erasure (Right to be Forgotten):** Under certain conditions, you can ask for your personal data to be deleted.
* **Right to Restrict Processing:** You have the option to limit how your data is processed.
* **Right to Data Portability:** You can obtain and transfer your data in a structured, commonly used format.
* **Right to Withdraw Consent:** If your data processing is based on consent, you can withdraw it at any time.
## Data Security Measures
We deploy a range of technical and organizational safeguards to protect your personal data from unauthorized access, alteration, disclosure, and destruction, including:
* **Encryption:** Data is encrypted in transit and at rest.
* **Secure Server Configurations:** Our infrastructure is optimized for enhanced security.
* **Access Controls:** Strict controls ensure that only authorized personnel access sensitive data.
* **Regular Assessments:** Security audits and penetration tests are routinely performed to identify and address vulnerabilities.
## Third-Party Data Processors
To provide a best-in-class experience, Vapi partners with several reputable third-party providers, all of which comply with our GDPR standards. These include:
* **Analytics Tools:**
* *Google Analytics*
* *Cloudflare Analytics*
* *Segment.io*
* *Mixpanel* (with opt-out options)
* *PostHog*
* **CI/CD and Development Platforms:**
* *GitHub*
* **Payment Processors:**
* *Stripe*
Each of these providers is carefully selected and operates under strict data protection agreements to ensure that your data remains secure.
## Transborder Data Transfers
In cases where personal data is transferred outside the European Union (primarily to the United States), we ensure that all transfers are governed by legally approved safeguards such as standard contractual clauses. These measures guarantee that your data receives the same level of protection, regardless of where it is processed.
## Compliance Testing & Continuous Improvement
To reinforce our GDPR compliance, we conduct routine testing and audits including:
* **Penetration Testing:** Confirming there are no critical vulnerabilities.
* **Compliance Audits:** Verifying that our data processing practices adhere to GDPR standards.
* **Role-Based Access Control Tests:** Ensuring that access to personal data is strictly limited to authorized personnel.
* **Data Breach Simulations:** Evaluating the efficiency of our incident response plans.
* **User Consent Management Tests:** Checking the ease and accuracy of obtaining or withdrawing user consent.
* **Data Recovery and Deletion Tests:** Ensuring our backup systems and deletion protocols function as required.
These measures ensure that our data protection systems remain robust, up-to-date, and fully compliant with the ever-evolving data protection landscape.
## Conclusion
Vapi’s dedication to safeguarding your personal data is unwavering. Our comprehensive compliance framework not only meets but exceeds the minimum requirements of the GDPR, ensuring that your privacy and data security are always at the forefront of our operations.
For further details, please contact our Data Protection Officer or review our detailed [GDPR Report](https://security.vapi.ai/).
# HIPAA Compliance
> Learn how to ensure privacy when using Vapi's voice assistant platform.
## Introduction to Privacy at Vapi
At Vapi, we are committed to delivering exceptional voice assistant services while upholding the highest standards of privacy and data protection for our users. We understand the importance of balancing service quality with the need to respect and protect personal and sensitive information. Our privacy policies and practices are designed to give you control over your data while benefiting from the full capabilities of our platform.
## Understanding HIPAA Compliance Basics
The Health Insurance Portability and Accountability Act (HIPAA) is a United States legislation that provides data privacy and security provisions for safeguarding medical information. HIPAA compliance is crucial for any entity that deals with protected health information (PHI), ensuring that sensitive patient data is handled, stored, and transmitted with the highest standards of security and confidentiality. The key concepts of HIPAA compliance include the Privacy Rule, which protects the privacy of individually identifiable health information; the Security Rule, which sets standards for the security of electronic protected health information (e-PHI); and the Breach Notification Rule, which requires covered entities to notify individuals, HHS, and in some cases, the media of a breach of unsecured PHI. Compliance with these rules is not just about adhering to legal requirements but also about building trust with your customers by demonstrating your commitment to protecting their sensitive data. By enabling the `hipaaEnabled` configuration in Vapi's voice assistant platform, you are taking a significant step towards aligning your operations with these HIPAA principles, ensuring that your use of technology adheres to these critical privacy and security standards.
## Understanding Default Settings
By default, Vapi records your calls and stores logs and transcriptions. This practice is aimed at continuously improving the quality of our service, ensuring that you receive the best possible experience. However, we recognize the importance of privacy and provide options for users who prefer more control over their data.
## Opting for Privacy: The HIPAA Compliance Option
For users prioritizing privacy, particularly in compliance with the Health Insurance Portability and Accountability Act (HIPAA), Vapi offers the flexibility to opt out of our default data recording settings. Choosing HIPAA compliance through our platform ensures that you can still use our voice assistant services without compromising on privacy requirements.
## Enabling HIPAA Compliance
HIPAA compliance can be ensured by enabling the `hipaaEnabled` configuration in your assistant settings. This simple yet effective setting guarantees that no call logs, recordings, or transcriptions are stored during or after your calls. An end-of-call report message will be generated and stored on your server for record-keeping, ensuring compliance without storing sensitive data on Vapi's systems.
To enable HIPAA compliance, set hipaaEnabled to true within your assistant's configuration:
```JSON
{
"hipaaEnabled": true
}
```
Note: The default value for hipaaEnabled is false. Activating this setting is a proactive measure to align with HIPAA standards, requiring manual configuration adjustment.
# FAQs
Enabling HIPAA compliance does not degrade the quality of the voice assistant services. However, it limits access to certain features, such as reviewing call logs or transcriptions, that some users may find valuable for quality improvement purposes.
This feature is particularly useful for businesses and organizations in the healthcare sector or any entity that handles sensitive health information and must comply with HIPAA regulations.
Yes, users can toggle the `hipaaEnabled` setting as needed. However, we recommend carefully considering the implications of each option on your data privacy and compliance requirements.
## Where can PHI be used with Vapi?
When using Vapi with PHI, you may only pass PHI through the `/call` endpoint. All other endpoints in the API Reference should not contain PHI. For example, you should not put PHI in an `/assistant` prompt or in a `/phone-number` label. The restriction applies to all configuration endpoints where data would be stored on Vapi's platform.
No, there are no designated "HIPAA-safe endpoints." Instead, when `hipaaEnabled` is turned on, Vapi will only use HIPAA-compliant services (such as Azure OpenAI) for processing PHI through the pipeline. The voice pipeline (STT → LLM → TTS) can process PHI when properly configured, but Vapi does not store this data.
## HIPAA Compliance Configuration
Enable `hipaaEnabled` at the organization level. This ensures that all appropriate compliance measures are in place across your Vapi implementation. You can also toggle HIPAA-compliance at the assistant-level by setting `Assistant.compliancePlan.hipaaEnabled=true` in your configuration.
No. Even when using your own HIPAA-compliant provider keys, it remains your responsibility not to store PHI via Vapi's endpoints. The model keys are a separate concern from the storage of PHI on Vapi's platform. You must both use HIPAA-compliant keys AND ensure you're not storing PHI on Vapi.
## Best Practices
* Enable `hipaaEnabled` at the organization level
* Ensure that PHI only passes through the call pipeline and is not stored in configuration
* Use HIPAA-compliant accounts with all third-party providers (STT, LLM, TTS)
* Be mindful of test/demo assistants where compliance might be turned off for testing purposes - never use these with real PHI
* Remember that with HIPAA compliance enabled, Vapi won't store logs, recordings, or transcriptions
Yes, but be extremely careful. If you have test or demo assistants where HIPAA compliance is turned off for testing purposes, ensure you never intermingle these with real PHI. It's safest to enable HIPAA compliance at the organization level to avoid accidental misconfigurations.
Under the Business Associate Agreement (BAA), you agree:
1. Not to introduce PHI onto Vapi's platform through its API or dashboard except as permitted
2. To use HIPAA-compliant accounts with external providers when providing keys
3. To only use HIPAA-compliant providers that Vapi has signed BAA with when not providing keys. This includes OpenAI, Azure, Google, Anthropic, Deepgram, ElevenLabs, Cartesia, and PlayHT. For updated list, check security.vapi.ai
4. To use the platform in accordance with all BAA requirements
## Need Further Assistance?
If you have more questions about privacy, HIPAA compliance, or how to configure your Vapi assistant, our support team is here to help. Contact us at [security@vapi.ai](mailto:security@vapi.ai) for personalized assistance and more information on how to make the most of Vapi's voice assistant platform while ensuring your data remains protected.
# PCI Compliance
> Ensure secure payment data handling while using Vapi’s voice assistant platform.
## Introduction to Security at Vapi
At Vapi, we prioritize the security of your data without compromising the quality of our voice assistant services. Protecting sensitive information, especially financial data, is at the core of our mission.
Our robust security policies and practices ensure you have complete control over your data while accessing all the capabilities of our platform.
## Understanding PCI Compliance
The Payment Card Industry Data Security Standard (PCI DSS) is a global framework designed to protect credit card information. Any organization processing, storing, or transmitting cardholder data must comply with PCI DSS to ensure that sensitive financial data is securely handled.
Key requirements for PCI compliance include:
* Securing data collection, transmission, and storage.
* Implementing strong access control measures.
* Regularly monitoring and testing systems to prevent breaches.
## PCI Compliance on Vapi’s Platform
By default, Vapi enables call recording, logging, and transcription features to enhance service quality. However, handling sensitive payment card data requires additional precautions.
### How We Ensure Security
When PCI compliance is enabled:
* **Cloud Storage and Webhooks**: You can choose to store recordings in a PCI DSS Level 1 compliant cloud storage solution (AWS S3, Azure Blob Storage, Google Cloud Storage or Cloudflare R2) and receive transcripts through your webhook.
* **No Retention Without Configuration**: If no cloud storage or webhook is specified, recordings and transcripts are permanently deleted to avoid retaining sensitive data.
## How to Enable PCI Compliance
If your organization handles payment data, you can enable PCI compliance by updating your assistant’s configuration.
#### Configuration Steps:
1. Log in to your Vapi account and navigate to your assistant’s settings.
2. Enable the PCI Compliance toggle.
3. Select the PCI-compliant Model, Voice, and Transcriber options for your assistant.
4. \[Optional] Configure cloud storage credentials for storing call recordings. If you have any of the storage endpoint credentials, they will be used to push the recordings.
5. \[Optional] Set up **webhooks** for receiving transcriptions.
If either cloud storage or webhook is not configured, the respective data will not be stored and cannot be retrieved.
Example configuration for `PCI compliant` assistant is:
```JSON
{
"compliancePlan": {
"pciEnabled": true
}
}
```
Note: The default value for `compliancePlan.pciEnabled` is false. Activating this setting aligns your assistant with PCI DSS standards by ensuring data is securely transmitted without being stored on Vapi’s systems.
## Can PCI be used alongside HIPAA?
Yes, you can enable both HIPAA and PCI compliance for an assistant. In this case, the restrictions from both compliances will apply, meaning that no recordings or transcripts will be stored or transmitted, even if you have specified cloud storage endpoints or webhooks for storing transcripts.
## FAQs
**Q: Will enabling PCI compliance affect the quality of Vapi’s service?**
A: Enabling PCI compliance does not degrade the quality of the voice assistant services.
However, it restricts you to use only the PCI-compliant endpoints, while limiting access to certain features, such as reviewing call logs, recordings or transcriptions, within the Vapi platform.
If any cloud storage endpoints are provided, you can review the audio recordings in your own storage environment. The recordings follow the naming convention:
```
---.wav
```
**Q: Who should use the PCI compliance feature?**
A: This feature is particularly useful for businesses and organizations that handle sensitive payment information and must comply with PCI regulations.
**Q: Can I switch between default and PCI-compliant settings?**
A: Yes, users can toggle the `pciEnabled` setting as needed. However, we recommend carefully considering the implications of each option on your data security and compliance requirements.
## Need Further Assistance?
If you have more questions about security, privacy, PCI compliance, or how to configure your Vapi assistant, our support team is here to help. Contact us at [security@vapi.ai](mailto:security@vapi.ai) for personalized assistance and more information on how to make the most of Vapi’s voice assistant platform while ensuring your data remains protected.
# TCPA Consent Guide
> Understanding consent requirements for outbound calls using Vapi's voice agent service.
This guide details the consent requirements under the Telephone Consumer Protection Act (TCPA) for callers using Vapi's voice agent service to make outbound telephone calls.
The TCPA does **not** apply to **inbound** telephone calls.
### Types of Consent Required
The type of consent required depends on whether the call is **marketing** or **non-marketing**:
| **Message Type** | **Consent Required** | **Consent Requirements** | **Sample Consent Disclosure Language** |
| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Marketing** | **Prior Express Written Consent (PEWC)** | 1. **Signed *written* agreement** from the recipient; **AND**
2. **Clear and conspicuous disclosure** that: (A) The consumer agrees to receive calls using artificial or prerecorded voice from the caller at the number(s) provided; **AND** (B) The consumer’s consent is **not** a condition for purchasing goods or services from \[Company]. | By \[signing below/checking this box/clicking "I Accept"], I consent to receive **marketing** calls from and on behalf of \[Company] and its affiliates, including calls made using an artificial or prerecorded voice, an automated telephone dialing system, or automated texting system. Calls and texts may be generated from computers or from persons. \[Company]. |
| **Non-Marketing** | **Prior Express Consent (PEC)** | The TCPA does not define PEC. However, the FCC has stated that non-marketing calls can form PEC for any phone number that is related to the transaction between the caller and consumer.
Therefore, an express and obvious consent is sufficient. | By \[signing below/checking this box/clicking "I Accept"], I consent to receive **non-marketing** calls from and on behalf of \[Company] and its affiliates, including calls made using an artificial or prerecorded voice or an automated telephone dialing system (note that I have provided the phone number(s) that I would like to receive these calls). |
\*The signature may comply with the E-SIGN Act (*e.g.*, email, website form, telephone keypress, text message, voice recording).
### Understanding "Marketing"
**"Marketing"** is interpreted broadly to include calls that:
* Encourage the purchase or rental of (or investment in) property, goods, or services
* Advertise the commercial availability or quality of any property, goods, or services
### Important Consent Guidelines
When providing consent, a consumer **must affirmatively opt in**. A pre-checked box next to consent disclosure language does **not** qualify as providing consent.
**A consumer may revoke consent at any time through any reasonable means** (*e.g.*, using a telephone keypress, speaking with a representative, selecting preferences via an online portal), so callers should provide a clear procedure for consumers to opt-out and honor their opt-out requests.
**Remaining Questions?** This consent guide does not constitute legal advice and does not cover other telemarketing laws that may apply (*e.g.*, federal Do-Not-Call (DNC) rules, state law). If you have further questions, please speak with an attorney who specializes in telemarketing compliance.
# List Calls
```http
GET https://api.vapi.ai/call
```
## Query Parameters
- id (optional): This is the unique identifier for the call.
- assistantId (optional): This will return calls with the specified assistantId.
- phoneNumberId (optional): This is the phone number that will be used for the call. To use a transient number, use `phoneNumber` instead.
Only relevant for `outboundPhoneCall` and `inboundPhoneCall` type.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/call \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.calls.list()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.calls.list();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Calls.List(
context.TODO(),
&serversdkgo.CallsListRequest{},
)
```
# Create Call
```http
POST https://api.vapi.ai/call
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/call \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.calls.create()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.calls.create();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Calls.Create(
context.TODO(),
&serversdkgo.CreateCallDto{},
)
```
# Get Call
```http
GET https://api.vapi.ai/call/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/call/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.calls.get(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.calls.get("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Calls.Get(
context.TODO(),
"id",
)
```
# Delete Call Data
```http
DELETE https://api.vapi.ai/call/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/call/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.calls.delete(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.calls.delete("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Calls.Delete(
context.TODO(),
"id",
)
```
# Update Call
```http
PATCH https://api.vapi.ai/call/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/call/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.calls.update(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.calls.update("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Calls.Update(
context.TODO(),
"id",
&serversdkgo.UpdateCallDto{},
)
```
# List Chats
```http
GET https://api.vapi.ai/chat
```
## Query Parameters
- assistantId (optional): This is the unique identifier for the assistant that will be used for the chat.
- workflowId (optional): This is the unique identifier for the workflow that will be used for the chat.
- sessionId (optional): This is the unique identifier for the session that will be used for the chat.
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/chat \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.chats.list()
```
# Create Chat
```http
POST https://api.vapi.ai/chat
Content-Type: application/json
```
Creates a new chat. Requires at least one of: assistantId/assistant, sessionId, or previousChatId. Note: sessionId and previousChatId are mutually exclusive.
## Response Body
- 200: Chat response - either non-streaming chat or streaming
## Examples
```shell
curl -X POST https://api.vapi.ai/chat \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"input": "Hello, how can you help me?"
}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.chats.create(
input="input",
)
```
# Get Chat
```http
GET https://api.vapi.ai/chat/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/chat/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.chats.get(
id="id",
)
```
# Delete Chat
```http
DELETE https://api.vapi.ai/chat/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/chat/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.chats.delete(
id="id",
)
```
# Create Chat (OpenAI Compatible)
```http
POST https://api.vapi.ai/chat/responses
Content-Type: application/json
```
## Response Body
- 200: OpenAI Responses API format - either non-streaming or streaming
## Examples
```shell
curl -X POST https://api.vapi.ai/chat/responses \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"input": "Hello, how can you help me?"
}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.chats.create_response(
input="input",
)
```
# List Campaigns
```http
GET https://api.vapi.ai/campaign
```
## Query Parameters
- id (optional)
- status (optional)
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/campaign \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.campaigns.campaign_controller_find_all()
```
# Create Campaign
```http
POST https://api.vapi.ai/campaign
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/campaign \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"name": "Q2 Sales Campaign",
"phoneNumberId": "foo",
"customers": [
{}
]
}'
```
```python
from vapi import CreateCustomerDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.campaigns.campaign_controller_create(
name="Q2 Sales Campaign",
phone_number_id="phoneNumberId",
customers=[CreateCustomerDto()],
)
```
# Get Campaign
```http
GET https://api.vapi.ai/campaign/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/campaign/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.campaigns.campaign_controller_find_one(
id="id",
)
```
# Delete Campaign
```http
DELETE https://api.vapi.ai/campaign/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/campaign/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.campaigns.campaign_controller_remove(
id="id",
)
```
# Update Campaign
```http
PATCH https://api.vapi.ai/campaign/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/campaign/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.campaigns.campaign_controller_update(
id="id",
)
```
# List Sessions
```http
GET https://api.vapi.ai/session
```
## Query Parameters
- name (optional): This is the name of the session to filter by.
- assistantId (optional): This is the ID of the assistant to filter sessions by.
- workflowId (optional): This is the ID of the workflow to filter sessions by.
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/session \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.sessions.list()
```
# Create Session
```http
POST https://api.vapi.ai/session
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/session \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.sessions.create()
```
# Get Session
```http
GET https://api.vapi.ai/session/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/session/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.sessions.get(
id="id",
)
```
# Delete Session
```http
DELETE https://api.vapi.ai/session/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/session/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.sessions.delete(
id="id",
)
```
# Update Session
```http
PATCH https://api.vapi.ai/session/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/session/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.sessions.update(
id="id",
)
```
# List Assistants
```http
GET https://api.vapi.ai/assistant
```
## Query Parameters
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/assistant \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.assistants.list()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.assistants.list();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Assistants.List(
context.TODO(),
&serversdkgo.AssistantsListRequest{},
)
```
# Create Assistant
```http
POST https://api.vapi.ai/assistant
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/assistant \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.assistants.create()
```
```typescript
import { VapiClient, Vapi } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.assistants.create({});
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Assistants.Create(
context.TODO(),
&serversdkgo.CreateAssistantDto{},
)
```
# Get Assistant
```http
GET https://api.vapi.ai/assistant/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/assistant/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.assistants.get(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.assistants.get("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Assistants.Get(
context.TODO(),
"id",
)
```
# Delete Assistant
```http
DELETE https://api.vapi.ai/assistant/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/assistant/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.assistants.delete(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.assistants.delete("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Assistants.Delete(
context.TODO(),
"id",
)
```
# Update Assistant
```http
PATCH https://api.vapi.ai/assistant/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/assistant/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.assistants.update(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.assistants.update("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Assistants.Update(
context.TODO(),
"id",
&serversdkgo.UpdateAssistantDto{},
)
```
# List Phone Numbers
```http
GET https://api.vapi.ai/phone-number
```
## Query Parameters
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/phone-number \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.phone_numbers.list()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.phoneNumbers.list();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.PhoneNumbers.List(
context.TODO(),
&serversdkgo.PhoneNumbersListRequest{},
)
```
# Create Phone Number
```http
POST https://api.vapi.ai/phone-number
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/phone-number \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"provider": "byo-phone-number",
"credentialId": "foo"
}'
```
```python
from vapi import CreateByoPhoneNumberDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.phone_numbers.create(
request=CreateByoPhoneNumberDto(
credential_id="credentialId",
),
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.phoneNumbers.create({
provider: "byo-phone-number",
credentialId: "credentialId"
});
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.PhoneNumbers.Create(
context.TODO(),
&serversdkgo.PhoneNumbersCreateRequest{
CreateByoPhoneNumberDto: &serversdkgo.CreateByoPhoneNumberDto{
CredentialId: "credentialId",
},
},
)
```
# Get Phone Number
```http
GET https://api.vapi.ai/phone-number/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/phone-number/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.phone_numbers.get(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.phoneNumbers.get("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.PhoneNumbers.Get(
context.TODO(),
"id",
)
```
# Delete Phone Number
```http
DELETE https://api.vapi.ai/phone-number/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/phone-number/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.phone_numbers.delete(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.phoneNumbers.delete("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.PhoneNumbers.Delete(
context.TODO(),
"id",
)
```
# Update Phone Number
```http
PATCH https://api.vapi.ai/phone-number/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/phone-number/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import UpdateByoPhoneNumberDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.phone_numbers.update(
id="id",
request=UpdateByoPhoneNumberDto(),
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.phoneNumbers.update("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.PhoneNumbers.Update(
context.TODO(),
"id",
&serversdkgo.PhoneNumbersUpdateRequest{
UpdateByoPhoneNumberDto: &serversdkgo.UpdateByoPhoneNumberDto{},
},
)
```
# List Tools
```http
GET https://api.vapi.ai/tool
```
## Query Parameters
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/tool \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.tools.list()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.tools.list();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Tools.List(
context.TODO(),
&serversdkgo.ToolsListRequest{},
)
```
# Create Tool
```http
POST https://api.vapi.ai/tool
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/tool \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"type": "apiRequest",
"method": "POST",
"url": "foo"
}'
```
```python
from vapi import CreateApiRequestToolDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.tools.create(
request=CreateApiRequestToolDto(
method="POST",
url="url",
),
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.tools.create({
type: "dtmf"
});
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Tools.Create(
context.TODO(),
&serversdkgo.ToolsCreateRequest{
CreateDtmfToolDto: &serversdkgo.CreateDtmfToolDto{},
},
)
```
# Get Tool
```http
GET https://api.vapi.ai/tool/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/tool/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.tools.get(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.tools.get("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Tools.Get(
context.TODO(),
"id",
)
```
# Delete Tool
```http
DELETE https://api.vapi.ai/tool/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/tool/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.tools.delete(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.tools.delete("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Tools.Delete(
context.TODO(),
"id",
)
```
# Update Tool
```http
PATCH https://api.vapi.ai/tool/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/tool/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import UpdateApiRequestToolDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.tools.update(
id="id",
request=UpdateApiRequestToolDto(),
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.tools.update("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Tools.Update(
context.TODO(),
"id",
&serversdkgo.ToolsUpdateRequest{
UpdateDtmfToolDto: &serversdkgo.UpdateDtmfToolDto{},
},
)
```
# List Files
```http
GET https://api.vapi.ai/file
```
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/file \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.files.list()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.files.list();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Files.List(
context.TODO(),
)
```
# Upload File
```http
POST https://api.vapi.ai/file
Content-Type: multipart/form-data
```
## Response Body
- 201: File uploaded successfully
- 400: Invalid file
## Examples
```shell
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer " \
-H "Content-Type: multipart/form-data" \
-F file=@foo
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.files.create()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
import * as fs from "fs";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.files.create(fs.createReadStream("/path/to/your/file"));
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Files.Create(
context.TODO(),
)
```
```shell
curl -X POST https://api.vapi.ai/file \
-H "Authorization: Bearer " \
-H "Content-Type: multipart/form-data" \
-F file=@
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.files.create()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
import * as fs from "fs";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.files.create(fs.createReadStream("/path/to/your/file"));
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Files.Create(
context.TODO(),
)
```
# Get File
```http
GET https://api.vapi.ai/file/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/file/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.files.get(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.files.get("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Files.Get(
context.TODO(),
"id",
)
```
# Delete File
```http
DELETE https://api.vapi.ai/file/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/file/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.files.delete(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.files.delete("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Files.Delete(
context.TODO(),
"id",
)
```
# Update File
```http
PATCH https://api.vapi.ai/file/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/file/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.files.update(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.files.update("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Files.Update(
context.TODO(),
"id",
&serversdkgo.UpdateFileDto{},
)
```
# List Knowledge Bases
```http
GET https://api.vapi.ai/knowledge-base
```
## Query Parameters
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/knowledge-base \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.knowledge_bases.list()
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.KnowledgeBases.List(
context.TODO(),
&serversdkgo.KnowledgeBasesListRequest{},
)
```
# Create Knowledge Base
```http
POST https://api.vapi.ai/knowledge-base
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/knowledge-base \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"provider": "trieve"
}'
```
```python
from vapi import CreateTrieveKnowledgeBaseDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.knowledge_bases.create(
request=CreateTrieveKnowledgeBaseDto(),
)
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.KnowledgeBases.Create(
context.TODO(),
&serversdkgo.KnowledgeBasesCreateRequest{
CreateTrieveKnowledgeBaseDto: &serversdkgo.CreateTrieveKnowledgeBaseDto{
VectorStoreSearchPlan: &serversdkgo.TrieveKnowledgeBaseVectorStoreSearchPlan{
SearchType: serversdkgo.TrieveKnowledgeBaseVectorStoreSearchPlanSearchTypeFulltext,
},
},
},
)
```
# Get Knowledge Base
```http
GET https://api.vapi.ai/knowledge-base/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/knowledge-base/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.knowledge_bases.get(
id="id",
)
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.KnowledgeBases.Get(
context.TODO(),
"id",
)
```
# Delete Knowledge Base
```http
DELETE https://api.vapi.ai/knowledge-base/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/knowledge-base/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.knowledge_bases.delete(
id="id",
)
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.KnowledgeBases.Delete(
context.TODO(),
"id",
)
```
# Update Knowledge Base
```http
PATCH https://api.vapi.ai/knowledge-base/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/knowledge-base/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import UpdateTrieveKnowledgeBaseDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.knowledge_bases.update(
id="id",
request=UpdateTrieveKnowledgeBaseDto(),
)
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.KnowledgeBases.Update(
context.TODO(),
"id",
&serversdkgo.KnowledgeBasesUpdateRequest{
UpdateTrieveKnowledgeBaseDto: &serversdkgo.UpdateTrieveKnowledgeBaseDto{},
},
)
```
# Get Workflows
```http
GET https://api.vapi.ai/workflow
```
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/workflow \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.workflow.workflow_controller_find_all()
```
# Create Workflow
```http
POST https://api.vapi.ai/workflow
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/workflow \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"nodes": [
{
"type": "conversation",
"name": "foo"
}
],
"name": "foo",
"edges": [
{
"from": "foo",
"to": "foo"
}
]
}'
```
```python
from vapi import ConversationNode, Edge, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.workflow.workflow_controller_create(
nodes=[
ConversationNode(
name="name",
)
],
name="name",
edges=[
Edge(
from_="from",
to="to",
)
],
)
```
# Get Workflow
```http
GET https://api.vapi.ai/workflow/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/workflow/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.workflow.workflow_controller_find_one(
id="id",
)
```
# Delete Workflow
```http
DELETE https://api.vapi.ai/workflow/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/workflow/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.workflow.workflow_controller_delete(
id="id",
)
```
# Update Workflow
```http
PATCH https://api.vapi.ai/workflow/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/workflow/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.workflow.workflow_controller_update(
id="id",
)
```
# List Squads
```http
GET https://api.vapi.ai/squad
```
## Query Parameters
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/squad \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.squads.list()
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.squads.list();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Squads.List(
context.TODO(),
&serversdkgo.SquadsListRequest{},
)
```
# Create Squad
```http
POST https://api.vapi.ai/squad
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/squad \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"members": [
{}
]
}'
```
```python
from vapi import SquadMemberDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.squads.create(
members=[SquadMemberDto()],
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.squads.create({
members: [{}]
});
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Squads.Create(
context.TODO(),
&serversdkgo.CreateSquadDto{
Members: []*serversdkgo.SquadMemberDto{
&serversdkgo.SquadMemberDto{},
},
},
)
```
# Get Squad
```http
GET https://api.vapi.ai/squad/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/squad/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.squads.get(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.squads.get("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Squads.Get(
context.TODO(),
"id",
)
```
# Delete Squad
```http
DELETE https://api.vapi.ai/squad/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/squad/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.squads.delete(
id="id",
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.squads.delete("id");
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Squads.Delete(
context.TODO(),
"id",
)
```
# Update Squad
```http
PATCH https://api.vapi.ai/squad/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/squad/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"members": [
{}
]
}'
```
```python
from vapi import SquadMemberDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.squads.update(
id="id",
members=[SquadMemberDto()],
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.squads.update("id", {
members: [{}]
});
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Squads.Update(
context.TODO(),
"id",
&serversdkgo.UpdateSquadDto{
Members: []*serversdkgo.SquadMemberDto{
&serversdkgo.SquadMemberDto{},
},
},
)
```
# List Test Suites
```http
GET https://api.vapi.ai/test-suite
```
## Query Parameters
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/test-suite \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suites.test_suite_controller_find_all_paginated()
```
# Create Test Suite
```http
POST https://api.vapi.ai/test-suite
Content-Type: application/json
```
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/test-suite \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suites.test_suite_controller_create()
```
# Get Test Suite
```http
GET https://api.vapi.ai/test-suite/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/test-suite/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suites.test_suite_controller_find_one(
id="id",
)
```
# Delete Test Suite
```http
DELETE https://api.vapi.ai/test-suite/{id}
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/test-suite/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suites.test_suite_controller_remove(
id="id",
)
```
# Update Test Suite
```http
PATCH https://api.vapi.ai/test-suite/{id}
Content-Type: application/json
```
## Path Parameters
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/test-suite/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suites.test_suite_controller_update(
id="id",
)
```
# List Tests
```http
GET https://api.vapi.ai/test-suite/{testSuiteId}/test
```
## Path Parameters
- testSuiteId (required)
## Query Parameters
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/test-suite/testSuiteId/test \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_tests.test_suite_test_controller_find_all_paginated(
test_suite_id="testSuiteId",
)
```
# Create Test
```http
POST https://api.vapi.ai/test-suite/{testSuiteId}/test
Content-Type: application/json
```
## Path Parameters
- testSuiteId (required)
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/test-suite/testSuiteId/test \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"scorers": [
{
"type": "ai",
"rubric": "foo"
}
],
"type": "voice",
"script": "foo"
}'
```
```python
from vapi import CreateTestSuiteTestVoiceDto, TestSuiteTestScorerAi, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_tests.test_suite_test_controller_create(
test_suite_id="testSuiteId",
request=CreateTestSuiteTestVoiceDto(
scorers=[
TestSuiteTestScorerAi(
rubric="rubric",
)
],
script="script",
),
)
```
# Get Test
```http
GET https://api.vapi.ai/test-suite/{testSuiteId}/test/{id}
```
## Path Parameters
- testSuiteId (required)
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/test-suite/testSuiteId/test/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_tests.test_suite_test_controller_find_one(
test_suite_id="testSuiteId",
id="id",
)
```
# Delete Test
```http
DELETE https://api.vapi.ai/test-suite/{testSuiteId}/test/{id}
```
## Path Parameters
- testSuiteId (required)
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/test-suite/testSuiteId/test/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_tests.test_suite_test_controller_remove(
test_suite_id="testSuiteId",
id="id",
)
```
# Update Test
```http
PATCH https://api.vapi.ai/test-suite/{testSuiteId}/test/{id}
Content-Type: application/json
```
## Path Parameters
- testSuiteId (required)
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/test-suite/testSuiteId/test/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import UpdateTestSuiteTestVoiceDto, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_tests.test_suite_test_controller_update(
test_suite_id="testSuiteId",
id="id",
request=UpdateTestSuiteTestVoiceDto(),
)
```
# List Test Suite Runs
```http
GET https://api.vapi.ai/test-suite/{testSuiteId}/run
```
## Path Parameters
- testSuiteId (required)
## Query Parameters
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/test-suite/testSuiteId/run \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_runs.test_suite_run_controller_find_all_paginated(
test_suite_id="testSuiteId",
)
```
# Create Test Suite Run
```http
POST https://api.vapi.ai/test-suite/{testSuiteId}/run
Content-Type: application/json
```
## Path Parameters
- testSuiteId (required)
## Response Body
- 201:
## Examples
```shell
curl -X POST https://api.vapi.ai/test-suite/testSuiteId/run \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_runs.test_suite_run_controller_create(
test_suite_id="testSuiteId",
)
```
# Get Test Suite Run
```http
GET https://api.vapi.ai/test-suite/{testSuiteId}/run/{id}
```
## Path Parameters
- testSuiteId (required)
- id (required)
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/test-suite/testSuiteId/run/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_runs.test_suite_run_controller_find_one(
test_suite_id="testSuiteId",
id="id",
)
```
# Delete Test Suite Run
```http
DELETE https://api.vapi.ai/test-suite/{testSuiteId}/run/{id}
```
## Path Parameters
- testSuiteId (required)
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X DELETE https://api.vapi.ai/test-suite/testSuiteId/run/id \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_runs.test_suite_run_controller_remove(
test_suite_id="testSuiteId",
id="id",
)
```
# Update Test Suite Run
```http
PATCH https://api.vapi.ai/test-suite/{testSuiteId}/run/{id}
Content-Type: application/json
```
## Path Parameters
- testSuiteId (required)
- id (required)
## Response Body
- 200:
## Examples
```shell
curl -X PATCH https://api.vapi.ai/test-suite/testSuiteId/run/id \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{}'
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.test_suite_runs.test_suite_run_controller_update(
test_suite_id="testSuiteId",
id="id",
)
```
# Create Analytics Queries
```http
POST https://api.vapi.ai/analytics
Content-Type: application/json
```
## Response Body
- 200:
## Examples
```shell
curl -X POST https://api.vapi.ai/analytics \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"queries": [
{
"table": "call",
"name": "foo",
"operations": [
{
"operation": "sum",
"column": "id"
}
]
}
]
}'
```
```python
from vapi import AnalyticsOperation, AnalyticsQuery, Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.analytics.get(
queries=[
AnalyticsQuery(
table="call",
name="name",
operations=[
AnalyticsOperation(
operation="sum",
column="id",
)
],
)
],
)
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.analytics.get({
queries: [{
table: "call",
name: "name",
operations: [{
operation: "sum",
column: "id"
}]
}]
});
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
err := client.Analytics.Get(
context.TODO(),
)
```
# Get Logs
```http
GET https://api.vapi.ai/logs
```
## Query Parameters
- type (optional): This is the type of the log.
- webhookType (optional): This is the type of the webhook, given the log is from a webhook.
- assistantId (optional): This is the ID of the assistant.
- phoneNumberId (optional): This is the ID of the phone number.
- customerId (optional): This is the ID of the customer.
- squadId (optional): This is the ID of the squad.
- callId (optional): This is the ID of the call.
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200:
## Examples
```shell
curl https://api.vapi.ai/logs \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
response = client.logs.get()
for item in response:
yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
yield page
```
```typescript
import { VapiClient } from "@vapi/server-sdk";
const client = new VapiClient({ token: "YOUR_TOKEN" });
await client.logs.get();
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
response, err := client.Logs.Get(
context.TODO(),
&serversdkgo.LogsGetRequest{},
)
```
# Delete Logs
```http
DELETE https://api.vapi.ai/logs
```
## Query Parameters
- type (optional): This is the type of the log.
- assistantId (optional)
- phoneNumberId (optional): This is the ID of the phone number.
- customerId (optional): This is the ID of the customer.
- squadId (optional): This is the ID of the squad.
- callId (optional): This is the ID of the call.
## Examples
```shell
curl -X DELETE https://api.vapi.ai/logs \
-H "Authorization: Bearer "
```
```python
from vapi import Vapi
client = Vapi(
token="YOUR_TOKEN",
)
client.logs.logging_controller_logs_delete_query()
```
```go
import (
context "context"
option "github.com/VapiAI/server-sdk-go/option"
serversdkgo "github.com/VapiAI/server-sdk-go"
serversdkgoclient "github.com/VapiAI/server-sdk-go/client"
)
client := serversdkgoclient.NewClient(
option.WithToken(
"",
),
)
err := client.Logs.LoggingControllerLogsDeleteQuery(
context.TODO(),
&serversdkgo.LoggingControllerLogsDeleteQueryRequest{},
)
```
# Get paginated list of provider resources
```http
GET https://api.vapi.ai/provider/{provider}/{resourceName}
```
## Path Parameters
- provider (required): The provider (e.g., 11labs)
- resourceName (required): The resource name (e.g., pronunciation-dictionary)
## Query Parameters
- id (optional)
- resourceId (optional)
- page (optional): This is the page number to return. Defaults to 1.
- sortOrder (optional): This is the sort order for pagination. Defaults to 'DESC'.
- limit (optional): This is the maximum number of items to return. Defaults to 100.
- createdAtGt (optional): This will return items where the createdAt is greater than the specified value.
- createdAtLt (optional): This will return items where the createdAt is less than the specified value.
- createdAtGe (optional): This will return items where the createdAt is greater than or equal to the specified value.
- createdAtLe (optional): This will return items where the createdAt is less than or equal to the specified value.
- updatedAtGt (optional): This will return items where the updatedAt is greater than the specified value.
- updatedAtLt (optional): This will return items where the updatedAt is less than the specified value.
- updatedAtGe (optional): This will return items where the updatedAt is greater than or equal to the specified value.
- updatedAtLe (optional): This will return items where the updatedAt is less than or equal to the specified value.
## Response Body
- 200: List of provider resources
## Examples
```shell
curl https://api.vapi.ai/provider/11labs/pronunciation-dictionary \
-H "Authorization: Bearer "
```
# Create provider resource
```http
POST https://api.vapi.ai/provider/{provider}/{resourceName}
```
## Path Parameters
- provider (required): The provider (e.g., 11labs)
- resourceName (required): The resource name (e.g., pronunciation-dictionary)
## Response Body
- 201: Successfully created provider resource
## Examples
```shell
curl -X POST https://api.vapi.ai/provider/11labs/pronunciation-dictionary \
-H "Authorization: Bearer "
```
# Get provider resource by ID
```http
GET https://api.vapi.ai/provider/{provider}/{resourceName}/{id}
```
## Path Parameters
- provider (required): The provider (e.g., 11labs)
- resourceName (required): The resource name (e.g., pronunciation-dictionary)
- id (required)
## Response Body
- 200: Successfully retrieved provider resource
- 404: Provider resource not found
## Examples
```shell
curl https://api.vapi.ai/provider/11labs/pronunciation-dictionary/id \
-H "Authorization: Bearer "
```
```shell
curl https://api.vapi.ai/provider/11labs/pronunciation-dictionary/:id \
-H "Authorization: Bearer "
```
# Delete provider resource by ID
```http
DELETE https://api.vapi.ai/provider/{provider}/{resourceName}/{id}
```
## Path Parameters
- provider (required): The provider (e.g., 11labs)
- resourceName (required): The resource name (e.g., pronunciation-dictionary)
- id (required)
## Response Body
- 200:
- 404: Provider resource not found
## Examples
```shell
curl -X DELETE https://api.vapi.ai/provider/11labs/pronunciation-dictionary/id \
-H "Authorization: Bearer "
```
```shell
curl -X DELETE https://api.vapi.ai/provider/11labs/pronunciation-dictionary/:id \
-H "Authorization: Bearer "
```
# Update provider resource by ID
```http
PATCH https://api.vapi.ai/provider/{provider}/{resourceName}/{id}
```
## Path Parameters
- provider (required): The provider (e.g., 11labs)
- resourceName (required): The resource name (e.g., pronunciation-dictionary)
- id (required)
## Response Body
- 200:
- 404: Provider resource not found
## Examples
```shell
curl -X PATCH https://api.vapi.ai/provider/11labs/pronunciation-dictionary/id \
-H "Authorization: Bearer "
```
```shell
curl -X PATCH https://api.vapi.ai/provider/11labs/pronunciation-dictionary/:id \
-H "Authorization: Bearer "
```
# Server Message
```http
POST https://{yourserver}.com/server
Content-Type: application/json
```
## Response Body
- 200: This is the response that is expected from the server to the message.
Note: Most messages don't expect a response. Only "assistant-request", "tool-calls" and "transfer-destination-request" do.
## Examples
```shell
curl -X POST https://{yourserver}.com/server \
-H "Content-Type: application/json" \
-d '{
"message": {
"type": "assistant-request"
}
}'
```
# Client Message
```http
POST https://{yourserver}.com/client
Content-Type: application/json
```
These are all the webhook messages that will be sent to the client-side SDKs during the call.
Configure the messages you'd like to receive in `assistant.clientMessages`.
## Response Body
- 200: These are the messages that can be sent from client-side SDKs to control the call.
## Examples
```shell
curl -X POST https://{yourserver}.com/client \
-H "Content-Type: application/json" \
-d '{
"message": {
"type": "workflow.node.started",
"node": {}
}
}'
```
# Model Context Protocol (MCP) Integration
> Connect your assistant to dynamic tools through MCP servers for enhanced capabilities.
The Model Context Protocol (MCP) integration allows your Vapi assistant to dynamically access tools from MCP servers during calls. This enables your assistant to:
1. Connect to any MCP-compatible server
2. Access tools dynamically at runtime
3. Execute actions through the MCP server
This powerful integration allows your assistant to leverage a wide range of tools without requiring individual integrations for each service.
Vapi also provides its own MCP server that exposes Vapi APIs as callable tools. See the [Vapi MCP Server documentation](/sdk/mcp-server) to learn how to use it with Claude Desktop or custom applications.
## Prerequisites
Before you can use the MCP integration, you need to:
1. Have access to the Vapi Dashboard
2. Have an assistant created in Vapi
3. Have access to an MCP server URL (e.g., from Zapier, Composio, or other MCP providers)
## Setup Steps
### 1. Obtain MCP Server URL
First, you need to obtain an MCP server URL from your chosen provider:
1. Sign up for an MCP-compatible service (e.g., Zapier, Composio)
2. Navigate to the MCP configuration section of your provider
3. Generate or copy your MCP server URL
For Zapier MCP, visit [https://mcp.zapier.com/mcp/?client=vapi](https://mcp.zapier.com/mcp/?client=vapi)? to generate your MCP server URL. This URL should be treated as a credential and kept secure.
### 2. Create and Configure MCP Tool
After obtaining your MCP server URL, create and configure the tool:
1. Go to **Dashboard** > **Tools** page
2. Click the **Create Tool** button
3. Select **MCP** from the available options
4. Provide a name and description explaining when it should be invoked
5. Configure the tool with the following required field:
* `serverUrl`: The URL of your MCP server
The MCP server URL should be treated as a credential and kept secure. It will be used to authenticate requests to the MCP server.
### 3. Add Tool to Assistant
Now, add the MCP tool to your assistant:
1. Navigate to **Dashboard** > **Assistants** page
2. Select your assistant
3. Go to the **Tools** tab
4. In the tools dropdown, select your MCP tool
5. Click **Publish** to save your changes
## How MCP Works
The MCP integration follows these steps during a call:
1. When a call starts, Vapi connects to your configured MCP server using **Streamable HTTP** protocol by default
2. The MCP server returns a list of available tools and their capabilities
3. These tools are dynamically added to your assistant's available tools
4. The assistant can then use these tools during the call
5. When a tool is invoked, Vapi sends the request to the MCP server
6. The MCP server executes the action and returns the result
The MCP tool itself is not meant to be invoked by the model. It serves as a configuration mechanism for Vapi to fetch and inject the specific tool definitions from the MCP server into the model's context.
The tools available through MCP are determined by your MCP server provider. Different providers may offer different sets of tools.
### Request Headers
MCP requests from Vapi include identifying headers to help with context and debugging:
* **`X-Call-Id`**: Included in requests during voice calls to identify the specific call
* **`X-Chat-Id`**: Included in requests during chat interactions to identify the specific chat
* **`X-Session-Id`**: Included in requests during chat interaction if the chat is part of a session
## Tool Configuration
### MCP Tool
This tool uses the following configuration options:
**Required:**
* `server.url`: The URL of your MCP server (e.g., [https://mcp.zapier.com/api/mcp/s/\*\*\*\*\*\*\*\*/mcp](https://mcp.zapier.com/api/mcp/s/********/mcp))
**Optional:**
* `server.headers`: Custom headers to include in requests to the MCP server
* `metadata`: Additional configuration options for the MCP connection
* `protocol`: Communication protocol to use. Options are:
* `"shttp"` (default): Uses Streamable HTTP protocol
* `"sse"`: (deprecated) Uses Server-Sent Events protocol
The server URL should be treated as a credential and kept secure. It will be used to authenticate requests to the MCP server.
## Example Usage
Here's how the MCP tool can be used in your assistant's configuration:
### Default Configuration (Streamable HTTP)
```json
{
"model": {
"provider": "openai",
"model": "gpt-4o",
"messages": [
{
"role": "system",
"content": "You are a helpful personal assistant named Alex. You can help users with various tasks through voice commands. You have access to tools that allow you to perform actions on the user's behalf.\n\nWhen a user requests an action, check if any of the available tools can help accomplish that task.\n\nCommon tasks you can help with include:\n- Scheduling appointments and meetings\n- Sending messages or emails\n- Creating or updating documents\n- Managing to-do lists and reminders\n- Searching for information\n- Making reservations\n- Ordering food or services\n- Checking account balances or transaction history\n- Controlling smart home devices\n\nAlways be polite, professional, and helpful. If a tool fails or isn't available, explain the situation to the user and suggest alternatives if possible."
}
],
"tools": [
{
"type": "mcp",
"function": {
"name": "mcpTools"
},
"server": {
"url": "https://mcp.zapier.com/api/mcp/s/********/mcp"
}
}
]
}
}
```
### Custom Configuration (SSE Protocol)
If you need to use Server-Sent Events protocol instead:
```json
{
"model": {
"provider": "openai",
"model": "gpt-4",
"messages": [
{
"role": "system",
"content": "You are a helpful personal assistant named Alex..."
}
],
"tools": [
{
"type": "mcp",
"function": {
"name": "mcpTools"
},
"server": {
"url": "https://mcp.zapier.com/api/mcp/s/********/mcp",
"headers": {
"Authorization": "Bearer your-token",
"X-Custom-Header": "your-value"
}
},
"metadata": {
"protocol": "sse"
}
}
]
}
}
```
## Best Practices
1. **Protocol Selection**: Use the default Streamable HTTP protocol for better performance unless you specifically need SSE
2. **Dynamic Tool Awareness**: Be aware that the available tools may change between calls
3. **Clear Instructions**: Provide clear instructions in your assistant's system message about how to handle dynamic tools
4. **Error Handling**: Include fallback responses for cases where tools fail or are unavailable
5. **User Communication**: Explain to users what tools you're using and what actions you're taking
6. **Security**: Treat the MCP server URL as a credential and keep it secure
## Example MCP Providers
### Zapier MCP
Zapier offers an MCP server that provides access to thousands of app integrations:
1. Go to [https://mcp.zapier.com/mcp/?client=vapi](https://mcp.zapier.com/mcp/?client=vapi)?
2. Generate your MCP server URL
3. Add the URL to your MCP tool configuration
4. Your assistant will now have access to Zapier's extensive integration network
Zapier MCP provides access to over 7,000+ apps and 30,000+ actions without requiring complex API integrations.
### Composio MCP
Composio also offers an MCP server for integration:
1. Log in to the Composio dashboard at [https://mcp.composio.dev/dashboard](https://mcp.composio.dev/dashboard)
2. Select the tool you want to integrate (e.g., Gmail)
3. Enable the MCP server for the selected tool by connecting your account using authentication flow
4. Create a server and copy the generated URL
5. Add this URL to your MCP tool configuration as the `serverUrl`
6. Your assistant will now have access to the specific Composio tool integration
**Context Overflow Warning**: Some MCP server tool calls (eg: GitHub API queries) may return large amounts of data. This can exceed model context limits, affecting assistant performance and potentially causing failures, especially with models like GPT-4o.
**Best Practices**:
* Configure your MCP tools to return focused, relevant data
* Use filtering parameters when available to limit response size
* Test your integration with realistic queries before deploying
* Monitor token usage and context size during development
## References
* [Model Context Protocol Introduction](https://modelcontextprotocol.io/introduction)
* [Zapier MCP](https://zapier.com/mcp)
Join our Discord community for support with MCP integration
View the complete API documentation for tools
# Vapi MCP Server
> Connect Vapi to AI assistants with Model Context Protocol (MCP)
## Overview
The **Vapi MCP Server** exposes Vapi APIs as tools via the Model Context Protocol (MCP), so you can manage assistants, phone numbers, and calls from any MCP-compatible AI assistant (like Claude Desktop) or agent framework.
Use this server to connect your AI workflows to real-world telephony, automate voice tasks, and build richer conversational agents.
Looking to use MCP tools *inside* a Vapi assistant? See the [MCP Tool documentation](/tools/mcp) for integrating *external* MCP servers with your Vapi agents.
**Using the Vapi CLI?** Auto-configure MCP in your IDE with one command:
```bash
vapi mcp setup
```
This automatically configures Cursor, Windsurf, or VSCode with the Vapi MCP server. [Learn more →](/cli/mcp)
## Quickstart: Claude Desktop Config
**Fastest way to get started:** connect Claude Desktop to the Vapi MCP Server.
[Get your API key from the Vapi dashboard.](https://dashboard.vapi.ai/org/api-keys)
Open Settings → Developer tab → Edit Config.
Insert this into your claude\_desktop\_config.json:
```json
{
"mcpServers": {
"vapi-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.vapi.ai/mcp",
"--header",
"Authorization: Bearer ${VAPI_TOKEN}"
],
"env": {
"VAPI_TOKEN": "YOUR_VAPI_API_KEY"
}
}
}
}
```
Replace YOUR\_VAPI\_API\_KEY with your API key.
Save and restart Claude Desktop.
**Example prompt:**
> "Have my customer support assistant call Jeremy at +1555123456."
***
## Core Tools
The Vapi MCP Server exposes these actions as MCP tools:
| Tool | Description | Example Usage |
| -------------------- | ------------------------------------------ | ---------------------------------- |
| `list_assistants` | List all Vapi assistants | Show all configured assistants |
| `create_assistant` | Create a new Vapi assistant | Add a new assistant for a use case |
| `get_assistant` | Get a Vapi assistant by ID | View assistant config |
| `list_calls` | List all calls | Review call activity |
| `create_call` | Create an outbound call (now or scheduled) | Initiate or schedule a call |
| `get_call` | Get details for a specific call | Check status or result of a call |
| `list_phone_numbers` | List all Vapi phone numbers | See available numbers |
| `get_phone_number` | Get details of a specific phone number | Inspect a phone number |
| `list_tools` | List all available Vapi tools | Tool discovery |
| `get_tool` | Get details of a specific tool | Tool integration info |
Scheduling calls: The create\_call action supports scheduling with the optional scheduledAt parameter.
***
## Integration Options
Connect to the Vapi-hosted MCP server using the streamable-HTTP protocol.
Recommended for most production use cases.
Use this for clients or SDKs that support streamable-HTTP transport.
* **Endpoint:** `https://mcp.vapi.ai/mcp`
* **Authentication:** Pass your Vapi API key as a bearer token:
Authorization: Bearer YOUR\_VAPI\_API\_KEY
Example config:
```json
{
"mcpServers": {
"vapi-mcp": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.vapi.ai/mcp",
"--header",
"Authorization: Bearer ${VAPI_TOKEN}"
],
"env": {
"VAPI_TOKEN": "YOUR_VAPI_API_KEY"
}
}
}
}
```
Connect to the Vapi-hosted MCP server using Server-Sent Events (SSE).
Use this for clients or SDKs that support SSE transport.
* **Endpoint:** `https://mcp.vapi.ai/sse`
* **Authentication:** Pass your Vapi API key as a bearer token:
Authorization: Bearer YOUR\_VAPI\_API\_KEY
Example config for Claude:
```json
{
"mcpServers": {
"vapi-sse": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.vapi.ai/sse",
"--header",
"Authorization: Bearer ${VAPI_TOKEN}"
],
"env": {
"VAPI_TOKEN": "YOUR_VAPI_API_KEY"
}
}
}
}
```
The OpenAI responses API now supports MCP. Read more here.
```typescript title="typescript"
import OpenAI from 'openai';
// Replace with your actual OpenAI API key
const openai = new OpenAI({ apiKey: 'YOUR_OPENAI_API_KEY' });
async function main() {
const response = await openai.responses.create({
model: 'gpt-4.1',
tools: [
{
type: 'mcp',
server_label: 'vapi-mcp',
server_url: 'https://mcp.vapi.ai/mcp',
headers: { "Authorization": "Bearer YOUR_VAPI_API_KEY" }
},
],
input: 'What vapi tools do you have available?',
});
console.dir(response, { depth: null });
}
main();
```
```python title="python"
import openai
# Replace with your actual OpenAI API key
openai.api_key = 'YOUR_OPENAI_API_KEY'
response = openai.responses.create(
model="gpt-4.1",
tools=[
{
"type": "mcp",
"server_label": "vapi-mcp",
"server_url": "https://mcp.vapi.ai/mcp",
"headers": {"Authorization": "Bearer YOUR_VAPI_API_KEY"}
},
],
input="What vapi tools do you have available?",
)
print(response)
```
Run the MCP server on your own machine for development or testing.
* **Start locally:**
```bash
npx -y @vapi-ai/mcp-server
```
* **Authentication:** Set the `VAPI_TOKEN` environment variable to your API key.
Example config for Claude:
```json
{
"mcpServers": {
"vapi-mcp-server": {
"command": "npx",
"args": [
"-y",
"@vapi-ai/mcp-server"
],
"env": {
"VAPI_TOKEN": "YOUR_VAPI_API_KEY"
}
}
}
}
```
Use this for clients or SDKs that support local command-based MCP servers.
Connect your client or SDK to the local server endpoint (default: `http://localhost:3000`).
***
## Custom MCP Client Integration
You can use any MCP-compatible client (SDKs available for multiple languages).
Choose a language:
* [TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)
* [Python](https://github.com/modelcontextprotocol/python-sdk)
* [Java](https://github.com/modelcontextprotocol/java-sdk)
* [Kotlin](https://github.com/modelcontextprotocol/kotlin-sdk)
* [C#](https://github.com/modelcontextprotocol/csharp-sdk)
Set up your SDK to connect to the Vapi MCP Server ([https://mcp.vapi.ai/sse](https://mcp.vapi.ai/sse)) and authenticate with your API key.
Query available tools, list assistants, create calls, etc, via your SDK.
***
### Example: Build a client with Node.js
```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import dotenv from 'dotenv';
dotenv.config();
const mcpClient = new Client({ name: 'vapi-client', version: '1.0.0' });
const transport = new StreamableHTTPClientTransport(
new URL('https://mcp.vapi.ai/mcp'),
{ requestInit: { headers: { Authorization: `Bearer ${process.env.VAPI_TOKEN}` } } }
);
async function main() {
await mcpClient.connect(transport);
const assistants = await mcpClient.callTool({ name: 'list_assistants', arguments: {} });
console.log(assistants);
await mcpClient.close();
}
main();
```
```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
import dotenv from 'dotenv';
dotenv.config();
const mcpClient = new Client({ name: 'vapi-client', version: '1.0.0' });
const transport = new SSEClientTransport(
new URL('https://mcp.vapi.ai/sse'),
{ requestInit: { headers: { Authorization: `Bearer ${process.env.VAPI_TOKEN}` } } }
);
async function main() {
await mcpClient.connect(transport);
const assistants = await mcpClient.callTool({ name: 'list_assistants', arguments: {} });
console.log(assistants);
await mcpClient.close();
}
main();
```
### Detailed example: Build a client with Node.js
```javascript
#!/usr/bin/env node
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import dotenv from 'dotenv';
// Load environment variables from .env file
dotenv.config();
// Ensure API key is available
if (!process.env.VAPI_TOKEN) {
console.error('Error: VAPI_TOKEN environment variable is required');
process.exit(1);
}
async function main() {
try {
// Initialize MCP client
const mcpClient = new Client({
name: 'vapi-client-example',
version: '1.0.0',
});
// Create Streamable-HTTP transport for connection to remote Vapi MCP server
const serverUrl = 'https://mcp.vapi.ai/mcp';
const headers = {
Authorization: `Bearer ${process.env.VAPI_TOKEN}`,
};
const options = {
requestInit: { headers: headers },
};
const transport = new StreamableHTTPClientTransport(new URL(serverUrl), options);
console.log('Connecting to Vapi MCP server via Streamable HTTP...');
await mcpClient.connect(transport);
console.log('Connected successfully');
// Helper function to parse tool responses
function parseToolResponse(response) {
if (!response?.content) return response;
const textItem = response.content.find(item => item.type === 'text');
if (textItem?.text) {
try {
return JSON.parse(textItem.text);
} catch {
return textItem.text;
}
}
return response;
}
try {
// List available tools
const toolsResult = await mcpClient.listTools();
console.log('Available tools:');
toolsResult.tools.forEach((tool) => {
console.log(`- ${tool.name}: ${tool.description}`);
});
// List assistants
console.log('\nListing assistants...');
const assistantsResponse = await mcpClient.callTool({
name: 'list_assistants',
arguments: {},
});
const assistants = parseToolResponse(assistantsResponse);
if (!(Array.isArray(assistants) && assistants.length > 0)) {
console.log('No assistants found. Please create an assistant in the Vapi dashboard first.');
return;
}
console.log('Your assistants:');
assistants.forEach((assistant) => {
console.log(`- ${assistant.name} (${assistant.id})`);
});
// List phone numbers
console.log('\nListing phone numbers...');
const phoneNumbersResponse = await mcpClient.callTool({
name: 'list_phone_numbers',
arguments: {},
});
const phoneNumbers = parseToolResponse(phoneNumbersResponse);
if (!(Array.isArray(phoneNumbers) && phoneNumbers.length > 0)) {
console.log('No phone numbers found. Please add a phone number in the Vapi dashboard first.');
return;
}
console.log('Your phone numbers:');
phoneNumbers.forEach((phoneNumber) => {
console.log(`- ${phoneNumber.phoneNumber} (${phoneNumber.id})`);
});
// Create a call using the first assistant and first phone number
const phoneNumberId = phoneNumbers[0].id;
const assistantId = assistants[0].id;
console.log(`\nCreating a call using assistant (${assistantId}) and phone number (${phoneNumberId})...`);
const createCallResponse = await mcpClient.callTool({
name: 'create_call',
arguments: {
assistantId: assistantId,
phoneNumberId: phoneNumberId,
customer: {
number: "+1234567890" // Replace with actual customer phone number
}
// Optional: schedule a call for the future
// scheduledAt: "2025-04-15T15:30:00Z"
// assistantOverrides: {
// variableValues: {
// name: 'John Doe',
// age: '25',
// },
// },
},
});
const createdCall = parseToolResponse(createCallResponse);
console.log('Call created:', JSON.stringify(createdCall, null, 2));
} finally {
console.log('\nDisconnecting from server...');
await mcpClient.close();
console.log('Disconnected');
}
} catch (error) {
console.error('Error:', error);
process.exit(1);
}
}
main();
```
```javascript
#!/usr/bin/env node
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
import dotenv from 'dotenv';
// Load environment variables from .env file
dotenv.config();
// Ensure API key is available
if (!process.env.VAPI_TOKEN) {
console.error('Error: VAPI_TOKEN environment variable is required');
process.exit(1);
}
async function main() {
try {
// Initialize MCP client
const mcpClient = new Client({
name: 'vapi-client-example',
version: '1.0.0',
});
// Create SSE transport for connection to remote Vapi MCP server
const serverUrl = 'https://mcp.vapi.ai/sse';
const headers = {
Authorization: `Bearer ${process.env.VAPI_TOKEN}`,
};
const options = {
requestInit: { headers: headers },
eventSourceInit: {
fetch: (url, init) => {
return fetch(url, {
...(init || {}),
headers: {
...(init?.headers || {}),
...headers,
},
});
},
},
};
const transport = new SSEClientTransport(new URL(serverUrl), options);
console.log('Connecting to Vapi MCP server via SSE...');
await mcpClient.connect(transport);
console.log('Connected successfully');
// Helper function to parse tool responses
function parseToolResponse(response) {
if (!response?.content) return response;
const textItem = response.content.find(item => item.type === 'text');
if (textItem?.text) {
try {
return JSON.parse(textItem.text);
} catch {
return textItem.text;
}
}
return response;
}
try {
// List available tools
const toolsResult = await mcpClient.listTools();
console.log('Available tools:');
toolsResult.tools.forEach((tool) => {
console.log(`- ${tool.name}: ${tool.description}`);
});
// List assistants
console.log('\nListing assistants...');
const assistantsResponse = await mcpClient.callTool({
name: 'list_assistants',
arguments: {},
});
const assistants = parseToolResponse(assistantsResponse);
if (!(Array.isArray(assistants) && assistants.length > 0)) {
console.log('No assistants found. Please create an assistant in the Vapi dashboard first.');
return;
}
console.log('Your assistants:');
assistants.forEach((assistant) => {
console.log(`- ${assistant.name} (${assistant.id})`);
});
// List phone numbers
console.log('\nListing phone numbers...');
const phoneNumbersResponse = await mcpClient.callTool({
name: 'list_phone_numbers',
arguments: {},
});
const phoneNumbers = parseToolResponse(phoneNumbersResponse);
if (!(Array.isArray(phoneNumbers) && phoneNumbers.length > 0)) {
console.log('No phone numbers found. Please add a phone number in the Vapi dashboard first.');
return;
}
console.log('Your phone numbers:');
phoneNumbers.forEach((phoneNumber) => {
console.log(`- ${phoneNumber.phoneNumber} (${phoneNumber.id})`);
});
// Create a call using the first assistant and first phone number
const phoneNumberId = phoneNumbers[0].id;
const assistantId = assistants[0].id;
console.log(`\nCreating a call using assistant (${assistantId}) and phone number (${phoneNumberId})...`);
const createCallResponse = await mcpClient.callTool({
name: 'create_call',
arguments: {
assistantId: assistantId,
phoneNumberId: phoneNumberId,
customer: {
phoneNumber: "+1234567890" // Replace with actual customer phone number
}
// Optional: schedule a call for the future
// scheduledAt: "2025-04-15T15:30:00Z"
},
});
const createdCall = parseToolResponse(createCallResponse);
console.log('Call created:', JSON.stringify(createdCall, null, 2));
} finally {
console.log('\nDisconnecting from server...');
await mcpClient.close();
console.log('Disconnected');
}
} catch (error) {
console.error('Error:', error);
process.exit(1);
}
}
main();
```
For more detailed examples and complete client implementations, see the
[MCP Client Quickstart](https://modelcontextprotocol.io/quickstart/client)
.
## References
* [Github repo](https://github.com/VapiAI/mcp-server)
* [Model Context Protocol docs](https://modelcontextprotocol.io)
* [Vapi dashboard](https://dashboard.vapi.ai)
* [MCP client quickstart](https://modelcontextprotocol.io/quickstart/client)
Join our Discord community for MCP support.
Full API documentation for tools.
# Ecosystem
> Find all of our resources here.
{/* Use this LInk to modify the content -> https://onecompiler.com/ejs/425khha82 */}
# Project integration
> Initialize Vapi in your existing projects with intelligent auto-detection
## Overview
The `vapi init` command intelligently integrates Vapi into your existing codebase. It automatically detects your framework, installs the appropriate SDK, and generates production-ready code examples tailored to your project structure.
**In this guide, you'll learn to:**
* Initialize Vapi in any project
* Understand what files are generated
* Customize the initialization process
* Work with different frameworks
## Quick start
Navigate to your project directory and run:
```bash
cd my-project
vapi init
```
The CLI will:
1. Detect your project type and framework
2. Install the appropriate Vapi SDK
3. Generate example components and API routes
4. Create environment configuration templates
5. Provide next steps specific to your setup
## How it works
### Framework detection
The CLI analyzes your project structure to identify:
* **Package files**: `package.json`, `requirements.txt`, `go.mod`, etc.
* **Configuration files**: Framework-specific configs
* **Project structure**: Directory patterns and file extensions
* **Dependencies**: Installed packages and libraries
### What gets generated
Based on your framework, the CLI generates:
```bash
vapi init
# Detected: Next.js application
```
**Generated files:**
* `components/VapiButton.tsx` - Voice call button component
* `pages/api/vapi/webhook.ts` - Webhook handler endpoint
* `lib/vapi-client.ts` - Vapi client setup
* `.env.example` - Environment variables template
**Installed packages:**
* `@vapi-ai/web` - Web SDK for browser integration
* `@vapi-ai/server-sdk` - Server SDK for webhooks
```bash
vapi init
# Detected: Python application
```
**Generated files:**
* `vapi_example.py` - Basic assistant example
* `webhook_handler.py` - Flask/FastAPI webhook handler
* `requirements.txt` - Updated with Vapi SDK
* `.env.example` - Environment variables template
**Installed packages:**
* `vapi-server-sdk` - Python server SDK
```bash
vapi init
# Detected: Node.js application
```
**Generated files:**
* `vapi-example.js` - Basic usage example
* `webhook-server.js` - Express webhook handler
* `.env.example` - Environment variables template
**Installed packages:**
* `@vapi-ai/server-sdk` - TypeScript/JavaScript SDK
## Supported frameworks
### Frontend frameworks
* Create React App
* Vite
* Custom webpack
* Vue 3
* Nuxt.js
* Vite
* Angular 12+
* Ionic
* App Router
* Pages Router
* API Routes
* SvelteKit
* Vite
* HTML/CSS/JS
* Webpack
* Parcel
### Mobile frameworks
* Expo
* Bare workflow
* iOS & Android
* Web support
### Backend frameworks
* Express
* Fastify
* Koa
* Django
* FastAPI
* Flask
* Gin
* Echo
* Fiber
* Rails
* Sinatra
* Spring Boot
* Quarkus
* ASP.NET Core
* Blazor
## Advanced options
### Specify target directory
Initialize in a specific directory:
```bash
vapi init /path/to/project
```
### Skip SDK installation
Generate only example files without installing packages:
```bash
vapi init --skip-install
```
### Force framework
Override auto-detection:
```bash
vapi init --framework react
vapi init --framework python
```
### Custom templates
Use your own templates:
```bash
vapi init --template @myorg/vapi-templates
```
## Environment setup
After initialization, configure your environment:
```bash
cp .env.example .env
```
Get your API key from the [Vapi Dashboard](https://dashboard.vapi.ai/):
```bash
VAPI_API_KEY=your-api-key-here
```
For local development:
```bash
VAPI_WEBHOOK_URL=https://your-domain.com/api/vapi/webhook
```
## Common patterns
### Adding to monorepos
For monorepos, run init in the specific package:
```bash
cd packages/web-app
vapi init
cd ../api-server
vapi init
```
### CI/CD integration
Add to your build process:
```yaml
# GitHub Actions example
- name: Setup Vapi
run: |
curl -sSL https://vapi.ai/install.sh | bash
vapi init --skip-install
```
### Docker environments
Include in your Dockerfile:
```dockerfile
# Install Vapi CLI
RUN curl -sSL https://vapi.ai/install.sh | bash
# Initialize project
RUN vapi init --skip-install
```
## Troubleshooting
If the CLI can't detect your framework:
1. Ensure you're in the project root
2. Check for required config files
3. Use `--framework` flag to specify manually
```bash
vapi init --framework react
```
For permission issues during SDK installation:
```bash
# npm projects
sudo npm install
# Python projects
pip install --user vapi-server-sdk
```
If files already exist, the CLI will:
1. Ask for confirmation before overwriting
2. Create backup files (`.backup` extension)
3. Show a diff of changes
Use `--force` to skip confirmations:
```bash
vapi init --force
```
## Next steps
After initializing your project:
* **[Test locally](/cli/webhook):** Use `vapi listen` to test webhooks
* **[Create assistants](/quickstart/phone):** Build your first voice assistant
* **[Set up MCP](/cli/mcp):** Enhance your IDE with Vapi intelligence
***
**Example output:**
```bash
$ vapi init
🔍 Analyzing project...
✓ Detected: Next.js 14 application
📦 Installing dependencies...
✓ Installed @vapi-ai/web@latest
✓ Installed @vapi-ai/server-sdk@latest
📝 Generating files...
✓ Created components/VapiButton.tsx
✓ Created app/api/vapi/webhook/route.ts
✓ Created lib/vapi-client.ts
✓ Created .env.example
🎉 Vapi initialized successfully!
Next steps:
1. Copy .env.example to .env
2. Add your VAPI_API_KEY
3. Run: npm run dev
4. Test the voice button at http://localhost:3000
```
# MCP integration
> Turn your IDE into a Vapi expert with Model Context Protocol
## Overview
The Model Context Protocol (MCP) integration transforms your IDE's AI assistant into a Vapi expert. Once configured, your IDE gains complete, accurate knowledge of Vapi's APIs, features, and best practices - eliminating AI hallucinations and outdated information.
**In this guide, you'll learn to:**
* Set up MCP in supported IDEs
* Understand what knowledge is provided
* Use your enhanced IDE effectively
* Troubleshoot common issues
## Quick start
Run the setup command to auto-configure all supported IDEs:
```bash
vapi mcp setup
```
Or configure a specific IDE:
```bash
vapi mcp setup cursor # For Cursor
vapi mcp setup windsurf # For Windsurf
vapi mcp setup vscode # For VSCode with Copilot
```
## What is MCP?
Model Context Protocol is a standard that allows AI assistants to access structured knowledge and tools. When you set up MCP for Vapi:
* Your IDE's AI gains access to complete Vapi documentation
* Code suggestions become accurate and up-to-date
* Examples use real, working Vapi patterns
* API hallucinations are eliminated
## Supported IDEs
AI-first code editor with deep MCP integration
**Setup:** Creates `.cursor/mcp.json`
Codeium's AI-powered IDE
**Setup:** Creates `.windsurf/mcp.json`
With GitHub Copilot extension
**Setup:** Configures Copilot settings
## How it works
### What gets configured
The MCP setup creates configuration files that connect your IDE to the Vapi MCP server:
**File:** `.cursor/mcp.json`
```json
{
"servers": {
"vapi-docs": {
"command": "npx",
"args": ["@vapi-ai/mcp-server"]
}
}
}
```
**File:** `.windsurf/mcp.json`
```json
{
"servers": {
"vapi-docs": {
"command": "npx",
"args": ["@vapi-ai/mcp-server"]
}
}
}
```
**Settings:** Updates workspace settings
```json
{
"github.copilot.advanced": {
"mcp.servers": {
"vapi-docs": {
"command": "npx",
"args": ["@vapi-ai/mcp-server"]
}
}
}
}
```
### What knowledge is provided
Your IDE gains access to:
* **Complete API Reference** - Every endpoint, parameter, and response
* **Code Examples** - Working samples for all features
* **Integration Guides** - Step-by-step implementation patterns
* **Best Practices** - Recommended approaches and patterns
* **Latest Features** - Always up-to-date with new releases
* **Troubleshooting** - Common issues and solutions
## Using your enhanced IDE
### Example prompts
Once MCP is configured, try these prompts in your IDE:
**Prompt:** "How do I create a voice assistant with Vapi?"
Your IDE will provide accurate code like:
```typescript
import { VapiClient } from "@vapi-ai/server-sdk";
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
const assistant = await client.assistants.create({
name: "Customer Support",
model: {
provider: "openai",
model: "gpt-4",
systemPrompt: "You are a helpful customer support agent..."
},
voice: {
provider: "11labs",
voiceId: "rachel"
}
});
```
**Prompt:** "Show me how to handle Vapi webhooks"
Get complete webhook examples:
```typescript
app.post('/webhook', async (req, res) => {
const { type, call, assistant } = req.body;
switch (type) {
case 'call-started':
console.log(`Call ${call.id} started`);
break;
case 'speech-update':
console.log(`User said: ${req.body.transcript}`);
break;
case 'function-call':
// Handle tool calls
const { functionName, parameters } = req.body.functionCall;
const result = await handleFunction(functionName, parameters);
res.json({ result });
return;
}
res.status(200).send();
});
```
**Prompt:** "How do I set up call recording with custom storage?"
Get detailed implementation:
```typescript
const assistant = await client.assistants.create({
name: "Recorded Assistant",
recordingEnabled: true,
artifactPlan: {
recordingEnabled: true,
videoRecordingEnabled: false,
recordingPath: "s3://my-bucket/recordings/{call_id}"
},
credentialIds: ["aws-s3-credential-id"]
});
```
### Best practices
Ask detailed questions about Vapi features:
* ✅ "How do I transfer calls to a human agent in Vapi?"
* ❌ "How do I transfer calls?"
Ask for working code samples:
* "Show me a complete example of..."
* "Generate a working implementation of..."
Specify SDK versions when needed:
* "Using @vapi-ai/web v2.0, how do I..."
* "What's the latest way to..."
## Configuration options
### Check status
View current MCP configuration:
```bash
vapi mcp status
```
Output:
```
MCP Configuration Status:
✓ Cursor: Configured (.cursor/mcp.json)
✗ Windsurf: Not configured
✓ VSCode: Configured (workspace settings)
Vapi MCP Server: v1.2.3 (latest)
```
### Update server
Keep the MCP server updated:
```bash
# Update to latest version
npm update -g @vapi-ai/mcp-server
# Or reinstall
npm install -g @vapi-ai/mcp-server@latest
```
### Remove configuration
Remove MCP configuration:
```bash
# Remove from all IDEs
vapi mcp remove
# Remove from specific IDE
vapi mcp remove cursor
```
## How MCP tools work
The Vapi MCP server provides these tools to your IDE:
Semantic search across all Vapi docs
**Example:** "How to handle voicemail detection"
Retrieve code samples for any feature
**Example:** "WebSocket connection example"
Get detailed API endpoint information
**Example:** "POST /assistant parameters"
Step-by-step guides for complex features
**Example:** "Workflow implementation guide"
## Troubleshooting
If your IDE isn't using the MCP knowledge:
1. **Restart your IDE** after configuration
2. **Check the logs** in your IDE's output panel
3. **Verify npm is accessible** from your IDE
4. **Ensure MCP server is installed** globally
```bash
# Verify installation
npm list -g @vapi-ai/mcp-server
```
For permission issues:
```bash
# Install with proper permissions
sudo npm install -g @vapi-ai/mcp-server
# Or use a Node version manager
nvm use 18
npm install -g @vapi-ai/mcp-server
```
If you're getting old API information:
1. Update the MCP server:
```bash
npm update -g @vapi-ai/mcp-server
```
2. Clear your IDE's cache
3. Restart the IDE
For different projects needing different configs:
* MCP configuration is per-workspace
* Run `vapi mcp setup` in each project
* Configuration won't conflict between projects
## Advanced usage
### Custom MCP configuration
Modify the generated MCP configuration for advanced needs:
```json
{
"servers": {
"vapi-docs": {
"command": "npx",
"args": ["@vapi-ai/mcp-server"],
"env": {
"VAPI_MCP_LOG_LEVEL": "debug"
}
}
}
}
```
### Using with teams
Share MCP configuration with your team:
1. **Commit the config files** (`.cursor/mcp.json`, etc.)
2. **Document the setup** in your README
3. **Include in onboarding** for new developers
Example README section:
```markdown
## Development Setup
This project uses Vapi MCP for enhanced IDE support:
1. Install Vapi CLI: `curl -sSL https://vapi.ai/install.sh | bash`
2. Set up MCP: `vapi mcp setup`
3. Restart your IDE
```
## Next steps
Now that MCP is configured:
* **[Create assistants](/quickstart/phone):** Build your first voice AI
* **[Test webhooks locally](/cli/webhook):** Debug webhooks with tunneling services
* **[Manage resources](/cli/overview#common-commands):** Use CLI commands
***
**Pro tip:** After setting up MCP, try asking your IDE to "Create a complete Vapi voice assistant with error handling and logging" - watch it generate production-ready code with all the right patterns!
# Local webhook testing
> Forward webhooks to your local development server with vapi listen
## Overview
The `vapi listen` command provides a local webhook forwarding service that receives events and forwards them to your local development server. This helps you debug webhook integrations during development.
**Important:** `vapi listen` does NOT provide a public URL or tunnel. You'll need to use a separate tunneling solution like ngrok to expose your local server to the internet.
**In this guide, you'll learn to:**
* Set up local webhook forwarding with a tunneling service
* Debug webhook events in real-time
* Configure advanced forwarding options
* Handle different webhook types
**No automatic tunneling:** The `vapi listen` command is a local forwarder only. It does not create a public URL or tunnel to the internet. You must use a separate tunneling service (like ngrok) and configure your Vapi webhook URLs manually.
## Quick start
Use a tunneling service like ngrok to create a public URL:
```bash
# Example with ngrok
ngrok http 4242 # 4242 is the default port for vapi listen
```
Note the public URL provided by your tunneling service (e.g., `https://abc123.ngrok.io`)
```bash
vapi listen --forward-to localhost:3000/webhook
```
This starts a local server on port 4242 that forwards to your application
Go to your Vapi Dashboard and update your webhook URLs to point to your tunnel URL:
* Assistant webhook URL: `https://abc123.ngrok.io`
* Phone number webhook URL: `https://abc123.ngrok.io`
* Or any other webhook configuration
Trigger webhook events (make calls, etc.) and see them forwarded through the tunnel to your local server
## How it works
**Current implementation:** The `vapi listen` command acts as a local webhook forwarder only. It receives webhook events on a local port (default 4242) and forwards them to your specified endpoint. To receive events from Vapi, you must:
1. Use a tunneling service (ngrok, localtunnel, etc.) to expose port 4242 to the internet
2. Configure your Vapi webhook URLs to point to the tunnel URL
3. The flow is: Vapi → Your tunnel URL → vapi listen (port 4242) → Your local server
The CLI starts a webhook forwarder on port 4242 (configurable)
Your tunneling service creates a public URL that routes to port 4242
Update your Vapi webhook URL to point to the tunnel's public URL
Webhook events flow: Vapi → Tunnel → CLI forwarder → Your local endpoint
Events are displayed in your terminal for debugging
## Basic usage
### Standard forwarding
Forward to your local development server:
```bash
# Forward to localhost:3000/webhook
vapi listen --forward-to localhost:3000/webhook
# Short form
vapi listen -f localhost:3000/webhook
```
### Custom port
Use a different port for the webhook listener:
```bash
# Listen on port 8080 instead of default 4242
vapi listen --forward-to localhost:3000/webhook --port 8080
# Remember to update your tunnel to use port 8080
ngrok http 8080
```
### Skip TLS verification
For development with self-signed certificates:
```bash
vapi listen --forward-to https://localhost:3000/webhook --skip-verify
```
Only use `--skip-verify` in development. Never in production.
## Understanding the output
When you run `vapi listen`, you'll see:
```bash
$ vapi listen --forward-to localhost:3000/webhook
🎧 Vapi Webhook Listener
📡 Listening on: http://localhost:4242
📍 Forwarding to: http://localhost:3000/webhook
⚠️ To receive Vapi webhooks:
1. Use a tunneling service (e.g., ngrok http 4242)
2. Update your Vapi webhook URLs to the tunnel URL
Waiting for webhook events...
[2024-01-15 10:30:45] POST /
Event: call-started
Call ID: call_abc123def456
Status: 200 OK (45ms)
[2024-01-15 10:30:52] POST /
Event: speech-update
Transcript: "Hello, how can I help you?"
Status: 200 OK (12ms)
```
## Webhook event types
The listener forwards all Vapi webhook events:
* `call-started` - Call initiated
* `call-ended` - Call completed
* `call-failed` - Call encountered an error
* `speech-update` - Real-time transcription
* `transcript` - Final transcription
* `voice-input` - User speaking detected
* `function-call` - Tool/function invoked
* `assistant-message` - Assistant response
* `conversation-update` - Conversation state change
* `error` - Error occurred
* `recording-ready` - Call recording available
* `analysis-ready` - Call analysis complete
## Advanced configuration
### Headers and authentication
The listener adds helpful headers to forwarded requests:
```http
X-Forwarded-For: vapi-webhook-listener
X-Original-Host:
X-Webhook-Event: call-started
X-Webhook-Timestamp: 1705331445
```
Your server receives the exact webhook payload from Vapi with these additional headers for debugging.
### Setting up with different tunneling services
```bash
# Terminal 1: Start ngrok tunnel
ngrok http 4242
# Terminal 2: Start vapi listener
vapi listen --forward-to localhost:3000/webhook
# Use the ngrok URL in Vapi Dashboard
```
```bash
# Terminal 1: Install and start localtunnel
npm install -g localtunnel
lt --port 4242
# Terminal 2: Start vapi listener
vapi listen --forward-to localhost:3000/webhook
# Use the localtunnel URL in Vapi Dashboard
```
```bash
# Terminal 1: Start cloudflare tunnel
cloudflared tunnel --url http://localhost:4242
# Terminal 2: Start vapi listener
vapi listen --forward-to localhost:3000/webhook
# Use the cloudflare URL in Vapi Dashboard
```
**Pro tip:** Some tunneling services offer static URLs (like ngrok with a paid plan), which means you won't need to update your Vapi webhook configuration every time you restart development.
### Filtering events
Filter specific event types (coming soon):
```bash
# Only forward call events
vapi listen --forward-to localhost:3000 --filter "call-*"
# Multiple filters
vapi listen --forward-to localhost:3000 --filter "call-started,call-ended"
```
### Response handling
The listener expects standard HTTP responses:
* **200-299**: Success, event processed
* **400-499**: Client error, event rejected
* **500-599**: Server error, will retry
## Development workflow
### Typical setup
```bash
# In terminal 1
npm run dev # Your app on localhost:3000
```
```bash
# In terminal 2
ngrok http 4242 # Creates public URL for the CLI listener
# Note the public URL (e.g., https://abc123.ngrok.io)
```
```bash
# In terminal 3
vapi listen --forward-to localhost:3000/api/vapi/webhook
```
Update your Vapi webhook URLs to point to the ngrok URL from step 2
Use the Vapi dashboard or API to trigger webhooks
See events in the CLI terminal and debug your handler
**Data flow:** Vapi sends webhooks → Ngrok tunnel (public URL) → vapi listen (port 4242) → Your local server (port 3000)
### Example webhook handler
```typescript title="Node.js/Express"
app.post('/api/vapi/webhook', async (req, res) => {
const { type, call, timestamp } = req.body;
console.log(`Webhook received: ${type} at ${timestamp}`);
switch (type) {
case 'call-started':
console.log(`Call ${call.id} started with ${call.customer.number}`);
break;
case 'speech-update':
console.log(`User said: ${req.body.transcript}`);
break;
case 'function-call':
const { functionName, parameters } = req.body.functionCall;
console.log(`Function called: ${functionName}`, parameters);
// Return function result
const result = await processFunction(functionName, parameters);
return res.json({ result });
case 'call-ended':
console.log(`Call ended. Duration: ${call.duration}s`);
break;
}
res.status(200).send();
});
```
```python title="Python/FastAPI"
from fastapi import FastAPI, Request
from datetime import datetime
app = FastAPI()
@app.post("/api/vapi/webhook")
async def handle_webhook(request: Request):
data = await request.json()
event_type = data.get("type")
call = data.get("call", {})
timestamp = data.get("timestamp")
print(f"Webhook received: {event_type} at {timestamp}")
if event_type == "call-started":
print(f"Call {call.get('id')} started")
elif event_type == "speech-update":
print(f"User said: {data.get('transcript')}")
elif event_type == "function-call":
function_call = data.get("functionCall", {})
function_name = function_call.get("functionName")
parameters = function_call.get("parameters")
# Process function and return result
result = await process_function(function_name, parameters)
return {"result": result}
elif event_type == "call-ended":
print(f"Call ended. Duration: {call.get('duration')}s")
return {"status": "ok"}
```
```go title="Go/Gin"
func handleWebhook(c *gin.Context) {
var data map[string]interface{}
if err := c.ShouldBindJSON(&data); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
eventType := data["type"].(string)
fmt.Printf("Webhook received: %s\n", eventType)
switch eventType {
case "call-started":
call := data["call"].(map[string]interface{})
fmt.Printf("Call %s started\n", call["id"])
case "speech-update":
fmt.Printf("User said: %s\n", data["transcript"])
case "function-call":
functionCall := data["functionCall"].(map[string]interface{})
result := processFunction(
functionCall["functionName"].(string),
functionCall["parameters"],
)
c.JSON(200, gin.H{"result": result})
return
case "call-ended":
fmt.Println("Call ended")
}
c.JSON(200, gin.H{"status": "ok"})
}
```
## Testing scenarios
### Simulating errors
Test error handling in your webhook:
```bash
# Your handler returns 500
vapi listen --forward-to localhost:3000/webhook-error
# Output shows:
# Status: 500 Internal Server Error (23ms)
# Response: {"error": "Database connection failed"}
```
### Load testing
Test with multiple concurrent calls:
```bash
# Terminal 1: Start listener
vapi listen --forward-to localhost:3000/webhook
# Terminal 2: Trigger multiple calls via API
for i in {1..10}; do
vapi call create --to "+1234567890" &
done
```
### Debugging specific calls
Filter logs by call ID:
```bash
# Coming soon
vapi listen --forward-to localhost:3000 --call-id call_abc123
```
## Security considerations
The `vapi listen` command is designed for development only. In production, use proper webhook endpoints with authentication.
### Best practices
1. **Never expose sensitive data** in console logs
2. **Validate webhook signatures** in production
3. **Use HTTPS** for production endpoints
4. **Implement proper error handling**
5. **Set up monitoring** for production webhooks
### Production webhook setup
For production, configure webhooks in the Vapi dashboard:
```typescript
// Production webhook with signature verification
app.post('/webhook', verifyVapiSignature, async (req, res) => {
// Your production handler
});
```
## Troubleshooting
If you see "connection refused":
1. **Verify your server is running** on the specified port
2. **Check the endpoint path** matches your route
3. **Ensure no firewall** is blocking local connections
```bash
# Test your endpoint directly
curl -X POST http://localhost:3000/webhook -d '{}'
```
For timeout issues:
1. **Check response time** - Vapi expects \< 10s response
2. **Avoid blocking operations** in webhook handlers
3. **Use async processing** for heavy operations
```typescript
// Good: Quick response
app.post('/webhook', async (req, res) => {
// Queue for processing
await queue.add('process-webhook', req.body);
res.status(200).send();
});
```
If events aren't appearing:
1. **Check CLI authentication** - `vapi auth whoami`
2. **Verify account access** to the resources
3. **Ensure events are enabled** in assistant config
```bash
# Re-authenticate if needed
vapi login
```
For HTTPS endpoints:
```bash
# Development only - skip certificate verification
vapi listen --forward-to https://localhost:3000 --skip-verify
# Or use HTTP for local development
vapi listen --forward-to http://localhost:3000
```
## Next steps
Now that you can test webhooks locally:
* **[Build webhook handlers](/server-url/events):** Learn about all webhook events
* **[Implement tools](/tools/custom-tools):** Add custom functionality
* **[Set up production webhooks](/server-url):** Deploy to production
***
**Pro tip:** Keep `vapi listen` running while developing - you'll see all events in real-time and can iterate quickly on your webhook handlers without deployment delays!
# Authentication management
> Manage multiple Vapi accounts and environments with the CLI
## Overview
The Vapi CLI supports sophisticated authentication management, allowing you to work with multiple accounts, organizations, and environments seamlessly. This is perfect for developers who work across different teams, manage client accounts, or need to switch between production and staging environments.
**In this guide, you'll learn to:**
* Authenticate with your Vapi account
* Manage multiple accounts simultaneously
* Switch between organizations and environments
* Configure API keys and tokens
## Quick start
Authenticate with your primary account:
```bash
vapi login
```
This opens your browser for secure OAuth authentication.
View your authentication status:
```bash
vapi auth status
```
Add additional accounts without logging out:
```bash
vapi auth login
```
Switch between authenticated accounts:
```bash
vapi auth switch production
```
## Authentication methods
### OAuth login (recommended)
The default authentication method uses OAuth for maximum security:
```bash
vapi login
# Opens browser for authentication
# Securely stores tokens locally
```
Benefits:
* No manual API key handling
* Automatic token refresh
* Secure credential storage
* Organization access management
### API key authentication
For CI/CD or scripting, use API keys:
```bash
# Via environment variable
export VAPI_API_KEY=your-api-key
vapi assistant list
# Via command flag
vapi assistant list --api-key your-api-key
```
### Configuration file
Store API keys in configuration:
```yaml
# ~/.vapi-cli.yaml
api_key: your-api-key
base_url: https://api.vapi.ai # Optional custom endpoint
```
## Multi-account management
### Understanding accounts
Each authenticated account includes:
* **User identity** - Your email and user ID
* **Organization** - The Vapi organization you belong to
* **API access** - Permissions and API keys
* **Environment** - Production, staging, or custom
### Viewing accounts
List all authenticated accounts:
```bash
vapi auth status
```
Output:
```
🔐 Vapi Authentication Status
Active Account:
✓ Email: john@company.com
✓ Organization: Acme Corp (org_abc123)
✓ Environment: Production
✓ API Key: sk-prod_****efgh
Other Accounts:
• jane@agency.com - ClientCo (org_xyz789) [staging]
• john@personal.com - Personal (org_def456) [production]
Total accounts: 3
```
### Adding accounts
Add accounts without affecting existing ones:
```bash
# Add another account
vapi auth login
# You'll be prompted to:
# 1. Open browser for authentication
# 2. Choose an account alias (e.g., "staging", "client-a")
# 3. Confirm organization access
```
### Switching accounts
Switch between accounts instantly:
```bash
# Switch by alias
vapi auth switch staging
# Switch by email
vapi auth switch jane@agency.com
# Interactive selection
vapi auth switch
# Shows menu of available accounts
```
### Account aliases
Assign meaningful aliases to accounts:
```bash
# During login
vapi auth login --alias production
# Update existing
vapi auth alias john@company.com production
# Use aliases
vapi auth switch production
```
## Common workflows
### Development vs production
```bash
# Development work
vapi auth switch dev
vapi assistant create --name "Test Assistant"
# Production deployment
vapi auth switch prod
vapi assistant create --name "Customer Support"
```
```bash
# Client A work
vapi auth switch client-a
vapi phone list
# Client B work
vapi auth switch client-b
vapi workflow list
```
```bash
# Personal development
vapi auth switch personal
vapi init
# Team project
vapi auth switch team
vapi assistant list
```
### Account information
Get detailed information about current account:
```bash
vapi auth whoami
```
Output:
```json
{
"user": {
"id": "user_abc123",
"email": "john@company.com",
"name": "John Doe"
},
"organization": {
"id": "org_abc123",
"name": "Acme Corp",
"plan": "enterprise"
},
"permissions": [
"assistants:read",
"assistants:write",
"calls:create",
"billing:view"
]
}
```
### Token management
View and manage API tokens:
```bash
# View current token (masked)
vapi auth token
# Show full token (careful!)
vapi auth token --show
# Refresh token
vapi auth refresh
```
## Security best practices
### Credential storage
The CLI stores credentials securely:
* **macOS**: Keychain
* **Linux**: Secret Service API / keyring
* **Windows**: Credential Manager
### Environment isolation
Keep environments separate:
```bash
# Never mix environments
vapi auth switch prod
vapi assistant list # Production assistants
vapi auth switch dev
vapi assistant list # Development assistants
```
### CI/CD integration
For automated workflows:
```yaml
# GitHub Actions example
env:
VAPI_API_KEY: ${{ secrets.VAPI_PROD_KEY }}
steps:
- name: Deploy Assistant
run: |
vapi assistant create --file assistant.json
```
### Revoking access
Remove accounts when no longer needed:
```bash
# Logout from current account
vapi auth logout
# Logout from specific account
vapi auth logout jane@agency.com
# Logout from all accounts
vapi auth logout --all
```
## Advanced features
### Custom API endpoints
For on-premise or custom deployments:
```bash
# Login to custom endpoint
vapi login --base-url https://vapi.company.internal
# Or configure in file
echo "base_url: https://vapi.company.internal" >> ~/.vapi-cli.yaml
```
### Service accounts
For server applications:
```bash
# Create service account in dashboard
# Then configure:
export VAPI_API_KEY=service_account_key
export VAPI_ORG_ID=org_abc123
```
### Proxy configuration
For corporate environments:
```bash
# HTTP proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
# SOCKS proxy
export ALL_PROXY=socks5://proxy.company.com:1080
```
## Troubleshooting
Configure default browser:
```bash
# macOS
export BROWSER="Google Chrome"
# Linux
export BROWSER=firefox
# Windows
set BROWSER=chrome
```
If you see authentication errors:
```bash
# Refresh current token
vapi auth refresh
# Or re-login
vapi login
```
For credential storage problems:
```bash
# macOS: Reset keychain access
security unlock-keychain
# Linux: Install keyring
sudo apt-get install gnome-keyring
# Use file storage instead
vapi config set storage file
```
If you can't access organization resources:
1. Verify organization membership in dashboard
2. Check account permissions
3. Re-authenticate:
```bash
vapi auth logout
vapi login
```
## Best practices
### Account naming
Use clear, consistent aliases:
```bash
# Good aliases
vapi auth login --alias prod-acme
vapi auth login --alias dev-personal
vapi auth login --alias staging-client
# Avoid unclear aliases
vapi auth login --alias test1
vapi auth login --alias new
```
### Regular maintenance
Keep your authentication clean:
```bash
# Monthly review
vapi auth status
# Remove unused accounts
vapi auth logout old-client@example.com
# Update tokens
vapi auth refresh --all
```
### Team documentation
Document account structure for your team:
```markdown
## Vapi Accounts
- `prod`: Production (org_abc123)
- `staging`: Staging environment (org_abc124)
- `dev`: Shared development (org_abc125)
To switch: `vapi auth switch `
```
## Next steps
With authentication configured:
* **[Create assistants](/quickstart/phone):** Build voice assistants
* **[Initialize projects](/cli/init):** Add Vapi to your codebase
* **[Test webhooks](/cli/webhook):** Debug locally with any account
***
**Security tip:** Always use OAuth login for interactive use and API keys only for automation. Never commit API keys to version control!
# Changelog
document.querySelector('input[type="email"]').focus()}>Get the (almost) daily changelog} icon="envelope" iconType="solid">
# June 26, 2025
**Create web-based chat sessions with your assistants** using the new [`Web Chat`](https://api.vapi.ai/api#:~:text=WebChat) integration with [`OpenAI Web Chat Requests`](https://api.vapi.ai/api#:~:text=OpenAIWebChatRequest). Accept user input as strings or message arrays and manage conversations with session and customer information.
2. **Inworld TTS Voice Provider Integration**: You can now customize which language [`Inworld Voices`](https://api.vapi.ai/api#:~:text=InworldVoice) use like `English`, `Chinese`, and `Korean`. You can also set the TTS `model` and toggle voice caching with `cachingEnabled`.
3. **Additional Customer Information Fields**: You can now include `email` and `externalId` fields when [creating customers](https://api.vapi.ai/api#:~:text=CreateCustomerDTO). You can also disable the E164 number format check with `numberE164CheckEnabled` – setting it to `false` lets you use non-E164 numbers like `1234` or `abc`, useful for dialing non-standard numbers on SIP trunks. This lets you store extra contact information and link customers to external systems.
4. **`schedulePlan` No Longer Required in Campaigns**: You can now [create campaigns](https://docs.vapi.ai/api-reference/campaigns/campaign-controller-create) without specifying a `schedulePlan`.
**Behavior Change**: The `Chat.assistantOverrides` property now only supports variable substitution in chat contexts, limiting its functionality compared to previous versions.
# June 25, 2025
# Custom Models, Enhanced Campaigns, and MCP Tool Improvements
**Bring your own hosted LLMs and Google Gemini models** to workflows with new [`WorkflowCustomModel`](https://api.vapi.ai/api#:~:text=WorkflowCustomModel) and [`WorkflowGoogleModel`](https://api.vapi.ai/api#:~:text=WorkflowGoogleModel) objects. Control payload structure for advanced integrations and expand your model choices beyond OpenAI.
**Gain deeper insight into campaign performance** with new call counters including `callsCounterQueued`, `callsCounterScheduled`, `callsCounterInProgress`, and `callsCounterEndedVoicemail` for comprehensive campaign tracking.
**Flexible tool integrations** with new [`McpToolMetadata`](https://api.vapi.ai/api#:~:text=McpToolMetadata) field. Select between Server-Sent Events (`sse`) or Streamable HTTP (`shttp`) protocols for tool communication.
\*\*Create support tickets directly through Vapi \*\* using the new [`/support/ticket`](https://api.vapi.ai/api#:~:text=SupportTicket) endpoint, simplifying how you request assistance.
1. **Multilingual LMNT Voice Support**: The [`LMNTVoice`](https://api.vapi.ai/api#:~:text=LMNTVoice) and [`FallbackLMNTVoice`](https://api.vapi.ai/api#:~:text=FallbackLMNTVoice) objects now support a `language` property (ISO 639-1 or `auto`) for selecting or auto-detecting spoken language in synthesized voices.
2. **Assistant Overrides in Chats**: The `assistantOverrides` property is now available in [`Chat`](https://api.vapi.ai/api#:~:text=Chat), [`CreateChatDTO`](https://api.vapi.ai/api#:~:text=CreateChatDTO), and [`OpenAIResponsesRequest`](https://api.vapi.ai/api#:~:text=OpenAIResponsesRequest), allowing you to dynamically override assistant settings and template variables per chat session.
3. **New API Endpoints and Objects**: Added `POST /workflow/generate` endpoint for workflow generation with tool IDs, plus new objects including `GenerateWorkflowDTO` and enhanced `CreateMcpToolDTO`/`UpdateMcpToolDTO` with metadata support.
4. **Include Messages in Server Response from Transfer Requests**: When transferring calls, you can now include a `message` to communicate with users during the process with [`ServerMessageResponse.message.message`](https://api.vapi.ai/api#:~:text=ServerMessageResponse).
**Breaking Change**: The `'aws-sts'` type is no longer supported in [`OAuth2AuthenticationPlan`](https://api.vapi.ai/api#:~:text=OAuth2AuthenticationPlan). If you're currently using this type in your OAuth2 authentication configurations, you'll need to update it to avoid errors.
# June 24, 2025
You can now use Inworld as a voice provider by selecting [`Inworld`](https://dashboard.vapi.ai/assistants#:~:text=VOICE-,Voice%20Configuration,-Select%20a%20voice) in your configuration. You can also route your InWorld credentials under [Settings > Integrations](https://dashboard.vapi.ai/settings/integrations#:~:text=Save-,Inworld,-For%20using%20voices). Finally, there are new `Call.endedReason` codes to help you better understand why calls ended due to Inworld voice issues.
2. **HMAC Authentication for Webhook Credentials**: Secure your webhooks with HMAC authentication by configuring [`Assistant.credentials.authenticationPlan`](https://api.vapi.ai/api#:~:text=Assistant,-AssistantPaginatedResponse) with [`HMACAuthenticationPlan`](https://api.vapi.ai/api#:~:text=HMACAuthenticationPlan), providing an alternative to OAuth2.
3. **Detailed Call End Reasons for Inworld Voice**: New `endedReason` codes provide more insight when calls end due to Inworld voice issues.
**Breaking Change**: The `codeSwitchingEnabled` property has been removed from Deepgram transcribers. If you're currently using this property in your Deepgram transcriber configurations, you'll need to remove it to avoid errors.
**Org Concurrency Limit Deprecated**: The `concurrencyLimit` field in [`Org`](https://api.vapi.ai/api#:~:text=Org), [`CreateOrgDTO`](https://api.vapi.ai/api#:~:text=CreateOrgDTO), and [`UpdateOrgDTO`](https://api.vapi.ai/api#:~:text=UpdateOrgDTO) is now marked as deprecated.
# June 20, 2025
# New Campaigns APIs and Assistant Improvements
**Create, retrieve, and manage campaigns** using the new [`/campaign` endpoints](https://docs.vapi.ai/api-reference/calls/list#:~:text=Campaign). Build automated call campaigns with specified customers and schedules.
**General Availability**: [`Assistant.modelOutputInMessagesEnabled`](https://api.vapi.ai/api#:~:text=SessionPaginatedResponse-,Assistant,-AssistantPaginatedResponse) is now generally available without beta limitations. You can decide whether to use the model's output in conversation history instead of the assistant's speech transcription.
1. **Simplified Assistant Property Structure**: Properties like `serverMessages`, `clientMessages`, and `serverUrl` have been moved under [`Assistant.monitorPlan`](https://api.vapi.ai/api#:~:text=SessionPaginatedResponse-,Assistant,-AssistantPaginatedResponse). This reorganization simplifies how you configure monitoring for your assistants.
2. **Node-Level Overrides for Model and Voice**: In [`Conversation Node`](https://api.vapi.ai/api#:~:text=ConversationNode), properties like `model`, `voice`, and `transcriber` now explicitly override the workflow's settings. This allows you to customize these settings for individual nodes within a workflow for greater control.
3. **Enhanced Credential Configuration in Assistants**: Assistants now support `credentials` and `credentialIds`, similar to workflows. This allows you to specify dynamic credentials specifically for assistant calls, enhancing security and flexibility.
4. **New Models Available in `ConversationNode`**: You can now use [`Google Models`](https://api.vapi.ai/api#:~:text=WorkflowGoogleModel) and [`Custom Models`](https://api.vapi.ai/api#:~:text=WorkflowCustomModel) in conversation nodes. This expands the range of language models that can be integrated into conversation nodes.
# June 19, 2025
# Workflow Configuration Enhancements and Assistant Updates
1. **Workflow-Level Configuration of Voice and Plans**: Developers can now configure `voice`, `transcriber`, and various plans like `monitorPlan` and `artifactPlan` at the workflow level. These configurations can still be overridden at the node level if needed.
2. **Use of Dynamic Credentials in Workflows**: Workflows now support `credentials` and `credentialIds`, allowing you to specify dynamic credentials for workflow calls. This offers more flexibility in credential management, enabling credentials to be tied directly to specific workflows.
3. **`backgroundDenoisingEnabled` Deprecated in Assistants**: The `backgroundDenoisingEnabled` property in Assistant is now deprecated. You should use the new [`Assistant.backgroundSpeechDenoisingPlan`](https://api.vapi.ai/api#:~:text=SessionPaginatedResponse-,Assistant,-AssistantPaginatedResponse) to configure advanced background noise and speech denoising features.
# June 18, 2025
## Overview
1. **API Request Tool**: You can now create [API request tools](https://api.vapi.ai/api#:~:text=ApiRequestTool) that allow the assistant to make REST API calls during conversations
2. **Specify GCP Region**: You can now specify the region for your [GCP Credentials](https://dashboard.vapi.ai/settings/integrations#:~:text=Save-,GCP%20credentials,-For%20storing%20the), This gives you control over where your call artifacts are stored.
3. **Transcriber Formatting Option**: A new `formatTurns` option in your [`Assembly AI Transcriber`](https://api.vapi.ai/api#:~:text=AssemblyAITranscriber) that lets you enable or disable formatting of transcripts when using AssemblyAI's Universal Streaming API. This helps you format transcript outputs to show speaker turns.
# June 16, 2025
# New Model Selection, Enhanced Edge Conditions, Simplified Credentials, and More
1. **New Model Selection in Workflows**: You can now specify the AI model used in workflows by setting the `model` property in workflow schemas. This allows choosing between OpenAI, Anthropic, Google, or custom models to better suit application requirements.
2. **Enhanced Workflow Edge Conditions**: Workflows now support [`Logic Edge Conditions`](https://api.vapi.ai/api#:~:text=LogicEdgeCondition) and [`Failed Edge Conditions`](https://api.vapi.ai/api#:~:text=FailedEdgeCondition) for edges. Specify logic edge conditions with [Liquid JS templates](https://liquidjs.com/) to enable more complex logic and error handling within workflows, allowing for dynamic and responsive workflow designs.
3. **Simplified Credential Configuration**: Your uploaded credentials are now automatically configured with the correct fallback index, simplifying the setup process with cloud providers.
4. **Updated End Reasons for ElevenLabs**: The following `endedReason` values been removed from `Call`:
* `pipeline-error-eleven-labs-503-server-error`
* `call.in-progress.error-providerfault-eleven-labs-503-server-error`
You should update your error handling code to reflect the current set of possible end reasons.
**Prompt Length Limitations**: The `globalPrompt` in workflows now has a maximum length of 5000 characters, and the `liquid` property in `LogicEdgeCondition` now has a maximum length of 1000 characters. Ensure prompts and conditions stay within these limits to prevent errors.
# June 15, 2025
# New Storage Credentials Providers
1. **New Storage Provider Credentials Added**: You can now use new credential types [`S3Credential`](https://api.vapi.ai/api#:~:text=S3Credential), [`GcpCredential`](https://api.vapi.ai/api#:~:text=GcpCredential), [`AzureCredential`](https://api.vapi.ai/api#:~:text=AzureCredential), [`SupabaseCredential`](https://api.vapi.ai/api#:~:text=SupabaseCredential), and [`CloudflareCredential`](https://api.vapi.ai/api#:~:text=CloudflareCredential) to integrate with various storage services. This expands your options for storing data seamlessly across different providers.
# June 14, 2025
# Access to `chat` Object in Server Messages
1. **Access to `chat` Object in Server Messages**: You can now access the `chat` object within various server messages, providing additional context about the conversation.
# June 13, 2025
# Background Speech Denoising, Cartesia Transcriber, Workflow Enhancements, and Call Error Handling
1. **Background Speech Denoising Plan**: You can now enhance call quality by configuring advanced background speech denoising options using the new [`assistant.backgroundSpeechDenoisingPlan.smartDenoisingPlan`](https://api.vapi.ai/api#:~:text=SessionPaginatedResponse-,Assistant,-AssistantPaginatedResponse) (default: `false`), which replaces the previous `backgroundDenoisingEnabled` setting.
Use the `SmartDenoisingPlan` to filter out background speech and noise using [Krisp technology](https://krisp.ai/).
Fine-tune noise reduction with the new `FourierDenoisingPlan` for more control over audio clarity.
Smart and Fourier denoising can be combined for optimal results. Order of precedence: Smart denoising, then Fourier denoising.
2. **Workflow Server Property**: Workflows now support a [`server`](https://api.vapi.ai/api#:~:text=TrieveKnowledgeBaseImport-,Workflow,-UpdateWorkflowDTO) property, allowing you to specify a server URL to receive webhook callbacks for workflow events directly.
3. **New Workflow Models**: You can now integrate Google's LLMs or custom models into your workflows by specifying [`Google`](https://api.vapi.ai/api#:~:text=WorkflowGoogleModel) or [`Custom LLM`](https://api.vapi.ai/api#:~:text=WorkflowCustomModel) in your workflow model settings. Select your model under [Model Settings](https://dashboard.vapi.ai/workflows#:~:text=Model%20Settings)
4. **Enhanced Error Reporting for Cartesia Services**: A new `endedReason` value `pipeline-error-cartesia-502-server-error` has been added to help you identify and handle specific errors related to Cartesia server issues.
5. **Enhanced Error Handling and Status Enums**: We've added new error enums and status codes to help you better handle and debug call-related issues:
* **VAPI Fault Errors**: Detect specific VAPI-related errors during call start using `call.start.error-vapifault-get-org` and `call.start.error-vapifault-get-subscription`
* **Subscription Status Errors**: Identify subscription-related issues with new enums:
* `call.start.error-subscription-frozen` (replaces `unknown-error`)
* `call.start.error-subscription-insufficient-credits`
* **Call Completion Statuses**: Track how calls are completed with new enums:
* `call.in-progress.twilio-completed-call`
* `call.in-progress.sip-completed-call`
* **In-Call Error Detection**: Handle specific errors during active calls using enums like `call.in-progress.error-vapifault-chat-pipeline-failed-to-start`
# June 11, 2025
# Assembly AI Transcriber Improvements, chat cost tracking, and API tool enhancements
1. **Chat Cost Tracking**: You can now access detailed cost information per [Chat](https://api.vapi.ai/api#:~:text=FunctionCall-,Chat,-CreateChatDTO) and [Call](https://api.vapi.ai/api#:~:text=SchedulePlan-,Call,-CallBatchError), including total and per-component breakdowns. Use `Call.cost` and `Chat.cost` to get the total cost, and `Call.costs` and `Chat.costs` to get the breakdown.\`
```json title="Chat Schema (excerpt)"
{
"cost": 0.12,
"costs": [
{ "type": "model", "cost": 0.22 },
{ "type": "chat", "cost": 0.10 },
]
}
```
2. **Enhanced AssemblyAI Transcriber Configuration**: You can now fine-tune the AssemblyAI transcriber with:
* `maxTurnSilence`: The maximum amount of silence in milliseconds before a turn is considered complete.
* `endOfTurnConfidenceThreshold`: The confidence threshold for determining the end of a turn.
* `minEndOfTurnSilenceWhenConfident`: The minimum amount of silence in milliseconds before a turn is considered complete when the confidence is high.
* `wordFinalizationMaxWaitTime`: The maximum amount of time in milliseconds to wait for word finalization.
3. **New Cartesia Transcriber Option**: You can now use the [Cartesia "Ink Whisper" transcriber](https://api.vapi.ai/api#:~:text=CartesiaTranscriber) for your for assistants and workflow nodes using `Assistant.transcriber` and `ConversationNode.transcriber`. Set this in your [Vapi Assistant dashboard today](https://dashboard.vapi.ai/assistants#:~:text=Transcriber).
4. **API Request Tool Variable Extraction**: You can now use [`assistant.model.tools[type=apiRequest].variableExtractionPlan`](https://api.vapi.ai/api#:~:text=VariableExtractionPlan) to extract and validate variables from API responses by defining a variable schema.
# June 9, 2025
# New Call End Reason `pipeline-error-eleven-labs-vapi-voice-disabled-by-owner`
Calls can now end with the reason `pipeline-error-eleven-labs-vapi-voice-disabled-by-owner`, indicating the Eleven Labs voice service is disabled by the owner.
This call ended reason are available to handle in [`Call`](https://api.vapi.ai/api#:~:text=Call), [`ServerMessageStatusUpdate`](https://api.vapi.ai/api#:~:text=ServerMessageStatusUpdate), and [`ServerMessageEndOfCallReport`](https://api.vapi.ai/api#:~:text=ServerMessageEndOfCallReport). You can update your application to handle this new end reason, ensuring proper notification and handling when this occurs.
# June 7, 2025
# New Ended Reasons for SIP Inbound Calls
You can now handle SIP inbound call failures with two new `endedReason` values:
* `call.ringing.sip-inbound-caller-hungup-before-call-connect`: Use this when a caller hangs up before the call connects
* `call.ringing.error-sip-inbound-call-failed-to-connect`: Use this when there's a connection error
These values are available in all call event schemas, including `Call`, `ServerMessageStatusUpdate`, and `ServerMessageEndOfCallReport`. Implement precise error handling for your SIP inbound calls by checking for these specific failure scenarios.
# June 6, 2025
# Workflows Out of Beta and Gladia Transcriptions
1. **Workflows Are Out of Beta**: You can now use workflows in production as we've removed all `[BETA]` labels from workflow-related properties and API endpoints. See [Workflow API Documentation](/docs/api/workflows) for complete details.
2. **Per-Call Workflow Customization with Overrides**: You can now customize workflows on a per-call basis using the new `Call.workflowOverrides` property. Override workflow settings and template variables using [LiquidJS syntax](https://liquidjs.com/tutorials/intro-to-liquid.html). See [Workflow Documentation](/docs/workflows) for details.
3. **Enhanced Gladia Transcriptions**: You can now transcribe audio in multiple languages using the new `languages` property in `GladiaTranscriber` and `FallbackGladiaTranscriber` (when `languageBehaviour` is `manual`). You can also use the new `solaria-1` transcription model for potentially improved results. Learn more in our [Transcription Documentation](/docs/transcription).
# June 4, 2025
## Assistant Configuration Updates
1. **Set Minimum Messages for Analysis**: Skip analysis for very short conversations by setting `Assistant.analysisPlan.minMessagesThreshold` (default: 2).
2. **Configure Transfer Timeout**: You can now set the timeout for warm transfer modes with `Assistant.hooks.do[type=transfer].destination.transferPlan.timeout` (default: 60). Warm transfer modes allow for a smooth handoff between agents by maintaining context and conversation history during the transfer process.
This timeout setting determines how long the system will wait for the transfer to complete before timing out.
3. **Enable AssemblyAI Universal Streaming API**: You can now enable the new Universal Streaming API for AssemblyAI transcribers with `Assistant.transcriber.enableUniversalStreamingApi` and `Assistant.transcriber.fallbackPlan.transcribers.enableUniversalStreamingApi`.
Set this to `true` to use AssemblyAI's new Universal Streaming API for improved transcription.
**Removal of regex in JsonSchema**: You can no longer use regular expressions in your [JSON schema validations](https://api.vapi.ai/api#:~:text=JsonSchema).
**Dot paths affected:**
* `assistant.analysisPlan.structuredDataPlan.schema.regex`
* `assistant.hooks.do[type=function].function.parameters.properties.regex`
* `assistant.model.tools[type=apiRequest].body.regex`
* `assistant.model.tools[type=apiRequest].headers.regex`
# June 3, 2025
# Azure OpenAI Compatibility Mode and JSON Schema Updates
1. **`toolStrictCompatibilityMode` for Azure OpenAI Models**: Added a new option to handle Azure OpenAI's validation limitations. Set `toolStrictCompatibilityMode` in your `OpenAIModel` config to either:
* `strip-parameters-with-unsupported-validation`: Removes entire parameters that have unsupported validations
* `strip-unsupported-validation`: Keeps parameters but removes unsupported validation aspects
Default is `strip-unsupported-validation`.
# May 31, 2025
# SIP Call Error Handling Updates
The following specific SIP error codes have been added to help identify call failures:
* `call.in-progress.error-sip-inbound-call-failed-to-connect`
* `call.in-progress.error-providerfault-outbound-sip-403-forbidden`
* `call.in-progress.error-providerfault-outbound-sip-407-proxy-authentication-required`
* `call.in-progress.error-providerfault-outbound-sip-503-service-unavailable`
* `call.in-progress.error-providerfault-outbound-sip-480-temporarily-unavailable`
* `call.in-progress.error-sip-outbound-call-failed-to-connect`
* `call.in-progress.error-vapifault-worker-died`
The generic error code `call.in-progress.error-sip-telephony-provider-failed-to-connect-call` has been removed. Update your error handling to use the new specific error codes instead.
# May 30, 2025
# Session and Workflow Enhancements
1. **Addition of `expirationSeconds` to Session Schemas**: You can now set custom session expiration times using the `expirationSeconds` property when creating or updating sessions. This allows sessions to expire anywhere between 1 minute and 30 days, providing greater control over session lifecycles.
2. **Introduction of `globalPrompt` in Workflow Schemas**: A new `globalPrompt` property allows you to define a default prompt for entire workflows. By setting a `globalPrompt` up to 5,000 characters, you can streamline your workflow configurations without setting prompts for each individual node.
# May 28, 2025
1. **Removal of `language` Property in Voice Settings**: The `language` property has been removed from the `VapiVoice` and `FallbackVapiVoice` configurations. You no longer need to set `language` when configuring voice settings; voice language may now be handled automatically or through a different configuration.
2. **Introduction of Detailed Node Artifacts**: A new `NodeArtifact` schema has been added, accessible via `call.artifact.nodes`, providing detailed information about each node in a call's workflow. You can now access messages, node names, and variables for each node to gain deeper insights into call executions.
3. **Addition of `nodes` and `variables` to Call Artifacts**:
The `Artifact` schema now includes `nodes` and `variables` properties, enhancing the data available in `call.artifact`. This allows you to retrieve the history of executed workflow nodes and the final state of variables after a call.
4. **Removal of `Metrics` Schema**: The `Metrics` schema has been completely removed. If your application relies on `Metrics`, you will need to update your code to accommodate this change and explore alternative solutions.
5. **Update Voice Configuration Paths**: With the changes to voice configurations, paths like `assistant.voice` and `call.squad.members.assistant.voice` may require updates. Ensure your configurations align with the new schema definitions and remove any references to the deprecated `language` property.
6. **Enable Recording in Artifacts**: To access call recordings in your artifacts, set `assistant.artifactPlan.recordingEnabled` in your configuration. This enables the `recording` property in `call.artifact`, allowing you to review call recordings for analysis or debugging.
# May 27, 2025
1. **New Chat and Session API Endpoints**: You can now manage chats and sessions using the new API endpoints `/chat`, `/chat/{id}`, `/chat/responses`, `/session`, and `/session/{id}`. This enables you to programmatically create, retrieve, and manage chat conversations and sessions within your applications.
2. **Variable Extraction Feature Removed**: The variable extraction functionality has been removed from the API. You'll need to update your workflows if you previously used variable extraction, as it is no longer supported.
3. **Specify Regions for OpenAI Models**: You can now specify the region for OpenAI models in `OpenAIModel` and `WorkflowOpenAIModel` by including a region in the `model` property, like `gpt-4.1-2025-04-14:westus`. This helps you comply with data residency rules or regional requirements by ensuring data processing occurs in specified locations.
4. **New OpenAI Models Added**: A range of new OpenAI models, including regional variants, are now available for use. You can choose these new models to better align with your application's performance needs and regional compliance requirements.
# May 26, 2025
**Removed `async` Property from Tool Schemas**: Developers no longer need to set the `async` property when using various tool schemas like `GhlTool`, `SmsTool`, `BashTool`, and others. These tools now operate synchronously by default; please update your code to remove any references to `async` in these schemas.
**Default Roles in Message Schemas**: The `role` property in `ToolMessage`, `AssistantMessage`, and `DeveloperMessage` now has default values of `"tool"`, `"assistant"`, and `"developer"`, respectively. You can omit the `role` field when creating these messages, simplifying message construction.
**Improved Descriptions for Chat Inputs and Messages**: The `input` and `messages` properties in the `Chat`, `CreateChatDTO`, and `OpenAIResponsesRequest` schemas now have clearer descriptions. This helps you understand that `input` can be a string or an array of chat messages, and `messages` provide context for multi-turn conversations.
**Clarified `async` Behavior in `FunctionTool`**: The `async` property's description in `FunctionTool` and related schemas has been updated for clarity. It now better explains how setting `async` to `true` or `false` affects the assistant's behavior, facilitating more effective use of this feature.
**Added Titles to Schema Definitions**: The `oneOf` definitions in the `input` property of `Chat`, `CreateChatDTO`, and `OpenAIResponsesRequest` now include `title` attributes like `"String"` and `"MessageArray"`. This improves schema documentation and assists tools in processing these definitions.
# May 25, 2025
1. **New `transferCompleteAudioUrl` Property in `TransferPlan`:** You can now specify a custom audio file URL using `transferCompleteAudioUrl` in `TransferPlan` when using `warm-transfer-experimental` mode to play a sound after the transfer is complete. This allows you to add a custom notification (like a beep) for the destination party after delivering the message or summary.
2. **`body` Parameter in `CreateApiRequestToolDTO` Is Now Optional:** The `body` property has been removed from the required fields in `CreateApiRequestToolDTO`, so you no longer need to include it when creating an API request tool. This means you can create API requests without a body, useful for HTTP methods like GET or DELETE.
# May 24, 2025
1. **New `minutesUsed` Property for Organizations**: Developers can now track the total call minutes used by their organization via the new `minutesUsed` property in the `Org` schema.
2. **Removed `server` Property from Certain Tools**: The `server` property has been removed from several tools, such as `SmsTool` and `DtmfTool`; developers should update their implementations accordingly.
3. **Updated `server` Property Description in Tools**: The `server` property's description has been updated in tools like `McpTool` and `BashTool` to clarify webhook behavior when tool calls are made.
4. **New Model `gemini-2.5-flash-preview-05-20` Available**: A new model `gemini-2.5-flash-preview-05-20` is now supported, allowing developers to utilize its features in their applications.
5. **Additional Subscription Types Added**: New subscription types—`agency`, `startup`, `growth`, and `scale`—are now available, providing more options to fit different organizational needs.
# May 23, 2025
1. **New Chat API Schemas Introduced**: The Chat API now features new schemas like `Chat` and `CreateChatDTO` for enhanced chat management, replacing older schemas. You can use these updated structures to create and interact with chats more effectively.
2. **Session Management Now Available**: Session-related schemas like `Session` and `CreateSessionDTO` have been added to support conversation sessions. This allows you to maintain context over multiple interactions and manage session-specific configurations.
Session-related schemas like `Session` and `CreateSessionDTO` have been added to support conversation sessions. This allows you to maintain context over multiple interactions and manage session-specific configurations.
3. **Additional Message Types for Enhanced Roles**: New message types `ToolMessage`, `AssistantMessage`, and `DeveloperMessage` enable representing different participants in a conversation. You can now handle messages from tools, assistants, and developers, enriching the dialogue experience.
4. **Updates to Tool Function Calls with `ToolCallFunction`**: The schema for tool calls has been updated with the introduction of `ToolCallFunction`. Adjust your implementations to use `ToolCallFunction`, noting that `arguments` are now passed as strings and `name` has a maximum length of 40 characters.
The schema for tool calls has been updated with the introduction of `ToolCallFunction`. Adjust your implementations to use `ToolCallFunction`, noting that `arguments` are now passed as strings and `name` has a maximum length of 40 characters.
5. **Updated Property Descriptions and Constraints**: Property descriptions have been clarified, and length constraints like `maxLength` have been added to certain fields. Ensure your data conforms to these updates, such as keeping `content` under 10,000 characters.
6. **Removal of Deprecated Schemas**: Deprecated schemas like `ChatCompletionsDTO` have been removed from the API. Update your code to use the new schemas to maintain compatibility and access the latest features.
# May 22, 2025
1. **New Anthropic Models Available**: Two new models, `claude-opus-4-20250514` and `claude-sonnet-4-20250514`, have been added to the `model` options in `AnthropicModel` and `WorkflowAnthropicModel`. You can now specify these models in your requests to take advantage of their features.
# May 20, 2025
1. **New API Request Tool (`apiRequest`):** Developers can now create custom API request tools using the `apiRequest` tool type, allowing assistants to make HTTP requests to specified URLs.
2. **'TextEditor' Tool Type Renamed:** The `type` value for the Text Editor tool has changed from `text-editor` to `textEditor`. Update your code to use `textEditor` when specifying this tool type.
3. **Enhanced Call Entry Points Descriptions:** The properties related to starting calls with assistants, squads, or workflows have updated descriptions, providing clearer guidance on how to use `assistant`, `assistantId`, `squad`, `squadId`, `workflow`, and `workflowId`.
4. **Extended Server Timeout Limit:** The maximum value for `timeoutSeconds` in server configurations has increased from 120 to 300 seconds, allowing server requests to take up to 5 minutes.
5. **Removal of `secret` Property in Server Schema:** The `secret` property has been removed from the `Server` schema. Adjust your server configurations by removing any references to `server.secret`.
6. **New Voice Option `Kylie`:** The voice ID `Kylie` is now available for use in `VapiVoice` and `FallbackVapiVoice`, providing an additional voice option for your assistants.
7. **Workflows in Server Message Responses:** You can now specify `workflow` and `workflowId` in `ServerMessageResponseAssistantRequest`, enabling the use of workflows when responding to server messages.
8. **`assistantId` No Longer Nullable:** The `assistantId` property in `ServerMessageResponseAssistantRequest` is no longer nullable, which may require you to always provide an `assistantId` or adjust your logic accordingly.
9. **Pattern Constraint on Variable Titles:** The `VariableExtractionSchema` now includes a regex pattern for `title`, restricting it to letters, numbers, and underscores. Ensure your variable titles conform to this pattern.
10. **Updated Server Property Descriptions:** Descriptions for `url`, `headers`, `backoffPlan`, and `timeoutSeconds` in the `Server` schema have been updated for clarity, helping you better understand their purposes and how to configure them.
# May 19, 2025
1. **Renaming `SmsSendTool` to `SmsTool`:** The tool previously known as `SmsSendTool` is now `SmsTool`. You can now use the new `SmsTool` schema to send SMS messages with enhanced configuration options like `async`, `server`, `function`, and `messages`.
2. **Update Text Editor Tool Type to `'text-editor'`:** The `type` for Text Editor tools has changed from `'textEditor'` to `'text-editor'`. Make sure to update your configurations to use `type`: `'text-editor'` when specifying a Text Editor tool.
3. **Removal of `backgroundSound.maxLength` Property:** The `maxLength` constraint has been removed from the `backgroundSound` property in Assistant schemas. You no longer need to limit the length of `backgroundSound`; it can now be of any length.
4. **Deprecation of `MakeTool`:** The `MakeTool` has been removed from the available tools in various model schemas. Please update your models to remove any references to `MakeTool` and use alternative tools as needed.
# May 18, 2025
1. **Introduction of New Workflow Nodes**: New nodes `ConversationNode`, `ToolNode`, and `HangupNode` have been added to simplify workflow design. You can now use these nodes to start conversations, integrate tools, and end calls in your workflows more efficiently.
2. **SesameVoice Added as a New Voice Option**: The `SesameVoice` provider is now available for assistant voices. You can configure your assistant's voice to use Sesame by setting `assistant.voice` to `SesameVoice`.
3. **Voice Schema Titles Updated for Clarity**: Voice provider schemas have updated titles, e.g., from `OpenAI` to `OpenAIVoice`. This helps avoid confusion by clearly indicating that these configurations are for voice settings.
4. **Enhancements to MonitorPlan Security Options**: New properties `listenAuthenticationEnabled` and `controlAuthenticationEnabled` have been added to `MonitorPlan`. You can now enforce authentication for live listening and controlling calls by enabling these options.
5. **Addition of New Tools for Workflow Integration**: New tools such as `BashTool`, `ComputerTool`, and `SmsSendTool` have been added. These allow your assistant to perform system commands, interact with computers, and send SMS messages within workflows.
6. **Deprecation of Voicemail Tool Type**: The `voicemail` tool type in `CreateVoicemailToolDTO` has been deprecated. You should transition to alternative methods for handling voicemails in your applications.
7. **Replacement of VoicemailTool with TextEditorTool**: References to `VoicemailTool` have been replaced with `TextEditorTool` in model configurations. Update your models to use `TextEditorTool` for text editing functionality.
8. **Simplification of Transfer Destination Options**: The `Step` destination type has been removed from `TransferCallTool` destinations. Use other destination types like `assistant` or `phoneNumber` when configuring call transfers.
9. **Introduction of Gemini Model in Google Platforms**: The model `gemini-2.5-pro-preview-05-06` is now available in `GoogleModel` and `KnowledgeBase`. You can select this model to utilize Google's latest AI capabilities in your assistant.
# May 17, 2025
1. **Introduction of `WorkflowAssistant` Schema in Workflows**: [`WorkflowAssistant`](https://api.vapi.ai/api#:~:text=WorkflowAssistant) now replaces `Assistant` in workflow definitions. Use `WorkflowAssistant` when defining assistant nodes in workflows moving forward.
2. **Adding `dataExtractionPlan` and `variableExtractionPlan` to Conversations**: You can now include [`dataExtractionPlan`](https://api.vapi.ai/api#:~:text=DataExtractionPlan) and [`variableExtractionPlan`](https://api.vapi.ai/api#:~:text=VariableExtractionPlan) to extract structured data or variables from user responses. Utilize these plans to define what data to extract during conversations in your workflows.
3. **New `McpTool` for Model Configuration**: You can now add `McpTool` to your assistant's `tools` array to use MCP (Model Control Protocol) tool calls. This tool allows your assistant to use any MCP-compatible server in your workflow.
4. **Changes to `ToolCallResult` Message Property**: The `message` property in `ToolCallResult` now accepts a single object instead of an array. Ensure that you return a single `ToolMessageComplete` or `ToolMessageFailed` object when providing messages in tool call results.
5. **Updated Required Properties in `Assistant` Schema**: [`Assistant`](https://api.vapi.ai/api#:~:text=Assistant) now requires `id`, `orgId`, `createdAt`, and `updatedAt` when creating or updating assistants. Make sure to provide these fields when creating or updating assistants.
`TransferDestinationStep` is now deprecated. Update your code to use the new method for specifying transfer destinations in the `transferCall` tool.
# May 16, 2025
# Strip Asterisks from Transcribed Text with `stripAsterisk` Formatter
1. **New `stripAsterisk` Formatter in [FormatPlan](https://api.vapi.ai/api#:~:text=FormatPlan)**: You can now remove asterisks from transcribed text by adding it to your `Assistant.voice[VOICE_PROVIDER].chunkPlan.formatPlan.formattersEnabled` configuration.
Ensure `Assistant.voice[VOICE_PROVIDER].chunkPlan.formatPlan.enabled` is set to `true` to use the `stripAsterisk` formatter.
# May 15, 2025
# New Azure OpenAI GPT 4.1 Models
1. **Access to New Azure OpenAI Models**: You can now use new GPT 4.1 models in Azure OpenAI such as `gpt-4.1-2025-04-14`, `gpt-4.1-mini-2025-04-14`, and `gpt-4.1-nano-2025-04-14`.
The above models will be available to configure through the console at a later date. For now, configure your assistant to use these models through
[the API](https://docs.vapi.ai/api-reference/assistants/update)
.
# May 14, 2025
1. **Specify Start Node in Workflows with `isStart` Property**: You can now explicitly define the starting point of your workflow by setting the `isStart` property to `true` on any node like [`Say`](https://api.vapi.ai/api#:~:text=Say), [`Gather`](https://api.vapi.ai/api#:~:text=Gather), or [`Hangup`](https://api.vapi.ai/api#:~:text=Hangup).
2. **Updated Model Options in `GroqModel`**: You can now use the following new Assistant modles with [Groq](https://api.vapi.ai/api#:~:text=GroqModel):
* `meta-llama/llama-4-maverick-17b-128e-instruct`
* `meta-llama/llama-4-scout-17b-16e-instruct`
* `mistral-saba-24b`
* `compound-beta`
* `compound-beta-mini`
Note that some older models have been removed, including
`llama-3.1-70b-versatile`
and
`mixtral-8x7b-32768`
.
3. **New `Kylie` Voice Available in Vapi**: You can now use the new `Kylie` voice when using [`Vapi` as your voice provider](https://dashboard.vapi.ai/assistants#:~:text=Voice%20Configuration). You can learn more in the [Vapi voices documentation](https://docs.vapi.ai/providers/voice/vapi-voicesn).
# May 13, 2025
# GoHighLevel Tools for Calendar and Contact Management
You can now use new [GoHighLevel tools](https://www.gohighlevel.com) in all models, templates, and workflows directly through the [`/tool`](https://api.vapi.ai/api#:~:text=/tool) and [`/tool/{id}`](https://api.vapi.ai/api#:~:text=/tool/%7Bid%7D) endpoints with the following capabilities:
* **Contact Management**:
* [GoHighLevelContactGetTool](https://api.vapi.ai/api#:~:text=GoHighLevelContactGetTool): Fetch contact information from GoHighLevel
* [GoHighLevelContactCreateTool](https://api.vapi.ai/api#:~:text=GoHighLevelContactCreateTool): Create new contacts in GoHighLevel
* **Calendar Management**:
* [GoHighLevelCalendarEventCreateTool](https://api.vapi.ai/api#:~:text=GoHighLevelCalendarEventCreateTool): Schedule new calendar events programmatically
* [GoHighLevelCalendarAvailabilityTool](https://api.vapi.ai/api#:~:text=GoHighLevelCalendarAvailabilityTool): Check calendar availability for scheduling
# May 10, 2025
1. **Configure Conversation Nodes with OpenAI Models**: You can now set up your assistant's workflow conversation nodes to use OpenAI models by specifying [`WorkflowOpenAIModel`](https://api.vapi.ai/api#:~:text=WorkflowOpenAIModel). Choose from a range of OpenAI models and customize parameters like `maxTokens` and `temperature` to control responses.
2. **Configure Conversation Nodes with Anthropic Models, Including *Thinking* Feature**: Your assistant's conversation nodes can now use Anthropic models by specifying [`WorkflowAnthropicModel`](https://api.vapi.ai/api#:~:text=WorkflowAnthropicModel). Select from various Anthropic models and, for `claude-3-7-sonnet-20250219`, enable the optional `thinking` feature for advanced reasoning capabilities.
# May 9, 2025
1. **Workflows Now Marked as Beta Features**: The workflow endpoints and related properties have now moved to **\[BETA]**, indicating they're slightly more stable but still in active development. Refer to the [Workflows documentation](https://docs.vapi.ai/workflows) and [API documentation](https://docs.vapi.ai/api-reference/calls/list#:~:text=Workflow) for more information.
2. **New `{{endedReason}}` Variable in Templates**: You can now include the `{{endedReason}}` variable in your post-call analysis templates to access why a call ended. This helps generate more insightful summaries and evaluations based on the call's outcome.
3. **Introduction of `SayAssistantHookAction` Schema**: A new action, [`SayAssistantHookAction`](https://api.vapi.ai/api#:~:text=SayAssistantHookAction), allows the assistant to say specific messages during calls. Use this by adding it to `call.squad.members.assistant.hooks.do[type=say]` to enhance call interactions.
# May 8, 2025
1. **New 'Conversation' Node in Workflows**: You can now use the **Conversation** node in your workflows to create conversation tasks, enhancing how assistants interact during calls.
2. **Integration with GoHighLevel via OAuth2 Credentials**: You can now connect with GoHighLevel services using new **GoHighLevelMCPCredential** credentials in the [Provider Keys](https://dashboard.vapi.ai/keys#:~:text=GoHighLevel) section of the Vapi Dashboard.
3. **Standardized Message Types for `clientMessages` and `serverMessages`**: When configuring assistants, you now specify [Client Messages](https://api.vapi.ai/api#:~:text=ClientMessage) and [Server Messages](https://api.vapi.ai/api#:~:text=ServerMessage) using predefined message types, ensuring consistency and preventing invalid message configurations.
# May 7, 2025
1. **`ClientMessage` Additions**: Several new client message schemas have been added with additional information about `call`, `customer`, `assistant`, `timestamp`, and `phoneNumber`. This includes:
* [`Client Message Tool Calls`](https://api.vapi.ai/api#:~:text=ClientMessageToolCalls)
* [`Client Message Transcript`](https://api.vapi.ai/api#:~:text=ClientMessageTranscript)
* [`Client Message Speech Update`](https://api.vapi.ai/api#:~:text=ClientMessageSpeechUpdate)
* [`Client Message Transfer Update`](https://api.vapi.ai/api#:~:text=ClientMessageTransferUpdate)
2. **New Hooks for Speech Interruption Events**: Two new hooks, [`Speech Interrupted Assistant Hook`](https://api.vapi.ai/api#:~:text=AssistantHookAssistantSpeechInterrupted) and [`Speech Interrupted Customer Hook`](https://api.vapi.ai/api#:~:text=AssistantHookCustomerSpeechInterrupted), enable you to define actions when speech is interrupted during a call.
3. **Call Schema Updates**: There are several notable updates to how `Call` is structured:
* `costs` array now includes a new cost type: [`KnowledgeBaseCost`](https://api.vapi.ai/api#:~:text=KnowledgeBaseCost)
* `phoneCallProvider` and `phoneCallProviderId` are now deprecated.
* `waitFunction` in `LivekitSmartEndpointingPlan` has been updated to improve how long the assistant waits before speaking, enhancing call flow responsiveness.
# May 6, 2025
1. **Use Workflows as Call Entry Points**: You can now start calls or configure phone numbers using a `workflow` or `workflowId`, just like you would with `assistant`, `assistantId`, `squad`, or `squadId`. This provides more flexibility in defining how calls are initiated and allows direct use of workflows. Refer to the [Workflows documentation](https://docs.vapi.ai/workflows) and [API documentation](https://docs.vapi.ai/api-reference/calls/list#:~:text=Workflow) for more information.
2. **New Warm Transfer Mode and Hold Music in `TransferPlan`**: There's a new transfer mode `warm-transfer-experimental` in `call.squad.members.assistant.hooks.do[type=transfer].destination.transferPlan`that enhances call transfer capabilities, including voicemail detection and customer hold experience. You can also customize the hold music by specifying a `holdAudioUrl`.
3. **Simplified `clientMessages` Configuration**: The `clientMessages` property has been updated and is now required in `AssistantOverrides`, `CreateAssistantDTO`, and `UpdateAssistantDTO`. This change simplifies how you specify which messages are sent to your Client SDKs.
# May 3, 2025
1. **New `KnowledgeBaseCost` in Call Costs:**: You can now access detailed costs related to knowledge base queries in a call through the new `KnowledgeBaseCost` type in `call.costs[type=knowledge-base]`. This helps in tracking expenses when using knowledge base features during calls.
2. **Deprecated `smartEndpointingEnabled` Property:** The `smartEndpointingEnabled` property in `StartSpeakingPlan` is now deprecated. Developers should update their applications to use the new `smartEndpointingPlan` or `customEndpointingRules` for controlling endpointing behavior.
3. **Advanced Endpointing with `smartEndpointingPlan` and `customEndpointingRules`:** The `StartSpeakingPlan` now includes `smartEndpointingPlan` and `customEndpointingRules` properties, providing enhanced control over speech endpointing. Developers can specify endpointing methods or define custom rules to improve conversational interactions.
The `smartEndpointingEnabled` property in `StartSpeakingPlan` is now deprecated. Developers should update their applications to use the new `smartEndpointingPlan` or `customEndpointingRules` for controlling endpointing behavior.
# May 1, 2025
1. **Customize Server Messages with Flexible Array Input**: Before, [`serverMessages`](https://api.vapi.ai/api#:~:text=ServerMessage) could only be one of a set list of string values (enforced by enum). Now, `serverMessages` is an array of objects with no restrictions on what those objects are as long as they match the [`ServerMessage`](https://api.vapi.ai/api#:~:text=ServerMessage) schema, making the schema more open and future-proof, though less strict.
We provide an example list that matches the previous values: `["conversation-update", "end-of-call-report", "function-call", "hang", "speech-update", "status-update", "tool-calls", "transfer-destination-request", "user-interrupted"]`.
You now need to include the `serverMessages` property when creating or updating an assistant, ensuring you explicitly define which messages your assistant sends to your server.
# April 30, 2025
1. **New Voicemail Detection Configuration**: You can now configure voicemail detection for assistants with Vapi using the new [`VapiVoicemailDetectionPlan`](https://api.vapi.ai/api#:~:text=VapiVoicemailDetectionPlan). This feature allows you to control how Vapi handles voicemail detection, including specifying the provider, backoff strategy, and maximum wait time for a voicemail beep. Refer to [Voicemail Detection documentation](https://docs.vapi.ai/calls/voicemail-detection) for more information, and configure it on the [Assistants tab](https://dashboard.vapi.ai/assistants#:~:text=Voicemail%20Detection).
2. **Control SMS Capabilities on Twilio Numbers**: You can now enable or disable SMS functionality on your Twilio phone numbers with the new `smsEnabled` property. By setting `smsEnabled` to `false`, Vapi will not update the messaging webhook URL during phone number import or creation, allowing you to manage SMS settings independently.
# April 29, 2025
1. **Simplified Assistant Schema**: The `Assistant` schema is now simplified to focus on essential properties like `assistantId`, `name`, `type`, and `metadata`. Other advanced settings have been moved to the Call schema.
Configure advanced call-specific assistant parameters using
`Call.assistant`
instead of
`Assistant`
.
2. **New Structured Recording Properties in Artifact Schema**: You can now access recording details through `Call.artifact.recording`, which provides a structured way to obtain mono, stereo, and video recordings. This replaces the old recording url properties with a more organized format. You can also access this data through the [dashboard (Observe > Call Logs)](https://dashboard.vapi.ai/calls)
The `Call.recordingUrl`, `Call.videoRecordingUrl`, `Call.stereoRecordingUrl`, and `Call.videoRecordingStartDelaySeconds` properties are now deprecated. Transition to using `Call.artifact.recording` for accessing recording information.
3. **Include SIP Headers in Refer-To URI for Transfers**: By enabling `sipHeadersInReferToEnabled` in your `Call.assistant.hooks.do[type=transfer].destination.transferPlan`, you can now include SIP headers as URL-encoded query parameters during call transfers.
4. **Increased Length Limits for Liquid and Rubric Fields**: You can now write longer [LiquidJS](https://liquidjs.com/) expressions in `LogicEdgeCondition.liquid` (up to 1000 characters) and more detailed rubrics in `TestSuiteRunScorerAI.rubric` and `TestSuiteTestScorerAI.rubric` (up to 10,000 characters). Refer to [Advanced Date and Time Formatting documentation](https://docs.vapi.ai/assistants/dynamic-variables#advanced-date-and-time-usage) for more information.
5. **Introduction of Start Node in Workflow**: A new [`Start`](https://api.vapi.ai/api#:~:text=Start) node type is available in the assistant's workflow. Use this to define the starting point of your assistant's conversational flow with customizable metadata. Refer to [Workflows documentation](https://docs.vapi.ai/workflows#step-4-build-your-workflow) for more information.
6. **Standardized Assistant Version Pagination Response**: When fetching assistant versions, responses now conform to the [`AssistantVersionPaginatedResponse`](https://api.vapi.ai/api#:~:text=AssistantVersionPaginatedResponse). This standardization makes it easier to handle paginated data.
# April 27, 2025
1. **New Assistant Hook for Call Ending Events**: You can now define actions to execute when a call is ending using [`Assistant.hooks\["AssistantHookCallEnding"\]`](https://api.vapi.ai/api#:~:text=AssistantHookCallEnding). This allows you to specify actions like transferring the call, saying a message, or invoking a function at the end of a call.
2. **Enhanced Voicemail Detection Configuration**: Configure voicemail detection more precisely with new `Assistant.voicemailDetection.backoffPlan` and `Assistant.voicemailDetection.beepMaxAwaitSeconds` properties. This lets you control retry strategies and set maximum wait times for voicemail beeps.
3. **Twilio Authentication Using API Keys**: Authenticate with Twilio using `apiKey` and `apiSecret` when importing a [Twilio Phone Number](https://dashboard.vapi.ai/phone-numbers/) This replaces the need for `authToken`.
4. **Support for New Voicemail Detection Provider and Model**: Utilize the new `vapi` provider for voicemail detection by configuring `Assistant.voicemailDetection.provider`. Additionally, the `gemini-2.5-flash-preview-04-17` model is now supported in various schemas for advanced capabilities.
5. **Expanded Workflow Nodes**: Workflows now support `Start` and `Assistant` nodes, enabling more complex and customizable call flow designs. This allows for greater flexibility in defining how calls are handled.
# April 26, 2025
1. **Adding metadata to ToolCallResult and ToolCallResultMessage**: You can now include optional metadata in tool call results and messages. This allows you to send additional context or information to clients alongside standard tool responses.
2. **Adding `tool.completed` client message type**: Assistants can now handle a new client message type, `tool.completed`. This enables you to notify clients when a tool has finished executing.
3. **Customizable assistant messages via `message` property in [ToolCallResult](https://api.vapi.ai/api#:~:text=ToolCallResult)**: You can now specify exact messages for the assistant to say upon tool completion or failure using the `message` property. This gives you greater control over user interactions by allowing custom, context-specific responses.
# April 25, 2025
1. **New OpenAI Models 'o3' and 'o4-mini' Added**: You can now use the '`o3`' and '`o4-mini`' models with OpenAI models in `Assistant.model["OpenAIModel"].model`.
2. **'whisper' Model Added to Deepgram Transcribers**: The '`whisper`' model is now available in [Deepgram transcriber](https://api.vapi.ai/api#:~:text=DeepgramTranscriber) models for audio transcription. Select '`whisper`' in the `Assistant.transcriber["DeepgramTranscriber"].model` property to utilize this advanced transcription model.
3. **Expanded Language Support in Deepgram Transcribers**: You can now transcribe audio in '`ar`' (Arabic), '`he`' (Hebrew), and '`ur`' (Urdu) when using Deepgram transcriber in your assistant.
# April 24, 2025
1. **Per-Voice Caching Control Added**: Developers can now enable or disable voice caching for each assistant's voice using the new `cachingEnabled` property in voice configurations. This allows you to optimize performance or comply with data policies by controlling whether voice responses are cached.
2. **'Condition' Value Now Accepts Strings**: When specifying conditions, the `value` property should now be provided as a string instead of an object. This simplifies condition definitions and makes it easier to set and interpret condition values.
# April 23, 2025
1. **Create Sesame Voices Programmatically**: You can now create and manage [Sesame Voices](https://api.vapi.ai/api#:~:text=CreateSesameVoiceDTO) via the API by specifying a `voiceName` and `transcription`.
2. **AWS STS Support in OAuth2 Authentication**: You can now use AWS Security Token Service for authentication by setting the `type` of `OAuth2AuthenticationPlan` to `'aws-sts'`, enabling integration with AWS's secure token services.
# April 18, 2025
1. **Idle Message Count Reset in `Assistant.messagePlan`**: You can now enable `Assistant.messagePlan.idleMessageResetCountOnUserSpeechEnabled` (default: false) to allow the idle message count to reset whenever the user speaks. This means the assistant can repeatedly remind an idle user throughout the conversation.
# April 17, 2025
\*\*1. **Custom Hooks When a Call is Ringing**: You can now define custom hooks on your phone numbers to automatically perform actions when a call is ringing. This enables you to play messages or transfer calls without additional server-side code by using the new `hooks` property in `Call.phoneNumber.hooks["phoneNumberHookCallRinging"]`.
\*\*2. **Say and Transfer Actions in Hooks**: The new [phone number hook call ringing](https://api.vapi.ai/api#:~:text=PhoneNumberHookCallRinging) allows you to specify actions that trigger when a call is ringing (`on: 'call.ringing'`). like [redirecting calls](https://api.vapi.ai/api#:~:text=TransferPhoneNumberHookAction) or [playing a message](https://api.vapi.ai/api#:~:text=SayPhoneNumberHookAction). Include these actions in the `do` array of your hook.
\*\*3. **Enhanced Call Tracking with endedReason**: When implementing call analytics, you can now track calls that ended due to hook actions through new `endedReason` values:
* `'call.ringing.hook-executed-say'`: Call ended after playing a message via hook
* `'call.ringing.hook-executed-transfer'`: Call ended after being transferred via hook
These values let you distinguish between different automated call handling outcomes in your reporting.
# April 16, 2025
1. **Assistant Overrides in Testing (`TargetPlan.assistantOverrides`)**: You can now apply `assistantOverrides` when testing an assistant with a [Target Plan](https://api.vapi.ai/api#:~:text=TargetPlan), allowing modifications to the assistant's configuration specifically for tests without changing the original assistant. This helps in testing different configurations or behaviors of an assistant without affecting the live version.
2. **Specify Voice Model with Deepgram**: You can now specify the `model` to be used by Deepgram voices by setting the `model` property to `"aura"` or `"aura-2"` (default: `"aura-2"`).
3. **Expanded Deepgram Voice Options (`voiceId` in `DeepgramVoice` and `FallbackDeepgramVoice`)**: The list of available deepgram voice options has been greatly expanded, providing a wider selection of voices for assistants. This allows you to customize the assistant's voice to better match your desired persona with `Assistant.voice["DeepgramVoice"].voiceId`.
4. **Control Text Replacement Behavior (`replaceAllEnabled` in `ExactReplacement`)**: A new property `replaceAllEnabled` allows you to decide whether to replace all instances of a specified text (`key`) or just the first occurrence in [`ExactReplacement`](https://api.vapi.ai/api#:~:text=ExactReplacement) configurations. Setting `replaceAllEnabled` to `true` ensures that all instances are replaced.
# April 15, 2025
1. **New GPT-4.1 Models Available**: You can now use `'gpt-4.1'`, `'gpt-4.1-mini'`, and `'gpt-4.1-nano'` as options for the `model` and `fallbackModels` with your [OpenAI models](https://api.vapi.ai/api#:~:text=OpenAIModel). These models may offer improved performance or features over previous versions.
# April 12, 2025
1. **Expanded Voice Selection for Assistant Voices**: You can now specify any valid `voiceId` for assistant voices without being limited to a predefined list. This provides greater flexibility to use different voices in `Assistant.voice`, and related configurations.
# April 11, 2025
1. **Updated AI Edge Condition with Prompt**: When defining an AI edge condition, the `matches` property has been renamed to `prompt`. The `prompt` allows you to provide a natural language condition (up to 1000 characters) that guides AI decision-making in workflows.
2. **Assistant Overrides per Customer**: You can now customize assistant settings for individual customers using `assistantOverrides` when [creating customers](https://api.vapi.ai/api#:~:text=CreateCustomerDTO). This enables personalized assistant interactions for each customer in batch calls.
3. **New Call Ended Reasons**: New error codes have been added to `endedReason` enums, providing more detailed insights into call terminations related to providers like Anthropic Bedrock and Vertex. This helps in better error handling and debugging of call issues.
# April 8, 2025
1. **Simplified `transport` property in `Call` configuration**: You should now configure the `transport` property in [`Call`](https://api.vapi.ai/api#:~:text=Call) as an object when creating or updating a [`Call`](https://api.vapi.ai/api#:~:text=Call), since the separate `Transport` schema has been deprecated. This simplification makes it easier to work with transport details without referencing a separate transport configuration.
The `Transport` schema is now deprecated and will be removed in a future release.
2. **New call type `vapi.websocketCall`**: You can now make [phone calls over WebSockets](https://docs.vapi.ai/calls/websocket-transport) with Vapi. The `Call` schema now supports a new `type` value: `vapi.websocketCall`.
# April 5, 2025
1. **Introducing `SmsSendTool` for SMS messaging support**: You can now create and send `sms` text messages using the new `[Send Text`]\([https://api.vapi.ai/api#:\~:text=SmsSendTool](https://api.vapi.ai/api#:~:text=SmsSendTool)) tool, enabling assistants to send SMS messages via defined servers.
2. **[Eleven Labs Voice](https://api.vapi.ai/api#:~:text=ElevenLabsVoice) Auto Mode and Confidence Threshold configuration options**: When using [`Eleven Labs Voice`](https://api.vapi.ai/api#:~:text=ElevenLabsVoice) in your Assistant, you can now configure `autoMode` (default: false) to automatically manage manage chunking strategies for long texts; Eleven Labs automatically determines the best way to process and generate audio, optimizing for latency and efficiency. Additionally, `confidenceThreshold` has been introduced in transcriber schemas, allowing developers to set thresholds to discard low-confidence transcriptions and improve accuracy.
3. **Changes to `CartesiaExperimentalControls` Speed property**: The `speed` property now accepts both predefined speeds (`'slowest'`, `'slow'`, `'normal'`, `'fast'`, `'fastest'`) and numeric values between -1 and 1. This simplifies the process of controlling the speed of the generated audio with Cartesia.
# April 4, 2025
1. **Addition of `assistantId` to `TargetPlan` settings**: You can now specify an `assistantId` when testing [target plans](https://api.vapi.ai/api#:~:text=TargetPlan), allowing you to test scenarios involving specific assistants directly.
# April 3, 2025
1. **Introducing `SmsSendTool` for SMS messaging support**: You can now create and manage tools of type `sms` using the new [SMS Send Tool](https://api.vapi.ai/api#:~:text=SmsSendTool), allowing you to send SMS messages via defined servers. The `sms` tool type is also now recognized in API endpoints, ensuring that SMS send tools are correctly processed during CRUD operations.
2. **New configuration options for voice and transcriber settings**: The `autoMode` property has been added to [Eleven Labs Voice Settings](https://api.vapi.ai/api#:~:text=ElevenLabsVoice), letting developers control automatic voice settings. Additionally, `confidenceThreshold` has been introduced in transcriber settings, allowing developers to set thresholds to discard low-confidence transcriptions and improve accuracy.
3. **Enhanced speed control in `CartesiaExperimentalControls`**: The `speed` property now accepts both predefined speeds (`'slowest'`, `'slow'`, `'normal'`, `'fast'`, `'fastest'`) and numeric values between -1 and 1. This gives you more precise control over speed settings for better customization.
# March 30, 2025
1. **TestSuiteRunTestAttempt now accepts `callId` and `metadata`**: You can now include a `callId` and `metadata` when creating a test suite run attempt, allowing you to reference calls by ID and attach session-related information.
2. **`call` property in [TestSuiteRunTestAttempt](https://api.vapi.ai/api#:~:text=TestSuiteRunTestAttemptMetadata) is no longer required**: It's now optional to include the full `call` object in a test attempt, providing flexibility for cases where call details are unnecessary or already known.
3. **Attach Metadata to Test Suite Run Attempts**: You can now attach [metadata](https://api.vapi.ai/api#:~:text=TestSuiteRunTestAttemptMetadata) like `sessionId` to test attempts for better tracking and analysis.
# March 28, 2025
1. **New Slack and Google Calendar Tools Added**: You can now use the built-in [Slack tool](https://docs.vapi.ai/tools/slack) to send messages and use the [Google Calendar tool](https://docs.vapi.ai/tools/google-calendar) to check calendar availability directly from your assistant, with full CRUD operations available via the [`/tool` API endpoint](https://docs.vapi.ai/api-reference/tools/list). You can authenticate the [Slack tool](https://dashboard.vapi.ai/keys#:~:text=Slack) and the [Google Calendar tool](https://dashboard.vapi.ai/keys#:~:text=Google%20Calendar) using OAuth2 from the [Vapi provider keys page](https://dashboard.vapi.ai/keys).
2. **Select LLM Model in Workflow Nodes**: You can now select and update which LLM model you want to use within workflow nodes, allowing more precise control over the assistant's behavior in different workflow nodes and easier configuration updates.
3. **Enhanced Call Monitoring and Reporting**: We've improved call monitoring with conversation turn tracking, millisecond-precision timestamps, and provided more detailed call end reasons. These enhancements make it easier to track conversation flow, perform precise time calculations, and diagnose specific call termination issues like server overloads or database errors.
4. **Enable Background Denoising**: You can now filter out background noise during calls by setting `Assistant.backgroundDenoisingEnabled` to `true`.
# March 27, 2025
1. **Batch Call Operations**: You can now place multiple calls to different customers at once by providing a list of `customer`s as an array in [`POST /call`](https://api.vapi.ai/api#/Calls/CallController_create).
2. **Google Sheets Row Append Tool Added**: You can now append rows to Google Sheets directly from your assistant using [`GoogleSheetsRowAppendTool`](https://api.vapi.ai/api#/Tools/GoogleSheetsRowAppendTool). This allows integration with Google Sheets via the API for automating data entry tasks.
3. **Call Control and Scheduling**: You can now schedule calls using the new `SchedulePlan` feature, specifying earliest and latest times for calls to occur. This gives you more control over call timing and scheduling.
4. **New Transcriber Options and Fallback Plans**: New transcribers like `GoogleTranscriber` and `OpenAITranscriber` have been added, along with the ability to set `fallbackPlan` for transcribers. This provides more choices and reliability for speech recognition in your applications.
# March 23, 2025
1. **Multi-Structured Data Extraction with `StructuredDataMultiPlan`:** You can now extract multiple sets of structured data from calls by configuring `assistant.analysisPlan.structuredDataMultiPlan`. This allows you to define various extraction plans, each producing structured outputs accessible via `call.analysis.structuredDataMulti`.
2. **Customizable Voice Speed and Language Settings:** You can now adjust the speech speed and language for your assistant's voice by using the new `speed` and `language` properties in `Assistant.voice`. This enables you to fine-tune the voice output to better match your user's preferences and localize the experience.
3. **Integration of OpenAI Transcriber:** The `transcriber` property in assistants now supports `OpenAITranscriber`, allowing you to utilize OpenAI's transcription services. A corresponding `Call.endedReason` value, `pipeline-error-openai-transcriber-failed`, has been added to help you identify when a call ends due to an OpenAI transcriber error.
# March 22, 2025
1. **Customizable Background Sound**: You can now use a custom audio file as the background sound in calls by providing a URL in the `backgroundSound` property. This allows you to enhance the call experience with personalized ambient sounds or music.
2. **New Recording Format Options in `ArtifactPlan`**: You can specify the recording format as either `'wav;l16'` or `'mp3'` in `Assistant.artifactPlan` or `Call.artifactPlan`. This gives you control over the audio format of call recordings to suit your storage and playback preferences.
3. **Integrate with Langfuse for Enhanced Observability**: You can now integrate with Langfuse by setting `assistant.observabilityPlan` to `langfuse`. Add `tags` and `metadata` to your traces to improve monitoring, categorization, and debugging of your application's behavior.
# March 21, 2025
1. **OpenAI Voice Enhancements**: When using [OpenAI Voice models in `Assistant.voice`](https://api.vapi.ai/api#:~:text=OpenAIVoice), you can now use specific text to speech models and add custom instructions to control your assistant's voice output
2. **Improved Call Error Reporting**: You can now use new [`Call.endedReason`](https://api.vapi.ai/api#:~:text=Call,-CallBatchError) codes when a call fails to start or ends unexpectedly due to failing to retrieve Vapi objects. Refer to [Call.endedReason](https://api.vapi.ai/api#:~:text=Call,-CallBatchError) for more details.
# March 20, 2025
# Introducing Google Calendar Integration, and Chat Test Suite / Rime AI Voice Enhancements
1. **Integration with Google Calendar**: You can now create and manage Google Calendar events directly within your tools. Configure OAuth2 credentials through the [dashboard > Build > Provider Keys](https://dashboard.vapi.ai/keys#:~:text=Google%20Calendar) to authenticate and interact with Google Calendar APIs.
2. **Enhanced Voice Customization for RimeAIVoice**: Gain more control over [Rime AI voice](https://api.vapi.ai/api#:~:text=RimeAIVoice) properties with new options like `reduceLatency`, `inlineSpeedAlpha`, `pauseBetweenBrackets`, and `phonemizeBetweenBrackets`. These settings let you optimize voice streaming and adjust speech delivery to better suit your assistant's needs.
3. **Chat Test Suite Enhancements**: You can now create and run chat-based tests in your test suites using the new [`TestSuiteTestChat`](https://api.vapi.ai/api#:~:text=TestSuiteTestChat) to more comprehensively test conversational interactions in your assistant.
4. **Maximum Length for Test Suite Chat Scripts**: When creating or updating chat tests, note that the `script` property now has a maximum length of 10,000 characters. Ensure your test scripts conform to this limit to avoid any validation errors.
# March 19, 2025
# Test Suite, Smart Endpointing, and Compliance Plans, Chat Completion Message Workflows, and Voicemail Detection
1. **Test Suite Enhancements**: Developers can now define `targetPlan` and `testerPlan` when creating or updating [test suites](https://api.vapi.ai/api#:~:text=TestSuite), allowing for customized testing configurations without importing phone numbers to Vapi.
2. **Smart Endpointing Updates**: You can now select between [`Vapi`](https://api.vapi.ai/api#:~:text=VapiSmartEndpointingPlan) and [`Livekit`](https://api.vapi.ai/api#:~:text=LivekitSmartEndpointingPlan) smart endpointing providers using the `Assistant.startSpeakingPlan.smartEndpointingPlan`; the `customEndpointingRules` property is deprecated and should no longer be used.
3. **Compliance Plan Enhancements**: Organizations can now specify compliance settings using the new `compliancePlan` property, enabling features like PCI compliance at the org level.
4. **Chat Completion Message Updates**: When working with OpenAI chat completions, you should now use [`ChatCompletionMessageWorkflows`](https://api.vapi.ai/api#:~:text=ChatCompletionMessageWorkflows) instead of the deprecated `ChatCompletionMessage`.
5. **Voicemail Detection Defaults Updated**: The default `voicemailExpectedDurationSeconds` for voicemail detection plans has increased from 15 to 25 seconds, affecting how voicemail detection timings are handled.
# March 17, 2025
# New `timeoutSeconds` Property in Custom LLM Model
1. **New `timeoutSeconds` Property in [`Custom LLM Model`](https://api.vapi.ai/api#:~:text=CustomLLMModel):** Developers can now specify a custom timeout duration (between 20 and 600 seconds) for connections to their [custom language model provider](https://api.vapi.ai/api#:~:text=CustomLLMModel) using the new `timeoutSeconds` property. This enhancement allows for better control over response waiting times, accommodating longer operations or varying network conditions.
# March 15, 2025
# Enhancements in Assistant Responses, New Gemini Model, and Call Handling
1. **Introduction of 'gemini-2.0-flash-lite' Model Option**: You can now use `gemini-2.0-flash-lite` in [`Assistant.model[provider="google"].model[model="gemini-2.0-flash-lite"]`](https://api.vapi.ai/api#:~:text=GoogleModel) for a reduced latency, lower cost Gemini model with a 1 million token context window.
2. **New Assistant Paginated Response**: All [`Assistant`](https://api.vapi.ai/api#:~:text=Assistants) endpoints now return paginated responses. Each response specifies `itemsPerPage`, `totalItems`, and `currentPage`, which you can use to navigate through a list of assistants.
# March 14, 2025
## Blocks Schema Deprecations, Scheduling Enhancements, and New Voice Options for Vapi Voice
2. **'scheduled' Status Added to Calls and Messages**: You can now set the status of a call or message to `scheduled`, allowing it to be executed at a future time. This enables scheduling functionality within your application for calls and messages.
3. **New Voice Options for Text-to-Speech**: Four new voices—`Neha`, `Cole`, `Harry`, and `Paige`—have been added for text-to-speech services. You can enhance user experience by setting the `voiceId` to one of these options in your configurations.
4. **Removal of Step and Block Schemas**:
Blocks and Steps are now officially deprecated. Developers should update their applications to adapt to these changes, possibly by using new or alternative schemas provided.
# March 13, 2025
## New Workflows API, Telnyx Phone Number Support, Voice Options, and much more
1. **Workflows Replace Blocks**: The API has migrated from blocks to workflows with new `/workflow` endpoints. [Introduction to Workflows](https://docs.vapi.ai/workflows)
You can now use [`UpdateWorkflowDTO`](https://api.vapi.ai/api#:~:text=UpdateWorkflowDTO) where conversation components (`Say`, `Gather`, `ApiRequest`, `Hangup`, `Transfer` nodes) are explicitly connected via edges to create directed conversation flows.
```json
{
"name": "Customer Support Workflow",
"nodes": [
{
"id": "greeting",
"type": "Say",
"text": "Hello, welcome to customer support. Do you need help with billing or technical issues?"
},
{
"id": "menu",
"type": "Gather",
"options": ["billing", "technical", "other"]
},
{
"id": "billing",
"type": "Say",
"text": "I'll connect you with our billing department."
},
{
"id": "technical",
"type": "Say",
"text": "I'll connect you with our technical support team."
},
{
"id": "transfer_billing",
"type": "Transfer",
"destination": {
"type": "number",
"number": "+1234567890"
}
},
{
"id": "transfer_technical",
"type": "Transfer",
"destination": {
"type": "number",
"number": "+1987654321"
}
}
],
"edges": [
{
"from": "greeting",
"to": "menu"
},
{
"from": "menu",
"to": "billing",
"condition": {
"type": "logic",
"liquid": "{% if input == 'billing' %} true {% endif %}"
}
},
{
"from": "menu",
"to": "technical",
"condition": {
"type": "logic",
"liquid": "{% if input == 'technical' %} true {% endif %}"
}
},
{
"from": "billing",
"to": "transfer_billing"
},
{
"from": "technical",
"to": "transfer_technical"
}
]
}
```
2. **Telnyx Phone Number Support**: Telnyx is now available as a phone number provider alongside Twilio and Vonage.
* Use the [`TelnyxPhoneNumber`](https://api.vapi.ai/api#:~:text=TelnyxPhoneNumber), [`CreateTelnyxPhoneNumberDTO`](https://api.vapi.ai/api#:~:text=CreateTelnyxPhoneNumberDTO), and [`UpdateTelnyxPhoneNumberDTO`](https://api.vapi.ai/api#:~:text=UpdateTelnyxPhoneNumberDTO) schemas with [`/phone-number`](https://api.vapi.ai/api#/Phone%20Numbers) endpoints to create and update Telnyx phone numbers.
* The `Call.phoneCallProviderId` now includes Telnyx's `callControlId` alongside Twilio's `callSid` and Vonage's `conversationUuid`.
3. **New Voice Options**:
* **Vapi Voices**: New Vapi voices - `Elliot`, `Rohan`, `Lily`, `Savannah`, and `Hana`
* **Hume Voice**: New provider with `octave` model and customizable voice settings
* **Neuphonic Voice**: New provider with `neu_hq` (higher quality) and `neu_fast` (faster) models
4. **New Cerebras Model**: [`CerebrasModel`](https://api.vapi.ai/api#:~:text=CerebrasModel) Supports `llama3.1-8b` and `llama-3.3-70b` models
5. **Enhanced Transcription**:
* **New Providers**: [ElevenLabs](https://api.vapi.ai/api#:~:text=ElevenLabsTranscriber) and [Speechmatics](https://api.vapi.ai/api#:~:text=SpeechmaticsTranscriber) transcribers now available.
* **DeepgramTranscriber Numerals**: New `numerals` option converts spoken numbers to digits (e.g., "nine-seven-two" → "972")
6. **Improved Voicemail Detection**: You can now use multiple provider implementations for `assistant.voicemailDetection` (Google, OpenAI, Twilio). OpenAI implementation allows configuring detection duration (5-60 seconds, default: 15).
7. **Smart Endpointing Upgrade**: Now supports LiveKit as an alternative to Vapi's custom-trained model in [`StartSpeakingPlan.smartEndpointingEnabled`](https://api.vapi.ai/api#:~:text=StartSpeakingPlan). LiveKit only supports English but may offer different endpointing characteristics.
8. **Observability with Langfuse**: New `assistant.observabilityPlan` property allows integration with Langfuse for tracing and monitoring of assistant calls. Configure with [LangfuseObservabilityPlan](https://api.vapi.ai/api#:~:text=LangfuseObservabilityPlan).
9. **More Credential Support**: Added support for Cerebras, Google, Hume, InflectionAI, Mistral, Trieve, and Neuphonic credentials in `assistant.credentials`
# March 9, 2025
## Enhanced Voicemail Detection, File Processing, Knowledge Base Integration, and Invoicing Updates
1. **Track Voicemail Detection Cost, Configure Google and Twilio Voicemail Detection Plans**
* You can now configure provider-specific settings and track voicemail detection costs through the new `VoicemailDetectionCost` schema at `call.costs[type=voicemail-detection]`.
* Configure Google or Twilio voicemail detection settings using the new [`GoogleVoicemailDetectionPlan`](https://api.vapi.ai/api#:~:text=GoogleVoicemailDetectionPlan) and [`TwilioVoicemailDetectionPlan`](https://api.vapi.ai/api#:~:text=TwilioVoicemailDetectionPlan) schemas.
```json
// Google configuration example
{
"provider": "google",
"voicemailExpectedDurationSeconds": 15 // Range: 5-60 seconds
}
```
```json
// Twilio configuration example
{
"provider": "twilio",
"enabled": true,
"machineDetectionTimeout": 30, // Range: 3-59 seconds
"voicemailDetectionTypes": ["machine_end_beep", "machine_end_silence"]
}
```
2. **Improved File Processing Statuses and Parsed Text Content**
* File processing statuses have been renamed to better reflect their purpose: `processing` → `done` → `failed`.
* Two new properties have been added to the [`File`](https://api.vapi.ai/api#:~:text=File) schema: `parsedTextUrl` and `parsedTextBytes`, providing direct access to parsed text content from processed files.
3. **Google Gemini Models for Knowledge Base Integration**
* The [`KnowledgeBase`](https://api.vapi.ai/api#:~:text=KnowledgeBase) schema now fully supports Google's Gemini models with specific model options.
* You can use Gemini models in your knowledge bases at `assistant.model.tools[type=query].knowledgeBases`.
```json
"model": {
"enum": [
"gemini-2.0-flash-thinking-exp",
"gemini-2.0-pro-exp-02-05",
"gemini-2.0-flash",
"gemini-2.0-flash-lite-preview-02-05",
"gemini-2.0-flash-exp",
"gemini-2.0-flash-realtime-exp",
"gemini-1.5-flash",
"gemini-1.5-flash-002",
"gemini-1.5-pro",
"gemini-1.5-pro-002",
"gemini-1.0-pro"
]
}
```
4. **New Invoicing Features**
* You can now use [`InvoicePlan`](https://api.vapi.ai/api#:~:text=InvoicePlan) schema for customizing invoice information with company details.
* This can be accessed via the new `invoicePlan` property on the [`Subscription`](https://api.vapi.ai/api#:~:text=Subscription) schema.
* Customize company name, email, tax ID, and address for your invoices.
5. **Additional Voice Options**
* Five new voice options have been added to the [`FallbackVapiVoice`](https://api.vapi.ai/api#:~:text=FallbackVapiVoice) schema: `Adi`, `Julia`, `Maibri (Web)`, `Maibri (Phone)`, and `Ashley`.
* Configure these voices in your assistant fallback plans at `assistant.voice.fallbackPlan.voices`.
# March 6, 2025
## New Query Tool and Vapi Voice Provider, Updates to Language Support and Error Handling
1. **New Query Tool Feature and Knowledge Base Integration**
* The API now supports a new query tool that allows assistants to search through knowledge bases. Add this tool to any assistant model by configuring it at `assistant.model.tools[type=query]` path.
* You can now link knowledge bases to query tools, providing structured information sources for assistants to access. Define knowledge bases with a name, model, provider, description, and associated file IDs.
```json
{
"type": "query",
"async": false,
"server": {
"url": "https://api.example.com/query-handler"
},
"function": {
"name": "query_knowledge",
"description": "Query knowledge bases for information",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The query to search for"
}
},
"required": ["query"]
}
},
"knowledgeBases": [
{
"name": "Product Documentation",
"model": "gemini-1.5-flash",
"provider": "google",
"description": "Contains all product manuals",
"fileIds": ["file-123", "file-456"]
}
]
}
```
2. **New Voice Provider Support**
A new voice provider "vapi" has been added with support for a voice called "Jordan" in [`FallbackVapiVoice`](https://api.vapi.ai/api#:~:text=FallbackVapiVoice). Configure it in our assistant fallback plans at `assistant.voice.fallbackPlan.voices`.
3. **Language Support Updates**
Myanmar language ("my") has been added to supported languages, while "jp" and "mymr" codes have been removed. Use "ja" for Japanese language and "my" for Myanmar. Reference [`GladiaTranscriber`](https://api.vapi.ai/api#:~:text=GladiaTranscriber) for more language codes.
4. **Error Handling Improvements**
Added new error code `pipeline-error-11labs-transcriber-failed` for `ServerMessageStatusUpdate.endedReason` and `ServerMessageEndOfCallReport.endedReason`. Also added an explicit `failed` status for test suite runs in [`TestSuiteRun`](https://api.vapi.ai/api#:~:text=TestSuiteRun). These additions provide more detailed error reporting.
5. **Azure OpenAI Model Update**
The model `gpt-4o-2024-08-06-ptu` has been removed from Azure OpenAI credential schemas. Update any credential configurations that were using this model.
# March 2, 2025
## Claude 3.7 Sonnet and GPT 4.5 preview, New Hume AI Voice Provider, New Supabase Storage Provider, Enhanced Call Transfer Options
1. **Claude 3.7 Sonnet with Thinking Configuration Support**:
You can now use the latest claude-3-7-sonnet-20250219 model with a new "thinking" feature via the [`AnthropicThinkingConfig`](https://api.vapi.ai/api#:~:text=AnthropicThinkingConfig) schema.
Configure it in `assistant.model` or `call.squad.members.assistant.model`:
```json
{
"model": "claude-3-7-sonnet-20250219",
"provider": "anthropic",
"thinking": {
"type": "enabled",
"budgetTokens": 5000 // min 1024, max 100000
}
}
```
2. **OpenAI GPT-4.5-Preview Support**:
You can now use the latest gpt-4.5-preview model as a primary model or fallback option via the [`OpenAIModel`](https://api.vapi.ai/api#:~:text=OpenAIModel) schema.
Configure it in `assistant.model` or `call.squad.members.assistant.model`:
```json
{
"model": "gpt-4.5-preview",
"provider": "openai"
}
```
3. **New Hume Voice Provider**:
Integrated Hume AI as a new voice provider with the "octave" model for text-to-speech synthesis.
4. **Supabase Storage Integration**:
New Supabase S3-compatible storage support for file operations. This integration lets developers configure buckets and paths across 16 regions, enabling structured file storage with proper authentication.
Configure [`SupabaseBucketPlan`](https://api.vapi.ai/api#:~:text=SupabaseBucketPlan) in `assistant.credentials.bucketPlan`,`call.squad.members.assistant.credentials.bucketPlan`
5. **Voice Speed Control**
Added a speed parameter to ElevenLabs voices ranging from 0.7 (slower) to 1.2 (faster) [`ElevenLabsVoice`](https://api.vapi.ai/api#:~:text=ElevenLabsVoice). This enhancement gives developers more control over speech cadence for more natural-sounding conversations.
6. **Enhanced Call Transfer Options in TransferPlan**
Added a new dial option to the sipVerb parameter for call transfers. This complements the existing refer (default) and bye options, providing more flexibility in call handling.
* 'dial': Uses SIP DIAL to transfer the call
7. **Zero-Value Minumum Subscription Minutes**
Changed the minimum value for minutesUsed and minutesIncluded from 1 to 0. This supports tracking of new subscriptions and free tiers with no included minutes.
8. **Zero-Value Minimum KeypadInputPlan Timeout**
Adjusted the KeypadInputPlan.timeoutSeconds minimum from 0.5 to 0.
# February 27, 2025
# Phone Keypad Input Support, OAuth2 and Analytics Improvements
1. **Keypad Input Support for Phone Calls:** A new [`keypadInputPlan`](https://api.vapi.ai/api#:~:text=KeypadInputPlan) feature has been added to enable handling of DTMF (touch-tone) keypad inputs during phone calls. This allows your voice assistant to collect numeric input from callers, like account numbers, menu selections, or confirmation codes.
Configuration options:
```json
{
"keypadInputPlan": {
"enabled": true, // Default: false
"delimiters": "#", // Options: "#", "*", or "" (empty string)
"timeoutSeconds": 2 // Range: 0.5-10 seconds, Default: 2
}
}
```
The feature can be configured in:
* `assistant.keypadInputPlan`
* `call.squad.members.assistant.keypadInputPlan`
* `call.squad.members.assistantOverrides.keypadInputPlan`
2. **OAuth2 Authentication Enhancement:** The [`OAuth2AuthenticationPlan`](https://api.vapi.ai/api#:~:text=OAuth2AuthenticationPlan) now includes a `scope` property to specify access scopes when authenticating. This allows more granular control over permissions when integrating with OAuth2-based services.
```json
{
"credentials": [
{
"authenticationPlan": {
"type": "oauth2",
"url": "https://example.com/oauth2/token",
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"scope": "read:data" // New property, max length: 1000 characters
}
}
]
}
```
The scope property can be configured at:
* `assistant.credentials.authenticationPlan`
* `call.squad.members.assistant.credentials.authenticationPlan`
3. **New Analytics Metric: Minutes Used** The [`AnalyticsOperation`](https://api.vapi.ai/api#:~:text=AnalyticsOperation) schema now includes a new column option: `minutesUsed`. This metric allows you to track and analyze the duration of calls in your usage reports and analytics dashboards.
4. **Removed TrieveKnowledgeBaseCreate Schema:** Removed `TrieveKnowledgeBaseCreate` schema from
* `TrieveKnowledgeBase.createPlan`
* `CreateTrieveKnowledgeBaseDTO.createPlan`
* `UpdateTrieveKnowledgeBaseDTO.createPlan`
# February 25, 2025
## Test Suite APIs, Enhanced Call Transfers, Voice Model Enhancements
1. **Introducing Test Suite Management APIs:** You can now test your assistant conversations before deploying them by creating [end-to-end tests](https://docs.vapi.ai/test/voice-testing#step-1-create-a-new-test-suite), [adding test cases](https://docs.vapi.ai/test/voice-testing#step-3-add-test-cases), and [running and reviewing test suites](https://docs.vapi.ai/test/voice-testing#step-5-run-and-review-tests). You can configure these tests through the [Test Suites dashboard page](https://dashboard.vapi.ai/test-suites) and [Test Suite APIs](https://docs.vapi.ai/api-reference/test-suites/test-suite-controller-find-all-paginated), and learn more in the [docs](https://docs.vapi.ai/test/voice-testing).
2. **Enhanced Call Transfers with TwiML Control:** You can now use `twiml` ([Twilio Markup Language](https://www.twilio.com/docs/voice/twiml)) in [`Assistant.model.tools[type=transferCall].destinations[].transferPlan[mode=warm-transfer-twiml]`](https://api.vapi.ai/api#:~:text=TransferPlan) to execute TwiML instructions before connecting the call, allowing for pre-transfer announcements or data collection with Twilio.
3. **New Voice Models and Experimental Controls:**
* **`mistv2` Rime AI Voice:** You can now use the `mistv2` model in [`Assistant.voice[provider="rime-ai"].model[model="mistv2"]`](https://api.vapi.ai/api#:~:text=RimeAIVoice).
* **OpenAI Models:** You can now use `chatgpt-4o-latest` model in [`Assistant.model[provider="openai"].model[model="chatgpt-4o-latest"]`](https://api.vapi.ai/api#:~:text=OpenAIModel).
4. **Experimental Controls for Cartesia Voices:** You can now specify your Cartesia voice speed (string) and emotional range (array) with [`Assistant.voice[provider="cartesia"].experimentalControls`](https://api.vapi.ai/api#:~:text=CartesiaExperimentalControls). For example:
```json
{
"speed": "fast",
"emotion": [
"anger:lowest",
"curiosity:high"
]
}
```
| Property | Option |
| -------- | ------------------ |
| speed | slowest |
| | slow |
| | normal (default) |
| | fast |
| | fastest |
| emotion | anger:lowest |
| | anger:low |
| | anger:high |
| | anger:highest |
| | positivity:lowest |
| | positivity:low |
| | positivity:high |
| | positivity:highest |
| | surprise:lowest |
| | surprise:low |
| | surprise:high |
| | surprise:highest |
| | sadness:lowest |
| | sadness:low |
| | sadness:high |
| | sadness:highest |
| | curiosity:lowest |
| | curiosity:low |
| | curiosity:high |
| | curiosity:highest |
# February 20, 2025
## What's New
1. **Configure 16 text normalization processors in [FormatPlan](https://api.vapi.ai/api#:~:text=FormatPlan)**: You can now control how text is transcribed and spoken for currency, dates, etc. by setting the `formattersEnabled` array in `Assistant.voice.chunkPlan.formatPlan` (not specifying `formattersEnabled` defaults to all formatters being enabled). See all available formatters in the [FormatPlan.formattersEnabled reference](https://api.vapi.ai/api#:~:text=FormatPlan).
2. **Deepgram [Keyterm Prompting](https://developers.deepgram.com/docs/keyterm)**: The `keyterm` array in [DeepgramTranscriber](https://api.vapi.ai/api#:~:text=DeepgramTranscriber) implements Deepgram's [Keyterm Prompting](https://developers.deepgram.com/docs/keyterm) technology, boosting recall for domain-specific terminology. Compared to the existing `keywords` field:
| Feature | `keywords` | `keyterm` |
| ------------ | ------------------ | -------------- |
| Recall Boost | 15-20% | Up to 90% |
| Format | Word:Weight | Raw phrases |
| Use Case | General vocabulary | Critical terms |
You should reserve `keyterm` for compliance-sensitive terms like medical codes while using `keywords` for proper nouns / brand names.
3. **Subscription usage tracking improvements**: The `minutesUsedNextResetAt` timestamp now appears in all subscription tiers (not just enterprise), exposed at `subscription.minutesUsedNextResetAt` for predictable billing cycle integration. Combine with existing `minutesUsed` and `minutesIncluded` metrics to build custom usage dashboards, regardless of subscription tier.
4. **Neuphonic voice synthesis**: You can now configure Neuphonic as a voice provider with `Assistant.voice[provider="neuphonic"]`. Handle appropriate errors with `pipeline-error-neuphonic-voice-failed`. Test latency thresholds as Neuphonic requires 200ms additional processing time compared to ElevenLabs.
5. **Support for pre-transfer announcements in [ClientInboundMessageTransfer](https://api.vapi.ai/api#:~:text=ClientInboundMessageTransfer)**: The `content` field in `ClientInboundMessageTransfer` now supports pre-transfer announcements ("Connecting you to billing...") before SIP/number routing. Implement via WebSocket messages using type: "transfer" with destination object.
### Deprecation Notice
**OrgWithOrgUser**
is now deprecated, and impacts endpoints returning organization-user composites. This has been replaced with separate
[`Org`](https://api.vapi.ai/api#:~:text=Org)
and
[`User`](https://api.vapi.ai/api#:~:text=User)
schemas for better clarity and consistency.
# February 17, 2025
## What's New
### Compliance & Security Enhancements
* **New [CompliancePlan](https://api.vapi.ai/api#:~:text=CompliancePlan) Consolidates HIPAA and PCI Compliance Settings**: You should now enable HIPAA and PCI compliance settings with `Assistant.compliancePlan.hipaaEnabled` and `Assistant.compliancePlan.pciEnabled` which both default to `false` (replacing the old HIPAA and PCI flags on `Assistant` and `AssistantOverrides`).
* **Phone Number Status Tracking**: You can now view your phone number `status` with `GET /phone-number/{id}` for all phone number types ([Bring Your Own Number](https://api.vapi.ai/api#:~:text=ByoPhoneNumber), [Vapi](https://api.vapi.ai/api#:~:text=VapiPhoneNumber), [Twilio](https://api.vapi.ai/api#:~:text=TwilioPhoneNumber), [Vonage](https://api.vapi.ai/api#:~:text=VonagePhoneNumber)) for better monitoring.
### Advanced Call Control
* **Assistant Hooks System**: You can now use [`AssistantHooks`](https://api.vapi.ai/api#:~:text=AssistantHooks) to support `call.ending` events with customizable filters and actions
* Enable transfer actions through [`TransferAssistantHookAction`](https://api.vapi.ai/api#:~:text=TransferAssistantHookAction). For example:
```javascript
{
"hooks": [{
"on": "call.ending",
"do": [{
"type": "transfer",
"destination": {
// Your transfer configuration
}
}]
}]
}
```
* Conditionally execute hooks with `Assistant.hooks.filter`. For example, trigger different hooks for call completed, system errors, or customer hangup / transfer:
```json
{
"assistant": {
"hooks": [{
"filters": [{
"type": "oneOf",
"key": "call.endedReason",
"oneOf": ["pipeline-error-custom-llm-500-server-error", "pipeline-error-custom-llm-llm-failed"]
}]
}
]
}
}
```
### Model & Voice Updates
* **New Models Added**: You can now use new models inside `Assistant.model[provider="google", "openai", "xai"]` and `Assistant.fallbackModels[provider="google", "openai", "xai"]`
* Google: Gemini 2.0 series (`flash-thinking-exp`, `pro-exp-02-05`, `flash`, `flash-lite-preview`)
* OpenAI: o3 mini `o3-mini`
* xAI: Grok 2 `grok-2`
* **New `PlayDialog` Model for [PlayHT Voices](https://api.vapi.ai/api#:~:text=PlayHTVoice)**: You can now use the `PlayDialog` model in `Assistant.voice[provider="playht"].model["PlayDialog"]`.
* **New `nova-3` and `nova-3-general` Models for [Deepgram Transcriber](https://api.vapi.ai/api#:~:text=DeepgramTranscriber)**: You can now use the `nova-3` and `nova-3-general` models in `Assistant.transcriber[provider="deepgram"].model["nova-3", "nova-3-general"]`
### API Improvements
* **Workflow Updates**: You can now send a [`workflow.node.started`](https://api.vapi.ai/api#:~:text=ClientMessageWorkflowNodeStarted) message to track the start of a workflow node for better call flow tracking
* **Analytics Enhancement**: Added subscription table and concurrency columns in [POST /analytics](https://api.vapi.ai/api#/Analytics/AnalyticsController_query) for richer queries about your subscriptions and concurrent calls.
### Deprecations
The
`/logs`
endpoints are now marked as deprecated - plan to update your implementation accordingly.
# February 10, 2025
# API Enhancements, Call Features, and Workflow Improvements
1. **`POST` requests to `/analytics` (migrate from `GET`)**: You should now make `POST` requests (instead of `GET`) to the [`/analytics`](https://api.vapi.ai/api#/Analytics/AnalyticsController_query) endpoint. Structure your analytics query as a JSON payload using [`AnalyticsQuery`](https://api.vapi.ai/api#/Analytics/AnalyticsQuery) in the request body.
2. **Use `SayHook` to Intercept and Modify Text for Assistant Speech**: You can use [`SayHook`](https://api.vapi.ai/api#/Hooks/SayHook) to intercept and modify text before it's spoken by your assistant. Specify the text to be spoken using the `exact` or `prompt` properties.
3. **Call Transfer Support**: The `Transfer` node type is now available in workflows. Configure the `destination` property to define the transfer target.
4. **Workflow Edge Condition Updates**: [`AIEdgeCondition`](https://api.vapi.ai/api#:~:text=AIEdgeCondition) (which replaces `SemanticEdgeCondition`) enables AI-powered routing decisions by analyzing conversation context and intent, while [`LogicEdgeCondition`](https://api.vapi.ai/api#:~:text=LogicEdgeCondition) (which replaces `ProgrammaticEdgeCondition`) allows for rule-based routing using custom logical expressions. The previous `SemanticEdgeCondition` and `ProgrammaticEdgeCondition` are now deprecated, and a new `FailedEdgeCondition` has been added to handle node failures in workflows.
5. **`Gather` Node: Data Collection Refactor**: The [`Gather` node](https://api.vapi.ai/api#:~:text=Gather) now requires an `output` property to define the expected data schema. The `instruction` and `schema` properties have been removed.
6. **Call Packet Capture (PCAP) Configuration**: Your call [`Artifact`](https://api.vapi.ai/api#:~:text=Artifact)s now support links to download a call's network packet capture (PCAP) file, providing you with detailed network traffic analysis and troubleshooting for calls. PCAP is only supported by `vapi` and `byo-phone-number` providers. Enable PCAP through `pcapEnabled`, automatically upload to S3 bucket with `pcapS3PathPrefix`, and access via `pcapUrl`.
7. **`ApiRequest` Node Improvements**: [`ApiRequest`](https://api.vapi.ai/api#:~:text=ApiRequest) now supports `GET` requests. You can also define the expected response schema. You can make API requests as `blocking` or run in the `background` with `ApiRequest.mode`.
8. **`Call` and `ServerMessage` `endedReason` Updates**: The `assistant-not-invalid` `Call.endedReason` has been corrected to `"assistant-not-valid"`. Also added `"assistant-ended-call-with-hangup-task"` to the `Call.endedReason`.
9. **New Azure OpenAI Model `gpt-4o-2024-08-06-ptu`**: You can now use `gpt-4o-2024-08-06-ptu` from Azure OpenAI inside your [Assistant](https://dashboard.vapi.ai/assistants/2ec63711-f867-4066-8c54-7833346783b1).
10. **Deprecated Schemas and Properties**: The following properties and schemas are now deprecated in the [API reference](https://api.vapi.ai/api/):
* `SemanticEdgeCondition`
* `ProgrammaticEdgeCondition`
* `Workflow.type`
* `ApiRequest.waitTaskMessage`
* `ApiRequest.startTaskMessage`
* `ApiRequest.failureTaskMessage`
* `ApiRequest.successTaskMessage`
* `OpenAIModel.semanticCachingEnabled`
* `CreateWorkflowDTO.type`
# February 4, 2025
# Hooks, PCI Compliance, and Blocking Messages
1. **Introduction of `Hook`s in Workflows**: You can now use [`Hooks`](https://api.vapi.ai/api#:~:text=Hook) in your workflows to automatically execute actions when specific events occur, like task start or confirmation. Hooks are now available in [`ApiRequest`](https://api.vapi.ai/api#:~:text=ApiRequest) and [`Gather`](https://api.vapi.ai/api#:~:text=Gather) workflow nodes.
2. **Make your Assistant PCI Compliant**: You can now configure [`Assistant.pciEnabled`](https://api.vapi.ai/api#:~:text=UpdateCallDTO-,Assistant,-UpdateAssistantDTO) to indicate if your assistant deals with sensitive cardholder data that requires PCI compliance, helping you meet security standards for financial information.
3. **Blocking Messages before Tool Calls**: You can now configure your tool calls to wait until a message is fully spoken before starting with [`ToolMessageStart.blocking=true`](https://api.vapi.ai/api#:~:text=ToolMessageStart) (default is `false`).
# February 1, 2025
# API Request Node, Improved Retries, and Enhanced Message Controls
1. **HttpRequest Node Renamed to ApiRequest**: The `HttpRequest` workflow node has been renamed to [`ApiRequest`](https://api.vapi.ai/api#:~:text=ApiRequest), and can be accessed through `Assistant.model.workflow.nodes[type="api-request"]`. Key changes:
* New support for POST requests with customizable headers and body
* New async request support with `isAsync` flag
* Task status messages for waiting, starting, failure and success states
The `HttpRequest` node is now deprecated and will be removed in a future release. Please migrate to the new `ApiRequest` node.
2. **New Backoff and Retry Controls**: You can now configure [`Assistant.model.tools[type=dtmf].server.backoffPlan`](https://api.vapi.ai/api#:~:text=BackoffPlan) to handle failed requests with customizable retry strategies and delays.
* Supports fixed or exponential backoff strategies
* Configure `maxRetries` (up to 10) and `baseDelaySeconds` (up to 10 seconds)
* Available in server configurations via `backoffPlan` property
3. **Enhanced Gather Node**: The [`Assistant.model.workflow.nodes[type=gather]`](https://api.vapi.ai/api#:~:text=Gather) node has been improved with the following changes:
* Added `maxRetries` property to control retry attempts
* Now accepts a single JsonSchema instead of an array
* Removed default value for `confirmContent` property
4. **Improved Message Controls**: [`Assistant.messagePlan`](https://api.vapi.ai/api#:~:text=MessagePlan) has been improved with the following changes:
* Increased `idleTimeoutSeconds` maximum from 30 to 60 seconds
* Added `silenceTimeoutMessage` to customize call ending due to silence
5. **New Distilled Deepseek Model with Groq**: You can now select `deepseek-r1-distill-llama-70b` when using [Groq](https://api.vapi.ai/api#:~:text=Groq) as the provider in [`Assistant.model[provider='groq']`](https://api.vapi.ai/api#:~:text=UpdateCallDTO-,Assistant,-UpdateAssistantDTO)
6. **Edge Condition Updates**: Edge conditions now require explicit matching criteria to improve workflow control and readability. Semantic edges must specify a `matches` property while programmatic edges require a `booleanExpression` property to define transition logic.
# January 29, 2025
# New workflow nodes, improved call handling, better phone number management, and expanded tool calling capabilities
1. **New Hangup Workflow Node**: You can now include a [`Hangup`](https://api.vapi.ai/api#:~:text=Hangup) node in your workflows to end calls programmatically.
2. **New HttpRequest Workflow Node**: Workflows can now make HTTP requests using the new [`HttpRequest`](https://api.vapi.ai/api#:~:text=HttpRequest) node, enabling integration with external APIs during workflow execution.
3. **Updates to Tool Calls**: The [`ToolCall`](https://api.vapi.ai/api#:~:text=ToolCall) schema has been revamped; you should update your tool calls to use the new `function` property with `id` and `function` details (instead of older `tool` and `toolBody` properties).
4. **Improvements to [Say](https://api.vapi.ai/api#:~:text=Say), [Edge](https://api.vapi.ai/api#:~:text=Edge), [Gather](https://api.vapi.ai/api#:~:text=Gather), and [Workflow](https://api.vapi.ai/api#:~:text=Workflow) Nodes**:
* The `name`, `to`, and `from` properties in these nodes now support up to 80 characters, letting you use more descriptive identifiers.
* A `metadata` property has been added to these nodes, allowing you to store additional information.
* The [`Gather`](https://api.vapi.ai/api#:~:text=Gather) node now supports a `confirmContent` option to confirm collected data with users.
5. **Regex Validation with Json Outputs**: You can now validate inputs and outputs from your conversations, tool calls, and OpenAI structured outputs against regular expressions using the `regex` property in [`JSON outputs`](https://api.vapi.ai/api#:~:text=JsonSchema) node.
6. **New Assistant Transfer Mode**: A new [transfer mode](https://api.vapi.ai/api#:~:text=TransferPlan) `swap-system-message-in-history-and-remove-transfer-tool-messages` allows more control over conversation history during assistant transfers.
7. **Area Code Selection for Vapi Phone Numbers**: You can now specify a desired area code when creating Vapi phone numbers using `numberDesiredAreaCode`.
8. **Chat Completions Support**: You can now handle chat messages and their metadata within your applications using familiar chat completion messages in your workflow nodes.
# January 22, 2025
# Tool Calling Updates, Final Transcripts, and DeepSeek Reasoner
1. **Migrate `ToolCallFunction` to `ToolCall`**: You should update your client and server tool calling code to use the [`ToolCall` schema](https://api.vapi.ai/api#:~:text=ToolCall) instead of `ToolCallFunction`, which includes properties like `name`, `tool`, and `toolBody` for more detailed tool call specifications. ToolCallFunction has been removed.
2. **Include `ToolCall` Nodes in Workflows**: You can now incorporate [`ToolCall` nodes](https://api.vapi.ai/api#:~:text=ToolCall) directly into workflow block steps, enabling tools to be invoked as part of the workflow execution.
3. **New Model Option `deepseek-reasoner`**: You can now select `deepseek-reasoner` as a model option inside your assistants with `Assistant.model["deep-seek"].model["deepseek-reasoner"]`, offering enhanced reasoning capabilities for your applications.
4. **Support for Final Transcripts in Server Messages**: The API now supports `'transcript[transcriptType="final"]'` in server messages, allowing your application to handle and process end of conversation transcripts.
# January 21, 2025
# Updated Azure Regions for Credentials
1. **Updated Azure Regions for Credentials**: You can now specify `canadacentral`, `japaneast`, and `japanwest` as valid regions when specifying your Azure credentials. Additionally, the region `canada` has been renamed to `canadaeast`, and `japan` has been replaced with `japaneast` and `japanwest`; please update your configurations accordingly.
# January 20, 2025
# Workflow Steps, Trieve Knowledge Base Updates, and Concurrent Calls Tracking
1. **Use Workflow Blocks to Simplify Blocks Steps:** You can now compose complicated Blocks steps with smaller, resuable [Workflow blocks](https://api.vapi.ai/api#:~:text=Workflow) that manage conversations and take actions in external systems.
In addition to normal operations inside [Block steps](https://docs.vapi.ai/blocks/steps) - you can now [Say messages](https://api.vapi.ai/api#:~:text=Say), [Gather information](https://api.vapi.ai/api#:~:text=Gather), or connect to other workflow [Edges](https://api.vapi.ai/api#:~:text=Edge) based on a [LLM evaluating a condition](https://api.vapi.ai/api#:~:text=SemanticEdgeCondition), or a more [logic-based condition](https://api.vapi.ai/api#:~:text=ProgrammaticEdgeCondition). Workflows can be used through `Assistant.model["VapiModel"]` to create custom call workflows.
2. **Trieve Knowledge Base Integration Improvements:** You should now configure [Trieve knowledge bases](https://api.vapi.ai/api#:~:text=TrieveKnowledgeBase) using the new `createPlan` and `searchPlan` fields instead of specifying the raw vector plans directly. The new plans allow you to create or import trieve plans directly, and specify the type of search more precisely than before.
3. **Updated Concurrency Tracking:** Your subscriptions now track active calls with `concurrencyCounter`, replacing `concurrencyLimit`. This does not affect how you reserve concurrent calls through [billing add-ons](https://dashboard.vapi.ai/org/billing/add-ons).
4. **Define Allowed Values with `type` using `JsonSchema`:** You can restrict model outputs to specific values inside Blocks or tool calls using the new `type` property in [JsonSchema](https://api.vapi.ai/api#:~:text=JsonSchema). Supported types include `string`, `number`, `integer`, `boolean`, `array` (which also needs `items` to be defined), and `object` (which also needs `properties` to be defined).
# January 15, 2025
1. **Updated Log Endpoints:**
Both the `GET /logs` and `DELETE /logs` endpoints have been simplified by removing the `orgId` parameter.
2. **Updated Log Schema:**
The following fields in the Log schema are no longer required: `requestDurationSeconds`, `requestStartedAt`, `requestFinishedAt`, `requestBody`, `requestHttpMethod`, `requestUrl`, `requestPath`, and `responseHttpCode`.
# January 14, 2025
**End Call Message Support in ClientInboundMessage**: Developers can now programmatically end a call by sending an `end-call` message type within `ClientInboundMessage`. To use this feature, include a message with the `type` property set to `"end-call"` when sending inbound messages to the client.
# January 11, 2025
1. **Integration of Smallest AI Voices**: Assistants can now utilize voices from Smallest AI by setting the voice provider to `Assistant.voice[provider="smallest-ai"]`, allowing selection from a variety of 25 preset voices and customization of voice attributes.
2. **Support for DeepSeek Language Models**: Developers can now configure assistants to use DeepSeek LLMs by setting the `Assistant.model[provider="deep-seek"]` and `Assistant.model[model="deepseek-chat"]`. You can also specify custom credentials by passing the following payload:
```json
{
"credentials": [
{
"provider": "deep-seek",
"apiKey": "YOUR_API_KEY",
"name": "YOUR_CREDENTIAL_NAME"
}
],
"model": {
"provider": "deep-seek",
"model": "deepseek-chat"
}
}
```
3. **Additional Call Ended Reasons for DeepSeek and Cerebras**: New `Call.endedReason` have been added to handle specific DeepSeek and Cerebras call termination scenarios, allowing developers to better manage error handling.
4. **New API Endpoint to Delete Logs**: A new `DELETE /logs` endpoint has been added, enabling developers to programmatically delete logs and manage log data.
5. **Enhanced Call Transfer Options with SIP Verb**: You can now specify a `sipVerb` when defining a `TransferPlan` with `Assistant.model.tools[type=transferCall].destinations[type=sip].transferPlan` giving you the ability to specify the SIP verb (`refer` or `bye`) used during call transfers for greater control over call flow.
6. **Azure Credentials and Blob Storage Support**: You can now configure Azure credentials with support for AzureCredential.service\[service=blob\_storage] service and use AzureBlobStorageBucketPlan withAzureCredential.bucketPlan, enabling you to store call artifacts directly in Azure Blob Storage.
7. **Add Authentication Support for Azure OpenAI API Management with the 'Ocp-Apim-Subscription-Key' Header**: When configuring Azure OpenAI credentials, you can now include the AzureOpenAICredential.ocpApimSubscriptionKey to authenticate with Azure's OpenAI services for the API Management proxy in place of an API Key.
8. **New CloudflareR2BucketPlan**: You can now use CloudflareR2BucketPlan to configure storage with Cloudflare R2 buckets, enabling you to store call artifacts directly.
9. **Enhanced Credential Support**: It is now simpler to configure provider credentials in `Assistant.credentials`. Additionally, credentials can be overridden with `AssistantOverride.credentials` enables granular credential management per assistant. Our backend improvements add type safety and autocompletion for all supported credential types in the SDKs, making it easier to configure and maintain credentials for the following providers:
* S3Credential
* GcpCredential
* XAiCredential
* GroqCredential
* LmntCredential
* MakeCredential
* AzureCredential
* TavusCredential
* GladiaCredential
* GoogleCredential
* OpenAICredential
* PlayHTCredential
* RimeAICredential
* RunpodCredential
* TrieveCredential
* TwilioCredential
* VonageCredential
* WebhookCredential
* AnyscaleCredential
* CartesiaCredential
* DeepgramCredential
* LangfuseCredential
* CerebrasCredential
* DeepSeekCredential
* AnthropicCredential
* CustomLLMCredential
* DeepInfraCredential
* SmallestAICredential
* AssemblyAICredential
* CloudflareCredential
* ElevenLabsCredential
* OpenRouterCredential
* TogetherAICredential
* AzureOpenAICredential
* ByoSipTrunkCredential
* GoHighLevelCredential
* InflectionAICredential
* PerplexityAICredential
10. **Specify Type When Updating Tools, Blocks, Phone Numbers, and Knowledge Bases**: You should now specify the type in the request body when [updating tools](https://api.vapi.ai/api#/Tools/ToolController_update), [blocks](https://api.vapi.ai/api#/Blocks/BlockController_update), [phone numbers](https://api.vapi.ai/api#/Phone%20Numbers/PhoneNumberController_update), or [knowledge bases](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_update) using the appropriate payload for each type. Specifying the type now provides type safety and autocompletion in the SDKs. Refer to [the schemas](https://api.vapi.ai/api) to see the expected payload for the following types:
* UpdateBashToolDTO
* UpdateComputerToolDTO
* UpdateDtmfToolDTO
* UpdateEndCallToolDTO
* UpdateFunctionToolDTO
* UpdateGhlToolDTO
* UpdateMakeToolDTO
* UpdateOutputToolDTO
* UpdateTextEditorToolDTO
* UpdateTransferCallToolDTO
* BashToolWithToolCall
* ComputerToolWithToolCall
* TextEditorToolWithToolCall
* UpdateToolCallBlockDTO
* UpdateWorkflowBlockDTO
* UpdateConversationBlockDTO
* UpdateByoPhoneNumberDTO
* UpdateTwilioPhoneNumberDTO
* UpdateVonagePhoneNumberDTO
* UpdateVapiPhoneNumberDTO
* UpdateCustomKnowledgeBaseDTO
* UpdateTrieveKnowledgeBaseDTO
# January 7, 2025
# New Gemini 2.0 Models, Realtime Updates, and Configuration Options
1. **New Gemini 2.0 Models**: You can now use two new models in `Assistant.model[model='GoogleModel']`: `gemini-2.0-flash-exp` and `gemini-2.0-flash-realtime-exp`, which give you access to the latest real-time capabilities and experimental features.
2. **Support for Real-time Configuration with Gemini 2.0 Models**: Developers can now fine-tune real-time settings for the Gemini 2.0 Multimodal Live API using `Assistant.model[model='GoogleModel'].realtimeConfig`, enabling more control over text generation and speech output.
3. **Customize Speech Output for Gemini Multimodal Live APIs**: You can now customize the assistant's voice using the `speechConfig` and `voiceConfig` properties, with options like `"Puck"`, `"Charon"`, and more.
4. **Advanced Gemini Text Generation Parameters**: You can also tune advanced hyperparameters such as `topK`, `topP`, `presencePenalty`, and `frequencyPenalty` to control how the assistant generates responses, leading to more natural and dynamic conversations.
# January 5, 2025
1. **New Transfer Plan Mode Added**: You can now include call summaries in the SIP header during blind transfers without assistant involvement with `blind-transfer-add-summary-to-sip-header` (a new `TransferPlan.mode` option). Doing so will make `ServerMessageStatusUpdate` include a `summary` when the call status is `forwarding` - which means you can access call summaries for real-time display or logging purposes in your SIP calls.
2. **Azure Speech Transcription Support**: You can now specify a new property called `AzureSpeechTranscriber.language` in Azure's Speech-to-Text service to improve the accuracy of processing spoken input.
3. **New Groq Model Available**: You can now use `'llama-3.3-70b-versatile'` in `GroqModel.model`.
# December 30, 2024
1. **Addition of *AzureSpeechTranscriber*:**
You can now configure assistants to use Azure's speech transcription service by setting
`AzureSpeechTranscriber.provider` to `azure`. Additionally, you will receive azure transcriber errors like `pipeline-error-azure-speech-transcriber-failed` in `Call.endReason`, `ServerMessageEndOfCallReport.endReason`, and `ServerMessageStatusUpdate.endReason`.
2. **Combined `serverUrl` and `serverUrlSecret` into `server` Property**:
The `serverUrl` and `serverUrlSecret` properties have been replaced by a new `server` property in multiple schemas. This lets you configure webhook endpoints using the `server` object, allowing for more detailed and flexible setup, including URL and authentication, in a single place. These schemas include:
* ByoPhoneNumber
* BuyPhoneNumberDTO
* CreateByoPhoneNumberDTO
* CreateOrgDTO
* CreateTwilioPhoneNumberDTO
* CreateVapiPhoneNumberDTO
* CreateVonagePhoneNumberDTO
* ImportTwilioPhoneNumberDTO
* ImportVonagePhoneNumberDTO
* Org
* OrgWithOrgUser
* TwilioPhoneNumber
* UpdateOrgDTO
* UpdatePhoneNumberDTO
* VapiPhoneNumber
* VonagePhoneNumber
3. **Introduction of New OpenAI Models**:
You can now use `o1-preview`, `o1-preview-2024-09-12`, `o1-mini`, and `o1-mini-2024-09-12`. in `OpenAIModel.model`.
4. **Introduction of *'sonic' Voice Models* in Voice Schemas:**
You can now use `sonic` and `sonic-preview` models in `CartesiaVoice.model` and `FallbackCartesiaVoice.model` configurations.
5. **Removal of Deprecated *GroqModel* Models:**
The models `llama3-groq-8b-8192-tool-use-preview` and `llama3-groq-70b-8192-tool-use-preview` have been removed from `GroqModel.model`. You should switch to supported models to avoid any disruptions.
# December 21, 2024
**Expanded Voice Compatibility with Realtime Models**: You can use the voices ash, ballad, coral, sage, and verse with any realtime models, giving you more flexibility in voice synthesis options.
**Access to New OpenAI Models**:
You can now specify the new models `gpt-4o-realtime-preview-2024-12-17` and `gpt-4o-mini-realtime-preview-2024-12-17` when configuring `OpenAIModel.model` and `OpenAIModel.fallbackModels`.
**New ElevenLabs Voice Models Available**:
The new voice models `eleven_flash_v2` and `eleven_flash_v2_5` are now available for use in `ElevenLabsVoice` and `FallbackElevenLabsVoice`, offering potential improvements in voice performance.
# December 19, 2024
1. **Azure Region Renamed to `swedencentral` (from *sweden*)**: Azure Speech Services customers using the Sweden data center should now specify `swedencentral` as your Azure Speech Services region instead of `sweden`. Update your region in your code and the updated [provider keys page](https://dashboard.vapi.ai/keys) > *Azure Speech*.
# December 14, 2024
1. **Removal of `'gemma-7b-it'` from `GroqModel` Options:** The `'gemma-7b-it'` model is no longer available when selecting Groq as a model provider. Update your applications to use other valid options provided by the API.
Refer to the [`GroqModel` schema](https://api.vapi.ai/api) or the [vapi dashboard](https://dashboard.vapi.ai/assistants) for Groq for a list of supported models.
# December 13, 2024
1. **Azure Speech Transcriber Support**: You can now use Azure's speech-to-text service by specifying `AzureSpeechTranscriber` as an option for `transcriber`. This allows you to leverage Azure's speech to text capabilities when creating or updating your assistant.
Refer to our [api docs](lhttps://api.vapi.ai/api) to learn more.
# December 11, 2024
1. **Use OpenAI Chat Completions in your Assistant**: you can now more easily integrate your Assistant with OpenAI's [chat completions sessions](https://platform.openai.com/docs/api-reference/chat) by specifying `messages` (an array of `OpenAIMessage` objects) and an `assistantId` (a string). Each `OpenAIMessage` in turn consists of a `content` (a string between 1 and 100,000,000 characters) and a role (between *assistant*, *function*, *user*, *system*, *tool*). This makes it easier to manage chat sessions associated with a specific assistant. Refer to the `ChatDTO`, `OpenAIMessage` schemas in [our API docs](https://api.vapi.ai/api) to learn more.
2. **Update Subscription Email on Billing Page**: you can now customize which email address appears on your Vapi invoices through the updated billing page > [under payment history](https://dashboard.vapi.ai/org/billing). You can specify an email address (in addition through physical address and tax id) - read more in [our docs](https://docs.vapi.ai/quickstart/billing#how-do-i-download-invoices-for-my-credit-purchases).
# December 10, 2024
1. **Claude Computer Use Tools Available**: You can now use [Claude computer use tools](https://www.anthropic.com/news/3-5-models-and-computer-use) like `BashTool`, `ComputerTool`, and `TextEditorTool` when building your Vapi assistant. Create these tools with `CreateBashToolDTO` (enables shell command execution), `CreateComputerToolDTO` (use desktop functionality with customizable display dimensions using `displayWidthPx`, `displayHeightPx`), and `CreateTextEditorToolDTO` (text editing operations), respectively.
Refer to our [API docs](https://api.vapi.ai/api) to learn more about how to use Claude computer use tools.
# December 9, 2024
1. **Improved Tavus Video Processing Error Messages**: Your call `endedReason` now includes detailed error messages for `pipeline-error-tavus-video-failed`. Use this to detect and manage scenarios where the Tavus video processing pipeline fails during a call.
# December 6, 2024
1. **OAuth 2 Authentication for Custom LLM Models and Webhooks**: In addition to (AuthZ)\[[https://www.okta.com/identity-101/authentication-vs-authorization/](https://www.okta.com/identity-101/authentication-vs-authorization/)], you can now now authenticate users accessing your [custom LLMs](https://docs.vapi.ai/customization/custom-llm/using-your-server#step-2-configuring-vapi-with-custom-llm) and [server urls (aka webhooks)](https://docs.vapi.ai/server-url) using OAuth2 (RFC 6749). Use the `authenticationSession` dictionary which contains an `accessToken` and `expiresAt` datetime to authenticate further requests to your custom LLM or server URL.
For example, create a webhook credential with `CreateCustomLLMCredentialDTO` with the following payload:
```json
{
"provider": "custom-llm",
"apiKey": "your-api-key-max-10000-characters",
"authenticationPlan": {
"type": "oauth2",
"url": "https://your-url.com/your/path/token",
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
},
"name": "your-credential-name-between-1-and-40-characters"
}
```
This returns a [`CustomLLMCredential`](https://api.vapi.ai/api) object as follows:
This can be used to authenticate successive requests to your custom LLM or server URL.
# December 5, 2024
1. **OAuth2 Support for Custom LLM Credentials and Webhooks**: You can now authorize access to your [custom LLMs](https://docs.vapi.ai/customization/custom-llm/using-your-server#step-2-configuring-vapi-with-custom-llm) and [server urls (aka webhooks)](https://docs.vapi.ai/server-url) using OAuth2 (RFC 6749).
For example, create a webhook credential with `CreateWebhookCredentialDTO` with the following payload:
```json
{
"provider": "webhook",
"authenticationPlan": {
"type": "oauth2",
"url": "https://your-url.com/your/path/token",
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
},
"name": "your-credential-name-between-1-and-40-characters"
}
```
This returns a [`WebhookCredential`](https://api.vapi.ai/api) object as follows:
3. **Removal of Canonical Knowledge Base**: The ability to create, update, and use canoncial knowledge bases in your assistant has been removed from the API(as custom knowledge bases and the Trieve integration supports as superset of this functionality). Please update your implementations as endpoints and models referencing canoncial knowledge base schemas are no longer available.
# December 3, 2024
1. **New xAI and Inflection AI models**: You can now set `Assistant.model` to use `XAI` (e.g., model `grok-beta`) or `Inflection AI` (e.g., model `inflection_3_pi`) by specifying these providers in your assistant configuration. Specify these providers in `assistant.model`, `call.squad.members.assistant.model`, or `call.squad.members.assistantOverrides.model`.
2. **Integrate Existing Trieve Vector Stores in Your Knowledge Base**: When you create a knowledge base with [`POST /knowledge-base`](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_create), you can now specify `vectorStoreProviderId` to use an existing vector store from your Trieve account.
3. **Create Vector Stores with Uploaded Files**: You can first upload files using the [`POST /files`](https://api.vapi.ai/api#/Files/FileController_create) endpoint, and then use the `fileIds` to specify the IDs of previously uploaded files to create a new Trieve vector store. You can customize how your files are ingested, chunked, then rebalanced to ensure correct knowledge is served by your assistant:
* *Split delimiters*: Specify `splitDelimiters` to control how files are split before chunking (default is `[.!?\n]`).
* *Splits per chunk*: Set `targetSplitsPerChunk` to specify the desired number of splits per chunk when creating a vector store (default is 20 splits per chunk).
* *Chunk rebalancing*: Set `rebalanceChunks` to `true` to evenly distribute remainder splits across chunks when creating a vector store to ensure balanced chunk sizes; for example, 66 splits with `targetSplitsPerChunk` of 20 will result in 3 chunks with 22 splits each.
4. **Customize Search Heuristics**: You can filter or remove search results from your knowledge base:
* *Filter by Score threshold*: Set `scoreThreshold` to filter out chunks during searches based on their score. For cosine similarity, chunks below the threshold are filtered out; for other distance metrics, chunks above the threshold are filtered.
* *Remove stop words*: Set `removeStopWords` to `true` to remove stop words during searches. The stop words list is specified in `server/src/stop-words.txt`, and queries that are entirely stop words will still be preserved.
5. **Updated Analytics Endpoint**: The `/analytics` endpoint has changed—use `GET /analytics` to retrieve analytics data instead of `POST /analytics`.
# November 30, 2024
1. **Extended Silence Timeout for Assistants**: You can now set `silenceTimeoutSeconds` up to 3600 seconds (previously 600 seconds) when creating or updating assistants and assistant overrides. This allows for longer periods of silence before an assistant session times out.
2. **New Credits Purchase Option**: You can now purchase credits to your subscription by navigating to the [updated billing page](https://dashboard.vapi.ai/org/billing/credits). Specify the dollar amount of your credits in the `credits` field to complete the purchase.
# November 27, 2024
1. **New Knowledge Base API Endpoints**: You can now create a knowledge base with [`POST /knowledge-base`](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_create), list knowledge bases with [`GET /knowledge-base`](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_findAll) or [`GET /knowledge-base/{id}`](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_findOne) for a specific knowledge base, update a knowledge base with [`PATCH /knowledge-base/{id}`](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_update), or delete a knowledge base with [`DELETE /knowledge-base/{id}`](https://api.vapi.ai/api#/Knowledge%20Base/KnowledgeBaseController_remove). Refer to the [Vapi API endpoints](https://api.vapi.ai/api#/) for more details.
2. **Configure Custom Knowledge Bases for your Assistant**: Configure a custom knowledge base for your assistant in three steps by first uploading a file [through the dashboard](https://dashboard.vapi.ai/files) or [the API](https://api.vapi.ai/api#/Files/FileController_create), then [create a knowledge base](https://docs.vapi.ai/knowledgebase#step-2-create-a-knowledge-base), and lastly [updating your assistant](https://docs.vapi.ai/knowledgebase#step-3-create-an-assistant) with the knowledge base id. You can also assign a knowledge base to models like `GroqModel`, `VapiModel`, `GoogleModel`, and others using the new `knowledgeBaseId` property.
3. **Integration with Trieve Knowledge Base**: Vapi now supports [Trieve](https://trieve.ai/) as our first knowledge base provider. Refer to [our docs](https://docs.vapi.ai/knowledgebase#step-2-create-a-knowledge-base) for an example of how to use Trieve.
4. **Inflection AI Credential Management**: You can now manage Inflection AI credentials through the [updated providers credentials](https://dashboard.vapi.ai/keys) page. `Call.endedReason` also now enumerates new values like `'pipeline-error-inflection-ai-llm-failed'` to indicate specific Inflection AI errors.
5. **New Transfer Mode with Summary in SIP Header**: You can now configure `TransferPlan.mode` to `'blind-transfer-add-summary-to-sip-header'` to forward calls and include a summary in the SIP header called `X-Transfer-Summary`. You can also add custom SIP headers during a transfer call using the `sipHeaders` property in `TransferDestinationSip`.
6. **Azure Credential Service Default**: When creating or updating Azure credentials in the [updated providers credentials](https://dashboard.vapi.ai/keys), the `service` field now defaults to `'speech'`.
7. **Support for Cantonese in Deepgram Transcriber**: The `DeepgramTranscriber.language` option now includes `'zh-HK'` for Cantonese (Hong Kong).
# November 25, 2024
1. **No length limit for assistant's first message**: You can now set `assistant.firstMessage` or `call.assistant.firstMessage` to any length; the previous maximum length restriction has been removed. This allows you to provide longer initial messages for the assistant's greeting.
# November 24, 2024
1. **Voice Fallback Plan Introduced**: You can now enhance your assistant's reliability by defining fallback voice providers using `assistant.voice.fallbackPlan.voices`. This allows your assistant to switch to alternative voices or providers like `FallbackLMNTVoice`, `FallbackAzureVoice`, `FallbackNeetsVoice`, `FallbackTavusVoice`, `FallbackOpenAIVoice`, and others if the primary voice provider fails.
2. **Language Selection for PlayHTVoice**: The `language` property has been added to `PlayHTVoice`. You can now specify the desired language for speech synthesis using `assistant.voice.language`.
3. **AssemblyAI Transcriber Available**: You can now use AssemblyAI for transcribing by setting `Assistant.transcriber` to `AssemblyAITranscriber`. This provides a new option for converting speech to text in your assistant.
4. **Updated OpenAI Model Support**: The `gpt-4o-2024-11-20` model has been added to `OpenAIModel.model` and `OpenAIModel.fallbackModels`. You can now configure your assistant to use this latest OpenAI model.
5. **Removal of 'fillerInjectionEnabled' Property**: The `fillerInjectionEnabled` property has been removed from voice configurations like `LMNTVoice`, `AzureVoice`, etc. You no longer need to include this property when configuring these voices.
# November 22, 2024
1. **Support for 'uaenorth' Region in Azure OpenAI Credentials**: When configuring Azure OpenAI credentials, you can now set `region` to use the UAE North region by specifying `'uaenorth'`.
# November 21, 2024
1. **Voice Fallback Plan**: You can now define a `fallbackPlan` in your assistant's voice settings in `assistant.voice.fallbackPlan` or `call.squad.members.assistant.voice.fallbackPlan` to specify alternative voices if your primary voice provider fails.
2. **AssemblyAI Credential Management**: You can now specify your AssemblyAI API keys in the updated "Transcriber Providers" page. Create your API key in the [AssemblyAI dashboard](https://www.assemblyai.com/app/account). AssemblyAI errors are now surfaced in the `endedReason` of `Call`, `ServerMessageEndOfCallReport`, and `ServerMessageStatusUpdate`.
3. **Enhanced BYO SIP Trunk Configuration**: When configuring BYO SIP trunk credentials, you can now specify a `techPrefix` for outbound SIP calls and enable `sipDiversionHeader` for authenticating the calling number (if supported). Refer to the `ByoSipTrunkCredential` schema in the [API reference](https://api.vapi.ai/api) to learn more.
4. **File Name Length Constraints**: The maximum file `name` length has been reduced from 100 to 40 characters. The required minimum length is still 1 character.
5. **Increased Server Timeout Limit**: The maximum value of `server.timeoutSeconds` has increased from 60 to 120 seconds, allowing longer timeouts for server responses.
6. **Extended Delay for Tool Messages**: The `timingMilliseconds` maximum in `ToolMessageDelayed` has increased from 20,000 to 120,000 milliseconds, enabling a longer delay for tool messages.
# November 15, 2024
1. **New Voices for `gpt-4o-realtime-preview-2024-10-01`**: You can now use new voice IDs: `ash`, `ballad`, `coral`, `sage`, and `verse` with the `voiceId` parameter when configuring `OpenAIVoice`. Please note that these voices are only available with the `gpt-4o-realtime-preview-2024-10-01` model.
# November 14, 2024
1. **Langfuse Credential Management**: You can now send traces to Langfuse by providing your "Secret Key", "Public Key", and "Host URL" for better telemetry monitoring. Create and update these credentials in the [updated Provider Credentials page](https://dashboard.vapi.ai/keys), under `Observability Providers`.
# November 11, 2024
1. **Subscription Updates**: You can now check the number of minutes used in a subscription with `Subscription.minutesUsed` (Enterprise only).
2. **Updates to Concurrency Limits in your Subscription**: `Subscription.concurrencyLimit` now shows both the included and purchased limits, which better represents the total concurrency limit. Refer to the [Subscription schema](https://api.vapi.ai/api/) for more details.
* Use `Subscription.concurrencyLimitIncluded` to get the default concurrency limit provided with the subscription.
* Use `Subscription.concurrencyLimitPurchased` to get any additional purchased concurrency limit.
# November 6, 2024
1. **New Anthropic model `claude-3-5-haiku-20241022` added**: You can now use `claude-3-5-haiku-20241022` in your assistants. Specify `anthropic` in `Assistant.model.provider` and `claude-3-5-haiku-20241022` in `Assistant.model`.
2. **Payment `cost`, Subscription `credits` and `couponUsageLeft` are now strings**: These properties are now strings to avoid floating point precision errors. Please update your applications to handle these values as strings.
3. **Advanced call logging improvements**: You can now access detailed call logs through the [updated call logs page](https://dashboard.vapi.ai/calls) or [`GET /logs?type=Call`](https://api.vapi.ai/api#/Logs/LoggingController_queryLogs) endpoint. Refer to `CallLogPrivileged` or `CallLogsPaginatedResponse` schemas in the [updated API reference](https://api.vapi.ai/api) to learn more.
# November 4, 2024
1. **XAi Model Support**: You can now use xAI's `grok-beta` model when creating or updating an assistant, and specify your API credentials from the [xAI console](https://console.x.ai/) in the [updated Provider Credentials page](https://dashboard.vapi.ai/keys). The list of call ended reasons has been updated to include xAI-specific errors.
# November 3, 2024
1. **Access Transport Details and Costs**: You can now use `call.transport` to access details about the provider used for a call (`twilio`, `vonage`, `vapi`, or `daily`), and whether the assistant's video is enabled for web calls (`assistantVideoEnabled`). Additionally, transport costs in `call.costs[type=transport]` now include a `provider` field, allowing you to see which provider contributed to the transport cost.
2. **Manage Tavus Credentials**: You can now create and update Tavus credentials in the [updated Provider Credentials page](https://dashboard.vapi.ai/keys).
# October 30, 2024
1. **Auto-reload Credits in Billing Page**: You can now auto-reload credits and check credits remaining for subscriptions within the [updated billing page](https://dashboard.vapi.ai/org/billing).
2. **Expanded Language Options in `CartesiaVoice`**: You can now specify additional languages in `CartesiaVoice.language` (optional), including 'hi' (Hindi), 'it' (Italian), 'ko' (Korean), 'nl' (Dutch), 'pl' (Polish), 'ru' (Russian), 'sv' (Swedish), and 'tr' (Turkish). Refer to the [CartesiaVoice](https://api.vapi.ai/api) schema for more details.
3. **Enhanced Template Variables in `AssistantOverrides`**: The `AssistantOverrides.variableValues` now supports LiquidJS syntax for replacing template variables. You can customize assistant messages using expressions like `{{ name }}` for dynamic content, or format dates with `{{"now" | date: "%b %d, %Y, %I:%M %p", "America/New_York"}}`.
# October 29, 2024
1. **Gemini Model Support and Credential Management**: You can now use Google Gemini models for your assistant (*gemini-1.5-flash-8b*, *gemini-1.5-flash-002*, *gemini-1.5-pro*, *gemini-1.0-pro*). Create and update your Google credentials by providing your `apiKey` from [Google AI Studio](https://aistudio.google.com/app/apikey) and setting your provider to `'google'` in Vapi.
2. **New Anthropic Model `claude-3-5-sonnet-20241022`**: You can now include Computer Use tools in the `toolWithToolCallList` of `ClientMessageToolCalls` or `ServerMessageToolCalls`. Select `'anthropic'` as your provider, `claude-3-5-sonnet-20241022`, and [create](https://api.vapi.ai/api#/Tools/ToolController_create) or [update](https://api.vapi.ai/api#/Tools/ToolController_update) newly supported computer use tools like `BashTool`, `ComputerTool`, or `TextEditorTool`.
3. **Enhanced Email Regex Support in Replacements**: The email matching regex pattern in `RegexReplacement` now supports top-level domains with two or more characters (`{2,}`). This improvement allows you to replace email addresses with placeholders like `[EMAIL]`, even for longer TLDs.
4. **Paginated Phone Number Responses**: [`GET /phone-numbers`](https://api.vapi.ai/api#/Phone%20Numbers/PhoneNumberController_findAll) now includes a `results` array of phone numbers and pagination metadata for easier handling of large datasets.
# October 25, 2024
1. **Specify API Traffic Channel for Organizations**: You can now configure which `channel` (cluster) your API traffic will be routed to. Select between *daily* or *weekly* in your [organization settings page](https://dashboard.vapi.ai/org/settings)
2. **Customize Tavus Voice Properties**: You can now use Tavus as a voice provider under `assistant.voice`. Configure additional properties like language, recording options, and transcriptions via `assistant.voice.properties`.
3. **Multilingual Support in Tool Messages**: You can now use the `contents` property in `ToolMessageStart`, `ToolMessageFailed`, `ToolMessageDelayed`, and `ToolMessageComplete` to provide message variants for different languages. If you don't provide content for a language, the first item will be automatically translated to the active language during the conversation.
4. **Automatic Translation of Message Contents**: For `CustomMessage`, `BlockStartMessage`, and `BlockCompleteMessage`, if specific content isn't provided for a language in `contents`, Vapi automatically translates the first item to the active language by default.
5. **Removed Backchanneling Configuration**: The `backchannelingEnabled` property has been removed from when creating or updating `Assistant` or `AssistantOverrides`. Backchanneling is no longer configurable in assistant settings.
# October 22, 2024
1. **Invite Multiple Users via Email**: You can now invite up to 100 users at once by providing a list of email addresses inside your [org users page](https://dashboard.vapi.ai/org/users). Click `'+'` after entering an email address, select the role as *Editor* or *Admin*, and click `'Invite'`.
2. **Simplified Subscription Status Handling**: Your subscription status no longer includes the `past-due` status, so you can streamline your subscription management without handling 'past-due' scenarios.
# October 19, 2024
1. **Custom Transcriber Support**: You can now integrate your own transcription service by using `CustomTranscriber` at `assistant.transcriber`, `call.squad.members.assistant.transcriber`, and `call.squad.members.assistantOverrides.transcriber`. Provide your custom transcription server details via `server.url` to receive real-time transcriptions during calls.
2. **Increased Maximum Call Duration**: The maximum allowed value for `maxDurationSeconds` has increased from 21,600 to 43,200 seconds when creating or updating `Assistant` or `AssistantOverrides`. You can now configure your assistant to handle calls lasting up to 12 hours.
3. **New Voice Provider 'tavus'**: You can now specify `tavus` as a voice provider in `Assistant.voice`, `AssistantOverrides.voice`, `Call.voice` and in the Voice Library.
4. **Subscription Status 'frozen' Added**: A new status `frozen` has been added to `Subscription.status`, indicating when a subscription is temporarily inactive.
5. **Added Subscription Coupon Codes**: You can now apply coupon codes to your subscription. Visit the [billing page](https://dashboard.vapi.ai/org/billing) to apply coupons to specific organizations within a subscription.
# October 16, 2024
1. **Apply Coupons to Subscriptions**: You can now apply coupons by specifying a `couponId` to add to a subscription.
2. **Detect Custom Transcriber Failures in Call End Reasons**: You can now handle cases where a custom transcriber fails during a call with `'pipeline-error-custom-transcriber-failed'`, a new `endedReason` option. This is now accessible in `Call`, `ServerMessageStatusUpdate`, and `ServerMessageEndOfCallReport`.
3. **Corrected Typo in Example Custom Voice Request**: We fixed a typo in `CustomVoice.server`, where the example request now shows how to use the `"message"` parameter instead of the misspelled `"messsage"`.
# October 13, 2024
1. **New Call Transfer Modes Added**: you can now wait for an operator to speak first before providing a transfer message or summary when transferring calls to a new destination with `TransferPlan`. Configure this through *transferPlan.mode=`'warm-transfer-wait-for-operator-to-speak-first-and-then-say-message'`* or *transferPlan.mode=`'warm-transfer-wait-for-operator-to-speak-first-and-then-say-summary'`* inside the request body of `POST /assistant` or `PATCH /assistant`.
2. **Unified Server Configuration in Assistants**: You can now use the `server` property in `Assistant.server`, `AssistantOverrides.server`, and when creating or updating assistants to specify webhook settings, including URL, secret, custom headers, and timeout. This replaces the old `serverUrl` and `serverUrlSecret` properties of `Assistant`.
Include custom headers in your webhook requests by using the
`headers`
property within the
`server`
object when creating or updating assistants.
3. **Configure PlayHT Voice Engines**: You can now configure which PlayHT voice `model` generates voices for your application between `PlayHT2.0`, `PlayHT2.0-turbo`, and `Play3.0-mini`.
# October 10, 2024
1. **Purchase Reserved Concurrency and Scale Infinitely**: You can now reserve more concurrent calls with Vapi and scale infinitely by switching to our new top up payment system on the [billing page](https://dashboard.vapi.ai/org/billing). To migrate, click "Switch to Credit Based Billing" and make a payment. Advantages include:
* **Support More Users Without Limits**: You don't need to worry about getting throttled or staying under usage limits on the conversations you can have with Vapi.
* **Predictable Budgets**: You know exactly how much you will spend on Vapi each month, and you can top up at any time as your needs grow.
* **Select Add-Ons You Need**: The credit based billing page allows you to select HIPAA compliance, dedicated Slack support, and the maximum number of concurrent calls you expect.
This will require human input to login and migrate your account. You will not be able to revert back to the old billing system.
# October 9, 2024
1. **Call Cost Information**: You can now use `call.costs[type=vapi].subType` to determine if a Vapi cost is `normal` or an `overage`.
2. **Updated Billing Page**: Your payments are now returned inside a table with pages on the [billing page](https://dashboard.vapi.ai/org/billing).
# October 8, 2024
1. **New GPT-4o Model Support for Azure OpenAI**: You can now specify the `gpt-4o-2024-08-06` model in the `models` field when configuring Azure OpenAI credentials. Use this model to access the latest GPT-4 operational capabilities in your applications.
2. **Specify Timestamps as Strings in `/logs`**: We now expect timestamps as strings when working with logs. Please make sure to handle this accordingly in your applications.
# October 7, 2024
1. **Add Structured Outputs for OpenAI Functions in Assistant Tools**: You can use [OpenAI Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) by specifying a new parameter called `strict` as true or false when creating or using `OpenAIFunction`s in `assistant.model.tools[type=function]`. Set the `name`, provide a `description` (up to 1000 characters), and specify `parameters` as a [JSON Schema object](https://json-schema.org/understanding-json-schema). See the [OpenAI guide](https://platform.openai.com/docs/guides/function-calling) for examples.
2. **Secure Incoming SIP Phone Calls to Vapi Provided SIP Numbers**: You can now specify a `username`, `password`, and optional `realm` in SIP Invite AuthZ header, through digest authentication. Create this secure SIP number by specifying an "authentication" object with the username and password fields inside `POST /phone-number` request body. Example:
```bash
curl --location 'https://api.vapi.ai/phone-number' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {}API_KEY}}' \
--data-raw '{
"provider": "vapi",
"sipUri": "sip:{{USERNAME}}@sip.vapi.ai",
"assistantId": "{{ASSISTANT_ID}}",
"name": "example phone number label for your reference",
"authentication": {
"realm": "sip.vapi.ai",
"username": "test@example.com",
"password": "example_password"
}
}'
```
3. **Use Updated `handoff`, `callback` Steps in Blocks**: You can now use `assistant.model.steps[type=handoff]` and `assistant.model.steps[type=callback]` to control conversation flow in your assistant. Use `HandoffStep` to move to the next step linearly without returning to the previous step, ideal for sequential tasks like forms. Use `CallbackStep` to spawn a new conversation thread and return to the previous step once done, good for handling interruptions or sub-tasks within a conversation.
4. **Use Step Destinations and Assignment Mutation in Blocks**: Specify destination nodes for each step with `assistant.model.steps[type=handoff].destinations[type=step]` to direct the workflow to specific steps based on certain conditions. Update context variables in each callback step with `mutations[type=assignment]`, for example: `assistant.model.steps[type=callback].mutations[type=assignment]`
Example trace in Langfuse: [https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/50163c14-9784-4cb9-b18e-23e924d0bb66](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/50163c14-9784-4cb9-b18e-23e924d0bb66)