Vapi

https://docs.vapi.ai/
Admin
Vapi is a developer platform for building voice AI agents that can make and receive phone calls,...
Tokens:814,581
Snippets:6,407
Trust Score:9.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run vapi init in your project directory

Source: https://docs.vapi.ai/cli/init

Navigate to your project directory and run `vapi init` to start the integration process. The CLI will detect your project type, install the SDK, generate example components and API routes, create environment configuration templates, and provide next steps.

```bash
cd my-project
vapi init

```

--------------------------------

### README section for team MCP setup

Source: https://docs.vapi.ai/cli/mcp

Example README section to document the MCP setup for your team. It lists the steps to install the Vapi CLI, run `vapi mcp setup`, and restart the IDE.

```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
```

--------------------------------

### Example vapi init output

Source: https://docs.vapi.ai/cli/init

Example output of running vapi init, showing the detected framework, installed packages, generated files, and next steps.

```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

```

--------------------------------

### Skip SDK installation

Source: https://docs.vapi.ai/cli/init

Generate only example files without installing packages using the --skip-install flag.

```bash
vapi init --skip-install
```

--------------------------------

### GitHub Actions CI/CD setup for Vapi

Source: https://docs.vapi.ai/cli/init

Add this step to a GitHub Actions workflow to install the Vapi CLI and initialize the project without installing dependencies.

```yaml
# GitHub Actions example
- name: Setup Vapi
  run: |
    curl -sSL https://vapi.ai/install.sh | bash
    vapi init --skip-install

```

--------------------------------

### Dockerfile setup for Vapi CLI

Source: https://docs.vapi.ai/cli/init

Include these Dockerfile instructions to install the Vapi CLI and initialize the project inside a Docker image.

```dockerfile
# Install Vapi CLI
RUN curl -sSL https://vapi.ai/install.sh | bash
# Initialize project
RUN vapi init --skip-install

```

--------------------------------

### Initialize Vapi with auto-detection

Source: https://docs.vapi.ai/cli

Initialize Vapi in an existing project with auto-detection. Shows example output for a Next.js app, installing the SDK and generating files.

```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
```

--------------------------------

### Copy .env.example to .env.local

Source: https://docs.vapi.ai/tools/integrations/n8n

Command to copy the environment example file to .env.local for configuring the starter.

```bash
cp .env.example .env.local
```

--------------------------------

### Install Redis Locally

Source: https://docs.vapi.ai/calls/call-queue-management

Install and start Redis locally on macOS, Ubuntu/Debian, or via Docker. The Docker command runs Redis on port 6379.

```bash
# macOS (using Homebrew)
brew install redis
brew services start redis
# Ubuntu/Debian
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
# Docker
docker run -d -p 6379:6379 redis:alpine
```

--------------------------------

### Install OpenAI SDK

Source: https://docs.vapi.ai/chat/openai-compatibility

Install the OpenAI SDK if it is not already present. This is the first step in the quick migration test.

```bash
npm install openai
```

--------------------------------

### Assistant JSON configuration with GoHighLevel tools

Source: https://docs.vapi.ai/tools/go-high-level

Example JSON setup for an assistant using GoHighLevel tools to schedule appointments. Includes system prompt with workflow instructions and tool definitions for checking availability, creating events, and managing contacts.

```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."
          }
      }
  ]
  }
}
```

--------------------------------

### 200 Response for Get Simulation Concurrency

Source: https://docs.vapi.ai/api-reference/simulations/simulation-controller-get-concurrency

Example 200 response from the GET /eval/simulation/concurrency endpoint. Contains orgId, concurrencyLimit, activeSimulations, availableToStart, createdAt, updatedAt, and isDefault fields.

```json
{
  "orgId": "string",
  "concurrencyLimit": 1.1,
  "activeSimulations": 1.1,
  "availableToStart": 1.1,
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "isDefault": true
}
```

--------------------------------

### Copy environment template

Source: https://docs.vapi.ai/cli/init

Copy the .env.example file to .env to start configuring your environment.

```bash
cp .env.example .env
```

--------------------------------

### Get Scorecard 200 Response

Source: https://docs.vapi.ai/api-reference/observability-scorecard/scorecard-controller-get

Example 200 response body for the Get Scorecard endpoint. Contains scorecard metadata, metrics with conditions, and optional assistant IDs.

```json
{
  "id": "string",
  "orgId": "string",
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "metrics": [
    {
      "conditions": [
        {
          "comparator": "=",
          "points": 1.1,
          "type": "comparator",
          "value": 1.1
        }
      ],
      "structuredOutputId": "string"
    }
  ],
  "name": "string",
  "description": "string",
  "assistantIds": [
    "string"
  ]
}
```

--------------------------------

### Run the starter script with Node.js

Source: https://docs.vapi.ai/tools/integrations/n8n

Command to run the starter script using the .env.local file for environment variables.

```bash
node --env-file=.env.local scripts/run.mjs
```

--------------------------------

### Set environment variables for setup script

Source: https://docs.vapi.ai/calls/transfer-calls-with-api-lookup

Export these environment variables in the terminal before running the setup script. Replace the example URL and phone numbers with your deployed endpoint and team-controlled test destinations.

```bash
export VAPI_API_KEY="YOUR_PRIVATE_VAPI_API_KEY"
export BRANCH_LOOKUP_URL="https://api.example.com/branches/lookup"
export BRANCH_LOOKUP_CREDENTIAL_ID="YOUR_CUSTOM_CREDENTIAL_ID"
export NORTH_BRANCH_NUMBER="+14155550100"
export SOUTH_BRANCH_NUMBER="+14155550101"
```

--------------------------------

### Install Vapi CLI and create an assistant

Source: https://docs.vapi.ai/dashboard

Install the Vapi CLI, log in, and create an assistant directly from the terminal. Requires a Vapi account and API key.

```bash
# Install the CLI
curl -sSL https://vapi.ai/install.sh | bash
# Login and create an assistant
vapi login
vapi assistant create
```

--------------------------------

### Initialize Vapi and forward webhooks with Vapi CLI

Source: https://docs.vapi.ai/quickstart/web

Use the Vapi CLI to initialize a project and forward webhooks to a local server for development. Run 'vapi init' to set up, then 'vapi listen --forward-to localhost:3000/webhook' to test webhooks locally.

```bash
# Initialize Vapi in your project
vapi init
# Forward webhooks to local server
vapi listen --forward-to localhost:3000/webhook
```

--------------------------------

### speech-update webhook payload

Source: https://docs.vapi.ai/server-url/events

Example of the speech-update webhook message, indicating when speech starts or stops for a role.

```json
{
  "message": {
    "type": "speech-update",
    "status": "started",
    "role": "assistant",
    "turn": 2
  }
}
```

--------------------------------

### Get Simulation 200 Response

Source: https://docs.vapi.ai/api-reference/simulations/simulation-controller-find-one

Example 200 response body for the Get Simulation endpoint. Contains simulation metadata including id, orgId, timestamps, scenarioId, personalityId, optional name, and optional path.

```json
{
  "id": "string",
  "orgId": "string",
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "scenarioId": "string",
  "personalityId": "string",
  "name": "Eligible Path with Confused User",
  "path": "string"
}
```

--------------------------------

### Complete pipeline timeline example

Source: https://docs.vapi.ai/customization/voice-pipeline-configuration

Illustrates the timing of each pipeline stage from user stopping speech to assistant speaking, with example durations.

```text
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
```

--------------------------------

### Get Boards 200 Response

Source: https://docs.vapi.ai/api-reference/board/board-controller-find-all

Example 200 response returned by the Get Boards endpoint. Contains a list of board objects with layout, items, and time range override fields, plus pagination metadata.

```json
{
  "results": [
    {
      "id": "string",
      "orgId": "string",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "name": "string",
      "layout": {
        "columns": 6
      },
      "items": [
        {
          "insightId": "string",
          "position": {
            "x": 1.1,
            "y": 1.1
          },
          "size": {
            "height": 1.1,
            "width": 1.1
          },
          "systemKey": "string",
          "type": "insight"
        }
      ],
      "systemKey": "string",
      "timeRangeOverride": {
        "step": "minute",
        "start": "\"2025-01-01\" or \"-7d\" or \"now\"",
        "end": "\"2025-01-01\" or \"now\"",
        "timezone": "string"
      }
    }
  ],
  "metadata": {
    "itemsPerPage": 1.1,
    "totalItems": 1.1,
    "currentPage": 1.1,
    "totalPages": 1.1,
    "hasNextPage": true,
    "nextCursor": "string",
    "sortOrder": "ASC",
    "itemsBeyondRetention": true,
    "createdAtLe": "2024-01-15T09:30:00Z",
    "createdAtGe": "2024-01-15T09:30:00Z"
  }
}
```

--------------------------------

### Assistant system prompt integration example

Source: https://docs.vapi.ai/knowledge-base/using-query-tool

Example system message that instructs the assistant to use the 'knowledge-search' tool. Replace 'knowledge-search' with the actual tool's function name from the query tool configuration. The knowledge base description alone is not sufficient; explicit instructions are required.

```json
{
  "role": "system",
  "content": "You are a helpful customer support assistant. When users ask about products, pricing, features, or need troubleshooting help, use the 'knowledge-search' tool to search our knowledge base for accurate information. Always call the knowledge-search tool before providing answers to ensure accuracy."
}
```

--------------------------------

### GET /eval/simulation/concurrency

Source: https://docs.vapi.ai/api-reference/simulations/simulation-controller-get-concurrency

Retrieves the organization's simulation concurrency limit, the number of active simulations, and how many more can start.

```APIDOC
## GET /eval/simulation/concurrency

### Description
Returns the organization's simulation concurrency limit, the number of active simulations, and how many more can start.

### Method
GET

### Endpoint
https://api.vapi.ai/eval/simulation/concurrency

### Authentication
Authorization: Bearer
Authenticate server-side requests with a private Vapi API key. Create or copy a key from the Vapi Dashboard and send it in the `Authorization` header as `Bearer <token>`. Keep private API keys out of client-side code and public repositories.

### Request Example
```
curl https://api.vapi.ai/eval/simulation/concurrency \
     -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **orgId** (string) - Organization ID
- **concurrencyLimit** (double) - Max call slots for simulations (each voice simulation uses 2 call slots: tester + target)
- **activeSimulations** (double) - Number of call slots currently in use by running simulations
- **availableToStart** (double) - Number of voice simulations that can start now (available call slots / 2)
- **createdAt** (datetime or null) - Creation timestamp
- **updatedAt** (datetime or null) - Last update timestamp
- **isDefault** (boolean) - True if org is using platform default concurrency limit

#### Response Example
```
{
  "orgId": "string",
  "concurrencyLimit": 1.1,
  "activeSimulations": 1.1,
  "availableToStart": 1.1,
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "isDefault": true
}
```
```

--------------------------------

### 200 response for get insights

Source: https://docs.vapi.ai/api-reference/insight/insight-controller-find-all

Example response returned when insights are successfully retrieved. Shows the structure of results and metadata.

```json
{
  "results": [
    {
      "type": "bar",
      "id": "string",
      "orgId": "string",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "name": "string",
      "systemKey": "string"
    }
  ],
  "metadata": {
    "itemsPerPage": 1.1,
    "totalItems": 1.1,
    "currentPage": 1.1,
    "totalPages": 1.1,
    "hasNextPage": true,
    "nextCursor": "string",
    "sortOrder": "ASC",
    "itemsBeyondRetention": true,
    "createdAtLe": "2024-01-15T09:30:00Z",
    "createdAtGe": "2024-01-15T09:30:00Z"
  }
}
```

--------------------------------

### Initialize in a specific directory

Source: https://docs.vapi.ai/cli/init

Run vapi init with a path to create the project in that directory.

```bash
vapi init /path/to/project
```
Tokens:
Raw