Vapi

https://github.com/vapiai/docs
Admin
Vapi is a platform that provides real-time SDKs and server examples for building voice applications,...
Tokens:714,216
Snippets:6,144
Trust Score:8.8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### README section for team MCP setup

Source: https://github.com/vapiai/docs/blob/main/fern/cli/mcp-integration.mdx

Example README section for documenting the MCP setup with your team, including installation and setup commands.

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

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

### Install Go Server SDK

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/web.mdx

Install the Go Server SDK using go get.

```bash
go get github.com/VapiAI/server-sdk-go
```

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

### Setting up with localtunnel

Source: https://github.com/vapiai/docs/blob/main/fern/cli/webhook-testing.mdx

Commands to install and start localtunnel, then start the vapi listener. Use the localtunnel URL in the 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
```

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

### Skip SDK installation

Source: https://github.com/vapiai/docs/blob/main/fern/cli/project-integration.mdx

Generates only example files without installing packages.

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

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

### Webhook server setup (Python FastAPI)

Source: https://github.com/vapiai/docs/blob/main/fern/calls/call-dynamic-transfers.mdx

Starts a FastAPI webhook server for dynamic transfers. Imports required modules and initializes the FastAPI app.

```python
import os
import httpx
from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
```

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

### vapi init example output

Source: https://github.com/vapiai/docs/blob/main/fern/cli/project-integration.mdx

Example output of running `vapi init` in a Next.js 14 project. Shows detected framework, installed packages (@vapi-ai/web, @vapi-ai/server-sdk), generated files (components/VapiButton.tsx, app/api/vapi/webhook/route.ts, lib/vapi-client.ts, .env.example), and next steps including copying .env.example to .env, adding VAPI_API_KEY, running npm run dev, and testing at http://localhost:3000.

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

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

### Complete React + Web SDK example with client-side tool calls

Source: https://github.com/vapiai/docs/blob/main/fern/tools/client-side-websdk.mdx

Complete React + Web SDK example showing how to listen for client-side tool calls, parse the arguments, and update the UI when the 'updateUI' tool is invoked. It also demonstrates starting a call with a client-side tool (no server URL) and stopping the call.

```tsx
import Vapi from '@vapi-ai/web';
import { useCallback, useState } from 'react';

const vapi = new Vapi('<YOUR_PUBLIC_KEY>');

function App() {
  const [notification, setNotification] = useState<string | null>(null);

  const handleUIUpdate = useCallback((message?: string) => {
    setNotification(message || 'UI Update Triggered!');
    setTimeout(() => setNotification(null), 3000);
  }, []);

  // 1) Listen for client tool-calls and update the UI
  vapi.on('message', (message) => {
    console.log('Message:', message);

    if (message.type === 'tool-calls') {
      const toolCalls = message.toolCallList;

      toolCalls.forEach((toolCall) => {
        const functionName = toolCall.function?.name;
        let parameters: Record<string, unknown> = {};

        try {
          const args = toolCall.function?.arguments;
          if (typeof args === 'string') {
            parameters = JSON.parse(args || '{}');
          } else if (typeof args === 'object' && args !== null) {
            parameters = args as Record<string, unknown>;
          } else {
            parameters = {};
          }
        } catch (err) {
          console.error('Failed to parse toolCall arguments:', err);
          return;
        }

        if (functionName === 'updateUI') {
          handleUIUpdate((parameters as any).message);
        }
      });
    }
  });

  // 2) Start the call with a client-side tool (no server URL)
  const startCall = useCallback(() => {
    vapi.start({
      model: {
        provider: 'openai',
        model: 'gpt-4.1',
        messages: [
          {
            role: 'system',
            content:
              "You are an attentive assistant who can interact with the application's user interface by calling available tools. Whenever the user asks to update, refresh, change, or otherwise modify the UI, or hints that some UI update should occur, always use the 'updateUI' tool call with the requested action and relevant data. Use tool calls proactively if you determine that a UI update would be helpful.",
          },
        ],
        tools: [
          {
            type: 'function',
            async: true,
            function: {
              name: 'updateUI',
              description:
                'Call this function to initiate any UI update whenever the user requests or implies they want the user interface to change (for example: show a message, highlight something, trigger an animation, etc). Provide an \'action\' describing the update and an optional \'data\' object with specifics.',
              parameters: {
                type: 'object',
                properties: {
                  message: {
                    description:
                      'Feel free to start with any brief introduction message in 10 words.',
                    type: 'string',
                    default: '',
                  },
                },
                required: ['message'],
              },
            },
            messages: [
              {
                type: 'request-start',
                content: 'Updating UI...',
                blocking: false,
              },
            ],
          },
        ],
      },
      voice: { provider: 'vapi', version: 2, voiceId: 'Elliot' },
      transcriber: { provider: 'deepgram', model: 'nova-2', language: 'en' },
      name: 'Alex - Test',
      firstMessage: 'Hello.',
      voicemailMessage: "Please call back when you're available.",
      endCallMessage: 'Goodbye.',
      clientMessages: ['tool-calls'], // subscribe to client-side tool calls
    });
  }, []);

  const stopCall = useCallback(() => {
    vapi.stop();
  }, []);

  return (
    <div style={{
      minHeight: '100vh',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
      fontFamily:
        '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
    }}>
      {notification && (
        <div style={{
          position: 'fixed',
          top: 20,
          left: '50%',
          transform: 'translateX(-50%)',
          background: '#10b981',
          color: '#fff',
          padding: '16px 24px',
          textAlign: 'center',
          borderRadius: '12px',
          zIndex: 1000,
          maxWidth: 400,
          boxShadow: '0 10px 25px rgba(0, 0, 0, 0.2)',
          fontSize: '14px',
          fontWeight: 500,
        }}>
          {notification}
        </div>
      )}
```

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

### Initialize Vapi client for Python Server SDK

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/examples/docs-agent.mdx

Starts the Python Server SDK example for creating the `docsquery` API Request tool. Imports the necessary classes and initializes the Vapi client with a private API key.

```python
from vapi import JsonSchema, ToolParameter, Vapi
from vapi.tools import CreateToolsRequest_ApiRequest

client = Vapi(token="YOUR_VAPI_PRIVATE_API_KEY")


```

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

### Start Server (node server.js)

Source: https://github.com/vapiai/docs/blob/main/fern/calls/call-queue-management.mdx

Starts your server to test the queue management flow.

```bash
node server.js
```

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

### Dockerfile setup for Vapi

Source: https://github.com/vapiai/docs/blob/main/fern/cli/project-integration.mdx

Include these commands in your Dockerfile to install the Vapi CLI and initialize the project.

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

# Initialize project
RUN vapi init --skip-install
```

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

### Install C# Server SDK

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/web.mdx

Install the C# Server SDK using dotnet CLI.

```bash
dotnet add package Vapi.Net
```

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

### Before (OpenAI) - OpenAI client configuration

Source: https://github.com/vapiai/docs/blob/main/fern/chat/openai-compatibility.mdx

Original OpenAI client setup using the OpenAI SDK with your OpenAI API key. This is the starting point for migration.

```typescript
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
});
```

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

### Install Ruby Server SDK

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/web.mdx

Install the Ruby Server SDK using gem.

```bash
gem install vapi_server_sdk
```

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

### Set up tunnel and run Vapi CLI

Source: https://github.com/vapiai/docs/blob/main/fern/server-url/developing-locally.mdx

Use this two-terminal setup to test webhooks locally. Terminal 1 starts an ngrok tunnel on port 4242; Terminal 2 installs the Vapi CLI and runs 'vapi listen' to forward webhooks to localhost:3000/webhook. Note that 'vapi listen' does not provide a public URL; you must use a separate tunneling service to expose the CLI's port (default 4242) to the internet.

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

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

### Install and Test Redis Locally

Source: https://github.com/vapiai/docs/blob/main/fern/calls/call-queue-management.mdx

Installs and starts Redis locally on macOS, Ubuntu/Debian, or via Docker. After installation, test the connection with 'redis-cli ping' which should return 'PONG'.

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

```bash
redis-cli ping
# Should return: PONG
```

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

### Install Web SDK

Source: https://github.com/vapiai/docs/blob/main/fern/tools/client-side-websdk.mdx

Install the @vapi-ai/web package to use the Web SDK for client-side tool handling.

```bash
npm install @vapi-ai/web
```

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

### Quick start authentication commands

Source: https://github.com/vapiai/docs/blob/main/fern/cli/authentication.mdx

These commands are part of the quick start workflow: initial login, checking status, adding another account, and switching accounts.

```bash
vapi login
```

```bash
vapi auth status
```

```bash
vapi auth login
```

```bash
vapi auth switch production
```

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

### Install Vapi CLI with curl

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/introduction.mdx

Installs the Vapi CLI in seconds using a curl command. Run this in your terminal to get started with the full power of the Vapi platform from the command line.

```bash
curl -sSL https://vapi.ai/install.sh | bash
```

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

### QueryTool configuration example

Source: https://github.com/vapiai/docs/blob/main/fern/changelog/2025-03-06.mdx

Example configuration for the new QueryTool, which allows assistants to search knowledge bases. Configure it at `assistant.model.tools[type=query]`. The example includes a server URL, function definition, and a knowledge base with model, provider, description, and 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"]
    }
  ]
}
```

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

### Install vapi_server_sdk with pip

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/phone.mdx

Install the Vapi server SDK for Python using pip.

```bash
pip install vapi_server_sdk
```

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

### Install @vapi-ai/server-sdk with npm, yarn, pnpm, or bun

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/phone.mdx

Install the Vapi server SDK for TypeScript using your preferred package manager. These are alternative commands for the same installation step.

```bash
npm install @vapi-ai/server-sdk
```

```bash
yarn add @vapi-ai/server-sdk
```

```bash
pnpm add @vapi-ai/server-sdk
```

```bash
bun add @vapi-ai/server-sdk
```

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

### Local verification commands for the Fern example cache

Source: https://github.com/vapiai/docs/blob/main/scripts/fern/README.md

Run these commands to install the pinned Fern CLI, point the adapter at it, and execute the test suite plus local validation and preview generation. Use --preview only for verification; production publishing stays in the existing main-branch workflow. Logs print cache hits, misses, and uncached diagnostic-producing calls at exit.

```sh
npm install --prefix /tmp/vapi-fern --no-save fern-api@5.112.0
export FERN_CLI_PATH=/tmp/vapi-fern/node_modules/fern-api/cli.cjs
node --test scripts/fern/example-cache.test.cjs
node scripts/fern/run.cjs check --local --log-level debug
node scripts/fern/run.cjs generate --docs --preview --log-level debug
```

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

### Repository structure example

Source: https://github.com/vapiai/docs/blob/main/fern/enterprise/dev-uat-prod.mdx

Example repository structure for declarative resources. Shows directories for assistants, squads, tools, knowledge, policies, plus environments.yaml and schemas/.

```text
/platform
  /assistants
    order-agent.yaml
    support-agent.yaml
  /squads
    support-level1.yaml
  /tools
    jira.yaml
    zendesk.yaml
  /knowledge
    product-faqs.yaml
  /policies
    safety.yaml
  environments.yaml       # maps env → org IDs, model defaults, endpoints
  schemas/                # JSONSchema for validation
```

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

### Install @vapi-ai/react-native

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/web.mdx

Install the React Native SDK for building voice-enabled mobile apps.

```bash
npm install @vapi-ai/react-native
```

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

### Quick local testing with Vapi CLI and tunneling

Source: https://github.com/vapiai/docs/blob/main/fern/server-url.mdx

Quick local testing setup using Vapi CLI and tunneling. Terminal 1 creates an ngrok tunnel on port 4242, and Terminal 2 starts the Vapi webhook forwarder to localhost:3000/webhook. Remember to update your Vapi webhook URLs to use the ngrok public URL.

```bash
# Terminal 1: Create tunnel
ngrok http 4242
```

```bash
# Terminal 2: Start webhook forwarder
vapi listen --forward-to localhost:3000/webhook
```

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

### Install Vapi CLI and create an assistant

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/phone.mdx

Use the Vapi CLI to install, log in, and create an assistant directly from your terminal. This is an alternative to using the Dashboard or SDK.

```bash
# Install the CLI
curl -sSL https://vapi.ai/install.sh | bash

# Login and create an assistant
vapi login
vapi assistant create
```

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

### Starting the Server

Source: https://github.com/vapiai/docs/blob/main/fern/calls/call-handling-with-vapi-and-twilio.mdx

Starts the Express server on port 3000 and logs a message when it is running.

```js
app.listen(3000, () => {
  console.log("Server running on port 3000");
});
```

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

### Start the webhook listener

Source: https://github.com/vapiai/docs/blob/main/fern/cli/webhook-testing.mdx

Starts a local server on port 4242 that forwards to your application at localhost:3000/webhook.

```bash
vapi listen --forward-to localhost:3000/webhook
```

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

### Install @vapi-ai/web SDK (npm, yarn, pnpm, bun)

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/examples/voice-widget.mdx

Install the @vapi-ai/web SDK using your preferred package manager. These commands are equivalent alternatives for the React/TypeScript implementation.

```bash
npm install @vapi-ai/web
```

```bash
yarn add @vapi-ai/web
```

```bash
pnpm add @vapi-ai/web
```

```bash
bun add @vapi-ai/web
```

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

### Start server and export app

Source: https://github.com/vapiai/docs/blob/main/fern/calls/call-queue-management.mdx

Initializes Redis and starts the Express server on the specified port (default 3000). Logs the max concurrency and confirms callback-driven queue processing. Exports the app for testing.

```javascript
// Start server
    async function startServer() {
      await initializeRedis();
      
      const PORT = process.env.PORT || 3000;
      app.listen(PORT, () => {
        console.log(`Queue management server running on port ${PORT}`);
        console.log(`Max concurrency: ${MAX_CONCURRENCY}`);
        console.log('Using callback-driven queue processing (no timers)');
      });
    }

    startServer().catch(console.error);

    module.exports = app;
```

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

### Install Vapi React Package

Source: https://github.com/vapiai/docs/blob/main/fern/chat/web-widget.mdx

Install the React package using npm, yarn, or pnpm. Choose the command that matches your package manager.

```bash
npm install @vapi-ai/client-sdk-react
```

```bash
yarn add @vapi-ai/client-sdk-react
```

```bash
pnpm add @vapi-ai/client-sdk-react
```

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

### Prompt structure example

Source: https://github.com/vapiai/docs/blob/main/fern/openai-realtime.mdx

Example prompt structure for realtime models, organized into sections like Role & Objective, Personality & Tone, Instructions, Tools, and Safety.

```text
# Role & Objective
You are a customer service agent for Acme Corp. Your goal is to resolve issues quickly.

# Personality & Tone  
- Friendly, professional, and empathetic
- Speak naturally at a moderate pace
- Keep responses to 2-3 sentences

# Instructions
- Greet callers warmly
- Ask clarifying questions before offering solutions
- Always confirm understanding before proceeding

# Tools
Use the available tools to look up account information and process requests.

# Safety
If a caller becomes aggressive or requests something outside your scope, 
politely offer to transfer them to a specialist.
```

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

### Before: one classic system prompt

Source: https://github.com/vapiai/docs/blob/main/fern/gpt-live/migrate.mdx

A classic single-prompt example for an appointment assistant at Example Service Studio. It combines conversation style and task procedures in one prompt, before splitting into speaker and reasoner instructions.

```text
You are the booking assistant for Example Service Studio. Be friendly and brief.
Ask for the service, location, and date. Use lookupAvailability to find open
times and read them to the caller. When they choose one, ask for their name,
confirm the details, and call bookAppointment. Never say a booking is done
until bookAppointment succeeds. If the caller wants to change a booking, cancel
it with cancelAppointment first. Answer questions about services with
getServiceInfo.
```

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

### Example Output for Financial Services Application

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/structured-outputs-examples.mdx

Example output for a mortgage application with co-applicant and preferences. Shows the structured response format expected from the assistant.

```json
{
  "applicant": {
    "personalInfo": {
      "firstName": "David",
      "lastName": "Kim",
      "dateOfBirth": "1988-11-15",
      "ssn": "***-**-6789",
      "email": "dkim@example.com",
      "phone": "+12065551234",
      "currentAddress": {
        "street": "456 Pine Street",
        "city": "Seattle",
        "state": "WA",
        "zip": "98101",
        "yearsAtAddress": 3
      }
    },
    "employment": {
      "status": "full-time",
      "employerName": "Tech Corp",
      "jobTitle": "Senior Engineer",
      "yearsEmployed": 5,
      "annualIncome": 150000,
      "otherIncome": 12000,
      "incomeVerifiable": true
    },
    "financial": {
      "creditScore": 750,
      "monthlyDebt": 2500,
      "bankruptcyHistory": false,
      "existingAccounts": ["checking", "savings", "credit-card"],
      "accountNumbers": ["****1234", "****5678"]
    }
  },
  "loanDetails": {
    "type": "mortgage",
    "amount": 450000,
    "term": 30,
    "purpose": "home-purchase",
    "propertyAddress": {
      "street": "789 Oak Avenue",
      "city": "Bellevue",
      "state": "WA",
      "zip": "98004"
    },
    "propertyValue": 550000,
    "downPayment": 100000,
    "collateral": {
      "type": "real-estate",
      "value": 550000,
      "description": "Single family home"
    }
  },
  "coApplicant": {
    "hasCoApplicant": true,
    "relationship": "spouse",
    "name": "Sarah Kim",
    "income": 85000
  },
  "preferences": {
    "preferredRate": "fixed",
    "preferredPaymentDate": 1,
    "autopayInterest": true
  },
  "additionalInfo": "Looking to close within 45 days, have pre-approval from another lender"
}
```

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

### Install OpenAI SDK with npm, yarn, pnpm, or bun

Source: https://github.com/vapiai/docs/blob/main/fern/chat/openai-compatibility.mdx

Install the OpenAI SDK using your preferred package manager. Choose one of these commands based on your environment.

```bash
npm install openai
```

```bash
yarn add openai
```

```bash
pnpm add openai
```

```bash
bun add openai
```

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

### Install MCP server with permissions or nvm

Source: https://github.com/vapiai/docs/blob/main/fern/cli/mcp-integration.mdx

Install the MCP server with proper permissions or using a Node version manager to resolve permission errors.

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

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

### Install Dependencies and Configure Environment Variables

Source: https://github.com/vapiai/docs/blob/main/fern/calls/call-queue-management.mdx

Installs the required Node.js dependencies (express, twilio, axios, dotenv, redis) and sets up the environment variables for Vapi and Twilio configuration. The .env file includes placeholders for API keys and IDs.

```bash
npm install express twilio axios dotenv redis
```

```bash
# Vapi Configuration
VAPI_API_KEY=your_vapi_api_key_here
VAPI_PHONE_NUMBER_ID=your_phone_number_id
VAPI_ASSISTANT_ID=your_assistant_id

# Twilio Configuration  
TWILIO_ACCOUNT_SID=your_twilio_account_sid
TWILIO_AUTH_TOKEN=your_twilio_auth_token
TWILIO_QUEUE_SID=QUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
```

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

### Assistant prompt examples: too vague vs specific and clear

Source: https://github.com/vapiai/docs/blob/main/fern/tools/custom-tools-troubleshooting.mdx

Two example assistant prompts: the first is too vague and the second is specific and clear. Use the exact tool name in your assistant instructions; if your tool is named get_weather, reference get_weather in prompts, not weather_tool.

```txt
Handle weather requests
```

```txt
When user asks for weather, use weather_tool with city parameter
```

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

### Quick start: vapi login, vapi init, and vapi assistant create

Source: https://github.com/vapiai/docs/blob/main/fern/cli/overview.mdx

Quick start commands: authenticate with vapi login (opens browser for OAuth), initialize Vapi in an existing project with vapi init (auto-detects tech stack), and create a voice assistant with vapi assistant create (interactive prompts).

```bash
vapi login
```

```bash
vapi init
```

```bash
vapi assistant create
```

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

### Azure OpenAI Configuration Example

Source: https://github.com/vapiai/docs/blob/main/fern/providers/model/azure-openai.mdx

Example configuration for integrating Azure OpenAI with Vapi. Replace the placeholder values with your actual Azure OpenAI resource details.

```json
{
  "provider": "azure-openai",
  "models": ["gpt-4o-2024-11-20"],
  "region": "eastus", 
  "openAIEndpoint": "https://your-resource.openai.azure.com",
  "openAIKey": "your-azure-openai-api-key",
  "ocpApimSubscriptionKey": ""
}
```

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

### Intent routing example

Source: https://github.com/vapiai/docs/blob/main/fern/static/vapi-prompt-reference.md

Example of how to instruct the agent to detect which workflow to enter based on the caller's first response. Maps phrases like 'Book/schedule/make an appointment' to specific workflows.

```markdown
## Intent Routing
Listen to the caller's first response and route accordingly:
- "Book/schedule/make an appointment" → Workflow 2 (Booking)
- "Change/move/reschedule" → Workflow 3 (Rescheduling)
- "Cancel/cancellation" → Workflow 4 (Cancellation)
- Anything else → Ask clarifying question, then route
```

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

### Initialize Vapi in your project

Source: https://github.com/vapiai/docs/blob/main/fern/cli/project-integration.mdx

Navigate to your project directory and run the vapi init command to start the initialization process.

```bash
cd my-project
vapi init
```

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

### Slack tool configuration example

Source: https://github.com/vapiai/docs/blob/main/fern/tools/slack.mdx

Example assistant configuration that includes the Slack Send Message tool. The tool type is "slack.message.send" with a custom name and description that specifies the target channel and when to invoke it.

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

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

### Start a web call with Vapi (Python)

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/structured-outputs-quickstart.mdx

Starts a web call with an assistant that has structured outputs attached. Requires an assistant ID and a VAPI API key. Includes commented-out code for making an outbound phone call instead.

```python
from vapi import Vapi
import os

vapi = Vapi(token=os.environ.get("VAPI_API_KEY"))

# Start a web call with your assistant (replace with your assistant ID)
call = vapi.calls.create(
    assistant_id="your-assistant-id",  # Use an assistant with structured outputs attached
    type="webCall"
)

print(f'Call started: {call.id}')
print(f'Join URL: {call.web_call_url}')

# For phone calls, use:
# call = vapi.calls.create(
#     assistant_id="your-assistant-id",
#     type="outboundPhoneCall",
#     phone_number_id="your-phone-number-id",
#     customer={
#         "number": "+1234567890"
#     }
# )
```

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

### Setting up with ngrok

Source: https://github.com/vapiai/docs/blob/main/fern/cli/webhook-testing.mdx

Commands to start an ngrok tunnel and the vapi listener. Use the ngrok URL in the Vapi Dashboard.

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

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

### Set environment variables for setup script

Source: https://github.com/vapiai/docs/blob/main/fern/calls/transfer-calls-with-api-lookup.mdx

Set these environment variables in the terminal where you will run the setup script. Replace the example URL with your deployed endpoint and the fictional phone numbers with team-controlled test destinations in E.164 format. VAPI_API_KEY authenticates the setup request to Vapi; BRANCH_LOOKUP_CREDENTIAL_ID identifies the stored credential Vapi uses to authenticate to your lookup API.

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

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

### Start a web call with VapiClient (TypeScript)

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/structured-outputs-quickstart.mdx

Starts a web call with an assistant that has structured outputs attached. Requires an assistant ID and a VAPI API key. Includes commented-out code for making an outbound phone call instead.

```typescript
import { VapiClient } from "@vapi-ai/server-sdk";

const vapi = new VapiClient({ token: process.env.VAPI_API_KEY! });

// Start a web call with your assistant (replace with your assistant ID)
const call = await vapi.calls.create({
  assistantId: "your-assistant-id", // Use an assistant with structured outputs attached
  type: "webCall"
});

console.log('Call started:', call.id);
console.log('Join URL:', call.webCallUrl);

// For phone calls, use:
// const call = await vapi.calls.create({
//   assistantId: "your-assistant-id",
//   type: "outboundPhoneCall",
//   phoneNumberId: "your-phone-number-id",
//   customer: {
//     number: "+1234567890"
//   }
// });
```

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

### Run local development server with fern docs dev

Source: https://github.com/vapiai/docs/blob/main/README.md

Installs the Fern CLI globally and starts a local development server with hot-reloading for the documentation.

```sh
npm install -g fern-api
fern docs dev
```

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

### quickstart-assistant.json configuration for GPT-Live

Source: https://github.com/vapiai/docs/blob/main/fern/gpt-live/quickstart.mdx

JSON configuration for the GPT-Live assistant. Save as `quickstart-assistant.json`. Uses the OpenAI provider with model `gpt-live-1`, the `endCall` tool, the Marin voice, and `assistant-speaks-first` mode. The reasoner uses its defaults: `gpt-5.6-terra` with `low` reasoning effort.

```json
{
  "name": "GPT-Live quickstart",
  "model": {
    "provider": "openai",
    "model": "gpt-live-1",
    "speaker": {
      "instructions": "You are the front desk for Example Service Studio, a fictional business used for testing. Greet callers warmly, ask for their name and the reason for their call, and summarize what they told you. You can't look anything up or book appointments yet, so say so if they ask.\n\nSpeak plainly and keep replies short. Ask one question at a time. Use details the caller has already given.\n\nDelegation policy:\nBackend tools:\n- Ending the call.\n\nDelegate to the backend when:\n- The caller asks to end the call or says goodbye. Always delegate this. Saying goodbye does not end the call."
    },
    "reasoner": {
      "instructions": "Call endCall when the caller asks to end the call or says goodbye."
    },
    "tools": [
      { "type": "endCall" }
    ]
  },
  "voice": {
    "provider": "openai",
    "voiceId": "marin"
  },
  "firstMessageMode": "assistant-speaks-first",
  "firstMessage": "Hi, this is Example Service Studio. Who am I speaking with?",
  "maxDurationSeconds": 600
}
```

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

### System prompt integration with <flush />

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/flush-syntax.mdx

Example of embedding the <flush /> instruction directly into a system prompt to guide the assistant's behavior. The prompt tells the model to use the tag after acknowledging requests.

```javascript
const systemPrompt = `When providing lengthy responses, use <flush /> after acknowledging the user's request to provide immediate feedback.`;
```

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

### Initialize Node.js project

Source: https://github.com/vapiai/docs/blob/main/fern/customization/custom-transcriber.mdx

Creates a new Node.js project directory and initializes it with npm.

```bash
mkdir vapi-custom-transcriber
cd vapi-custom-transcriber
npm init -y
```

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

### Get call details with Vapi API

Source: https://github.com/vapiai/docs/blob/main/fern/calls/troubleshoot-call-forwarding-drops.mdx

Retrieve the call object from Vapi to inspect the endedReason. The cURL command uses YOUR_API_KEY and the call ID; the SDK examples use the call ID ca123456xxxxx. The response includes endedReason, status, destination, and phoneCallProviderId.

```bash
curl -X GET "https://api.vapi.ai/call/{call_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```typescript
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
from vapi import Vapi

client = Vapi(token=os.getenv("VAPI_API_KEY"))
call = client.calls.get("ca123456xxxxx")
print(f"End reason: {call.ended_reason}")
```

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

### Input workflow JSON for Acme Dental Front Desk

Source: https://github.com/vapiai/docs/blob/main/fern/static/workflow-migration-guide.md

Example input workflow for a dental front desk voice agent. Defines conversation nodes, variable extraction, and edges with conditions. Used as the starting point for the migration decisions described in the surrounding text.

```json
{
  "name": "Acme Dental Front Desk",
  "nodes": [
    { "id": "greet", "type": "conversation", "firstMessage": "Hi! Thanks for calling Acme Dental. How can I help?", "systemPrompt": "Greet the caller and ask what they need." },
    { "id": "collect", "type": "conversation", "systemPrompt": "Ask for the caller's full name and whether they're calling about an appointment or a billing question.",
      "extractVariables": [
        { "name": "patientName", "type": "string", "description": "the caller's full name" },
        { "name": "intent", "type": "string", "description": "appointment or billing" }
      ] },
    { "id": "schedule", "type": "conversation", "systemPrompt": "Ask {{patientName}} for a preferred date/time, confirm the appointment, and mention a text confirmation." },
    { "id": "billing", "type": "conversation", "systemPrompt": "Answer {{patientName}}'s billing question." },
    { "id": "bye", "type": "endCall", "firstMessage": "You're all set, have a great day!" }
  ],
  "edges": [
    { "from": "greet", "to": "collect", "condition": "caller states what they need" },
    { "from": "collect", "to": "schedule", "condition": "caller wants an appointment" },
    { "from": "collect", "to": "billing", "condition": "caller has a billing question" },
    { "from": "schedule", "to": "bye" },
    { "from": "billing", "to": "bye" }
  ]
}
```

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

### Setting up with cloudflared

Source: https://github.com/vapiai/docs/blob/main/fern/cli/webhook-testing.mdx

Commands to start a cloudflare tunnel and the vapi listener. Use the cloudflare URL in the 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
```

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

### Complete system prompt section for email collection

Source: https://github.com/vapiai/docs/blob/main/fern/assistants/email-address-reading.mdx

A complete system prompt section for an appointment booking agent that collects and confirms email addresses. It includes identity, step-by-step email collection rules, and an example conversation to guide the LLM's pacing and format.

```md
[Identity]
You are Sarah, a friendly appointment scheduling assistant for Acme Dental.

[Email Collection and Confirmation]
When you need the user's email address:
1. Ask: "What email address should we send the confirmation to?"
2. Wait for the full response. Do not interrupt.
3. Read the email back to the user following these rules:
   - Say "@" as "at"
   - Say "." as "dot"
   - Say "-" as "dash"
   - Say "_" as "underscore"
   - Separate each part with a comma so the voice pauses between them.
   - For well-known domains (gmail, yahoo, outlook, hotmail, icloud),
     say the domain name naturally.
   - For unfamiliar domains, spell them out letter by letter.
   - For the username, if it is a recognizable name or word, say it normally.
     If it looks like an abbreviation or random string, spell it out letter
     by letter.
4. After reading the email, ask: "Did I get that right?"
5. If the user says no:
   - Ask: "Could you spell it out for me letter by letter?"
   - Listen carefully, then read the corrected version back.
   - Ask again: "Is that correct now?"
6. Do not proceed to the next step until the user confirms the email.
7. Never modify, autocorrect, or guess any part of the email address.

[Example Conversation]
Agent: "What email address should we send the confirmation to?"
User: "It's jsmith42@newcompany.io"
Agent: "Let me read that back. j, s, m, i, t, h, four, two, at, new company,
        dot, i, o. Did I get that right?"
User: "Yes, that's correct."
```

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

### Environment setup commands

Source: https://github.com/vapiai/docs/blob/main/fern/cli/project-integration.mdx

These commands set up the environment after initialization: copy the environment template, add your Vapi API key, and optionally configure a webhook URL for local development.

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

```bash
VAPI_API_KEY=your-api-key-here
```

```bash
VAPI_WEBHOOK_URL=https://your-domain.com/api/vapi/webhook
```

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

### Initialize Vapi in a project

Source: https://github.com/vapiai/docs/blob/main/fern/cli/overview.mdx

Run `vapi init` to integrate Vapi into an existing codebase. The CLI auto-detects the framework (e.g., Next.js) and installs the SDK, generates a component, creates a webhook route, and adds an environment template.

```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://github.com/vapiai/docs/blob/main/fern/tools/integrations/n8n.mdx

Copies the example environment file to .env.local so you can set VAPI_API_KEY and N8N_WEBHOOK_URL. Keep .env.local private.

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

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

### Add system prompt instruction to use knowledge-search tool

Source: https://github.com/vapiai/docs/blob/main/fern/knowledge-base/using-query-tool.mdx

Example system prompt that explicitly instructs the assistant to use the 'knowledge-search' tool. The knowledge base description alone is not sufficient; you must name the tool in the system prompt. Replace 'knowledge-search' with your actual tool's function name.

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

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

### Set up local webhook testing with npm, ngrok, and vapi listen

Source: https://github.com/vapiai/docs/blob/main/fern/cli/webhook-testing.mdx

Set up a local development environment for testing Vapi webhooks. Run the app on port 3000, expose port 4242 with ngrok, and start the vapi listen CLI to forward webhooks to your local endpoint.

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

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

### Run the simulation suite

Source: https://github.com/vapiai/docs/blob/main/fern/observability/simulations-quickstart.mdx

Starts a suite run against an assistant or squad. Use `"provider": "vapi.websocket"` for voice instead of `vapi.webchat` for chat. The response includes the run's `id`, which you save to check the result in the next step.

```bash
curl -X POST "https://api.vapi.ai/eval/simulation/run" \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "simulations": [{ "type": "simulationSuite", "simulationSuiteId": "<suite-id>" }],
    "target": { "type": "assistant", "assistantId": "<riley-assistant-id>" },
    "transport": { "provider": "vapi.webchat" },
    "iterations": 1
  }'
```

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

### Set up MCP integration

Source: https://github.com/vapiai/docs/blob/main/fern/cli/overview.mdx

Run `vapi mcp setup` to enable Model Context Protocol integration, giving your IDE's AI assistant (Cursor, Windsurf, VSCode) accurate knowledge of Vapi's APIs and best practices.

```bash
vapi mcp setup
```

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

### Install Local SDK with pip

Source: https://github.com/vapiai/docs/blob/main/advanced.md

Installs the locally generated SDK in editable mode for development.

```sh
pip install -e /fern/.preview/fern-python-sdk
```

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

### Create the assistant with the tool attached using cURL

Source: https://github.com/vapiai/docs/blob/main/fern/outbound-campaigns/build-personalized-appointment-campaign.mdx

Send a POST request to /assistant to create an assistant. Attach the tool with model.toolIds, set firstMessageMode to assistant-waits-for-user, and include the system prompt as a system message. Replace <tool-id> with the id from the previous step and <system prompt> with the system prompt as a single JSON string. Save the id from the response.

```bash
curl --request POST \
  --url https://api.vapi.ai/assistant \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Appointment reminders",
    "firstMessage": "",
    "firstMessageMode": "assistant-waits-for-user",
    "model": {
      "provider": "openai",
      "model": "gpt-4.1",
      "toolIds": ["<tool-id>"],
      "messages": [
        { "role": "system", "content": "<system prompt>" }
      ]
    }
  }'
```

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

### CI/CD example (GitHub Actions)

Source: https://github.com/vapiai/docs/blob/main/fern/enterprise/dev-uat-prod.mdx

GitHub Actions workflow for deploying to UAT and production. The plan job validates and plans UAT, uploading the plan artifact; the deploy-prod job runs only on main, requires the plan job, and applies to prod with approval.

```yaml
name: Platform Deploy

on:
  pull_request:
  push:
    branches: [ main ]

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - name: Validate
        run: npm run validate:all
      - name: Plan UAT
        env:
          ORG_ID: ${{ secrets.UAT_ORG_ID }}
          API_TOKEN: ${{ secrets.UAT_TOKEN }}
        run: npm run plan -- --env uat --out plan-uat.txt
      - uses: actions/upload-artifact@v4
        with: { name: plan-uat, path: plan-uat.txt }

  deploy-prod:
    if: github.ref == 'refs/heads/main'
    needs: [ plan ]
    permissions: { contents: read }
    runs-on: ubuntu-latest
    environment:
      name: prod
      url: https://console.vendor.com/orgs/${{ secrets.PROD_ORG_ID }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - name: Apply PROD
        env:
          ORG_ID: ${{ secrets.PROD_ORG_ID }}
          API_TOKEN: ${{ secrets.PROD_TOKEN }}
        run: npm run apply -- --env prod --approve
```

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

### Install Fern CLI

Source: https://github.com/vapiai/docs/blob/main/advanced.md

Installs the Fern CLI globally, required for all subsequent commands in this documentation.

```sh
npm install -g fern-api
```

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

### Initialize Vapi and forward webhooks with Vapi CLI

Source: https://github.com/vapiai/docs/blob/main/fern/quickstart/web.mdx

Use the Vapi CLI to initialize a project and forward webhooks to a local server for development. The first command sets up Vapi in your project, and the second forwards webhooks to localhost:3000/webhook.

```bash
# Initialize Vapi in your project
vapi init
```

```bash
# Forward webhooks to local server
vapi listen --forward-to localhost:3000/webhook
```

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

### Verbal Consent Example Message

Source: https://github.com/vapiai/docs/blob/main/fern/security-and-privacy/recording-consent-plan.mdx

Example message for verbal consent, requiring explicit verbal confirmation from the user.

```text
"This call may be recorded for quality and training purposes. Do you agree to being recorded? Please say 'yes' if you agree or 'no' if you decline."
```
Tokens:
Raw