Building Production AI Voice Agents with Vapi.ai (2026 Complete Guide)

// lib/vapi.ts
import { VapiClient } from "@vapi-ai/server-sdk";
 
const client = new VapiClient({ token: process.env.VAPI_API_KEY });
 
export async function createAssistant() {
  const assistant = await client.assistants.create({
    name: "Plumbing Receptionist",
    model: {
      provider: "openai",
      model: "gpt-4",
      temperature: 0.7,
      systemPrompt: `You are a professional receptionist for a plumbing company.
      
Your job:
- Greet callers warmly
- Collect their name, address, and issue description
- Determine if it's an emergency
- Schedule appointments for non-emergencies
- Capture lead information
 
Rules:
- Be concise (under 30 seconds per response)
- Always confirm details back to the caller
- If emergency, collect contact number and say a plumber will call within 15 minutes
- Never say "I don't know", offer to have a human call back`,
    },
    voice: {
      provider: "elevenlabs",
      voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel
    },
    firstMessage: "Hello! Thanks for calling. I'm here to help with your plumbing needs. What can I assist you with today?",
  });
 
  return assistant;
}

// lib/vapi-functions.ts
 
interface LeadCaptureParams {
  name: string;
  phone: string;
  address: string;
  issue: string;
  isEmergency: boolean;
}
 
export async function captureLead(params: LeadCaptureParams) {
  // Save to your CRM (Airtable, HubSpot, etc.)
  await saveToCRM({
    ...params,
    source: "voice-agent",
    timestamp: new Date().toISOString(),
  });
 
  // Send notification
  if (params.isEmergency) {
    await sendEmergencyAlert(params);
  }
 
  return {
    success: true,
    message: params.isEmergency 
      ? "Emergency logged. A plumber will call you within 15 minutes."
      : "Great! I've scheduled you for tomorrow between 2-4 PM. You'll get a confirmation text.",
  };
}
 
// Vapi function schema
export const captureLeadSchema = {
  name: "captureLead",
  description: "Capture lead information and schedule appointment",
  parameters: {
    type: "object",
    properties: {
      name: {
        type: "string",
        description: "Caller's full name",
      },
      phone: {
        type: "string", 
        description: "Caller's phone number",
      },
      address: {
        type: "string",
        description: "Service address",
      },
      issue: {
        type: "string",
        description: "Brief description of plumbing issue",
      },
      isEmergency: {
        type: "boolean",
        description: "True if water damage, no water, or sewage backup",
      },
    },
    required: ["name", "phone", "issue", "isEmergency"],
  },
};

// Update your assistant creation
const assistant = await client.assistants.create({
  // ... previous config
  functions: [
    {
      name: "captureLead",
      description: captureLeadSchema.description,
      parameters: captureLeadSchema.parameters,
      async: true, // Your endpoint handles this
    },
  ],
});

// app/api/vapi/webhook/route.ts
import { NextRequest, NextResponse } from "next/server";
import { captureLead } from "@/lib/vapi-functions";
 
export async function POST(request: NextRequest) {
  const body = await request.json();
  
  // Vapi sends different message types
  const { message } = body;
 
  switch (message.type) {
    case "function-call":
      if (message.functionCall.name === "captureLead") {
        const result = await captureLead(message.functionCall.parameters);
        return NextResponse.json({
          result,
        });
      }
      break;
      
    case "end-of-call-report":
      // Log call analytics
      console.log("Call ended:", message);
      break;
      
    case "speech-update":
      // Real-time transcription (optional)
      break;
  }
 
  return NextResponse.json({ status: "ok" });
}

// lib/twilio.ts
import twilio from "twilio";
 
const client = twilio(
  process.env.TWILIO_ACCOUNT_SID,
  process.env.TWILIO_AUTH_TOKEN
);
 
export async function buyPhoneNumber(areaCode: string) {
  const numbers = await client.availablePhoneNumbers("US")
    .local
    .list({ areaCode, limit: 1 });
 
  if (numbers.length === 0) {
    throw new Error("No numbers available in this area code");
  }
 
  const purchased = await client.incomingPhoneNumbers.create({
    phoneNumber: numbers[0].phoneNumber,
    voiceUrl: "https://your-domain.com/api/vapi/inbound", // We'll create this
  });
 
  return purchased.phoneNumber;
}

// app/api/vapi/inbound/route.ts
import { NextRequest, NextResponse } from "next/server";
import twilio from "twilio";
 
const TWIML = `
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://your-vapi-websocket-url">
      <Parameter name="assistantId" value="your-assistant-id" />
    </Stream>
  </Connect>
</Response>
`;
 
export async function POST(request: NextRequest) {
  // You can add call screening logic here
  // E.g., check if business hours, spam detection, etc.
  
  return new NextResponse(TWIML, {
    headers: {
      "Content-Type": "text/xml",
    },
  });
}

// Easier but less control
const phoneNumber = await client.phoneNumbers.create({
  provider: "twilio",
  areaCode: "555",
  assistantId: assistant.id,
});

// lib/vapi-error-handler.ts
 
interface ErrorContext {
  callId: string;
  assistantId: string;
  customerPhone: string;
  error: Error;
  transcript: string;
}
 
export async function handleVoiceError(context: ErrorContext) {
  // 1. Log to monitoring
  await logError(context);
 
  // 2. Send fallback SMS
  await sendSMS({
    to: context.customerPhone,
    body: "Sorry, we had a technical issue. A human will call you back within 10 minutes.",
  });
 
  // 3. Alert team
  await sendSlackAlert({
    channel: "#voice-agent-alerts",
    text: `Voice agent failed for call ${context.callId}`,
    error: context.error.message,
  });
 
  // 4. Create task for human follow-up
  await createTask({
    type: "voice-agent-fallback",
    priority: "high",
    customerPhone: context.customerPhone,
    context: context.transcript,
  });
}

// middleware.ts or API route
import { Ratelimit } from "@upstash/ratelimit";
import { Redis } from "@upstash/redis";
 
const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, "1 m"), // 10 calls per minute per number
});
 
export async function middleware(request: NextRequest) {
  const ip = request.ip ?? "127.0.0.1";
  const { success, limit, remaining } = await ratelimit.limit(ip);
 
  if (!success) {
    return new NextResponse("Rate limit exceeded", { status: 429 });
  }
 
  return NextResponse.next();
}

// Smart routing example
const model = detectSimpleQuery(transcript) 
  ? "gpt-3.5-turbo" // $0.0015/1K tokens
  : "gpt-4";        // $0.03/1K tokens

// tests/vapi.test.ts
import { test, expect } from "@playwright/test";
 
test("AI receptionist captures leads correctly", async ({ page }) => {
  // Mock a call
  const call = await startTestCall({
    phoneNumber: "+15551234567",
    scenario: "emergency_leak",
  });
 
  // Simulate conversation
  await call.speak("Hi, I have a water leak in my basement");
  
  const response = await call.waitForResponse();
  expect(response).toContain("emergency");
  expect(response).toContain("15 minutes");
 
  // Verify function was called
  const lead = await getLastLead();
  expect(lead.isEmergency).toBe(true);
  expect(lead.issue).toContain("leak");
});

// Key metrics to log
interface CallMetrics {
  callId: string;
  duration: number;           // seconds
  cost: number;               // USD
  transcriptLength: number;   // characters
  functionsCalled: number;
  errors: number;
  customerSatisfaction?: number; // Post-call survey
  resolved: boolean;          // Did it solve the problem?
}
 
// Alert on:
// - >5% error rate
// - >$0.50 average cost per call
// - >10s average latency
// - <80% resolution rate