How to Build an AI Voice Receptionist with Vapi.ai

npm install @vapi-ai/server-sdk @vapi-ai/web

// lib/vapi/create-assistant.ts
import { VapiClient } from "@vapi-ai/server-sdk";
 
const client = new VapiClient({ token: process.env.VAPI_API_KEY! });
 
export async function createPlumbingReceptionist() {
  const assistant = await client.assistants.create({
    name: "Captain Plumber - AI Receptionist",
    model: {
      provider: "openai",
      model: "gpt-4o",
      temperature: 0.4,
      systemPrompt: buildSystemPrompt(),
    },
    voice: {
      provider: "elevenlabs",
      voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel - warm, professional
      stability: 0.5,
      similarityBoost: 0.75,
    },
    firstMessage:
      "Thanks for calling Captain Plumber. I'm here to help. Can I get your name and tell me what's going on with your plumbing?",
    endCallMessage:
      "You're all set. A member of our team will be in touch shortly. Have a good one.",
    recordingEnabled: true,
    transcriptPlan: {
      enabled: true,
    },
    silenceTimeoutSeconds: 30,
    maxDurationSeconds: 600,
    serverUrl: process.env.VAPI_WEBHOOK_URL!, // your backend endpoint
  });
 
  console.log("Assistant created:", assistant.id);
  return assistant;
}
 
function buildSystemPrompt(): string {
  return `You are the AI receptionist for Captain Plumber, a licensed plumbing company serving the Greater Boston area.
 
## Your Role
You handle inbound calls to collect information, assess urgency, and route the caller appropriately. You are professional, warm, and efficient. You do not diagnose problems - you gather information and connect people to the right help.
 
## Information to Collect on Every Call
1. Caller full name
2. Service address (street, city)
3. Brief description of the issue
4. Best callback number (confirm if different from caller ID)
5. Whether the situation is urgent or can wait
 
## Emergency Classification
A call is an EMERGENCY if the caller mentions:
- Active water leak or flooding
- No hot water (in winter months)
- Sewage backup
- Gas smell (redirect to 911 first, then collect info)
- Pipe burst
 
## Conversation Rules
- Keep responses under 25 words when possible - this is a phone call
- Repeat back key details to confirm accuracy
- Never say "I don't know" - say "Let me make sure someone calls you about that"
- If a caller is distressed, acknowledge it before asking questions
- Confirm the callback number by reading it back digit by digit
 
## Routing Logic
- EMERGENCY: Tell them a plumber will call within 15 minutes. Trigger the emergency function immediately.
- NON-EMERGENCY: Offer available appointment slots for the next business day. Trigger the schedule function.
- INFORMATION ONLY: Answer basic questions from the FAQ, then offer to book an estimate.
 
## What You Never Do
- Quote prices over the phone
- Guarantee specific arrival times beyond the 15-minute emergency callback
- Collect payment information
- Make promises outside your defined scope`;
}

// lib/vapi/assistant-functions.ts
 
export const vapiTools = [
  {
    type: "function" as const,
    function: {
      name: "capture_lead",
      description:
        "Save the caller's information as a new lead in the CRM. Call this once you have collected name, address, issue, and callback number.",
      parameters: {
        type: "object",
        properties: {
          callerName: {
            type: "string",
            description: "Full name of the caller",
          },
          callbackPhone: {
            type: "string",
            description: "Phone number to call back, digits only",
          },
          serviceAddress: {
            type: "string",
            description: "Full service address including city",
          },
          issueDescription: {
            type: "string",
            description: "Brief description of the plumbing issue in the caller's own words",
          },
          isEmergency: {
            type: "boolean",
            description: "True if the caller described an active leak, flooding, or similar emergency",
          },
          preferredTime: {
            type: "string",
            description: "Preferred appointment window if not an emergency, e.g. 'tomorrow morning'",
          },
        },
        required: ["callerName", "callbackPhone", "serviceAddress", "issueDescription", "isEmergency"],
      },
    },
  },
  {
    type: "function" as const,
    function: {
      name: "route_emergency",
      description:
        "Immediately notify the on-call plumber via SMS and paging. Only call this when isEmergency is true.",
      parameters: {
        type: "object",
        properties: {
          callerName: { type: "string" },
          callbackPhone: { type: "string" },
          serviceAddress: { type: "string" },
          issueDescription: { type: "string" },
        },
        required: ["callerName", "callbackPhone", "serviceAddress", "issueDescription"],
      },
    },
  },
  {
    type: "function" as const,
    function: {
      name: "check_availability",
      description:
        "Check available appointment slots for the next 3 business days. Call this for non-emergency scheduling.",
      parameters: {
        type: "object",
        properties: {
          preferredDate: {
            type: "string",
            description: "Caller's preferred date if mentioned, e.g. 'tomorrow' or 'Thursday'",
          },
          timePreference: {
            type: "string",
            enum: ["morning", "afternoon", "any"],
            description: "Caller's time preference",
          },
        },
        required: [],
      },
    },
  },
];

// Add tools to the assistant create call
const assistant = await client.assistants.create({
  name: "Captain Plumber - AI Receptionist",
  model: {
    provider: "openai",
    model: "gpt-4o",
    temperature: 0.4,
    systemPrompt: buildSystemPrompt(),
    tools: vapiTools, // attach the functions here
  },
  // ... rest of config
});

// app/api/vapi/webhook/route.ts  (Next.js App Router)
import { NextRequest, NextResponse } from "next/server";
import { captureLeadInCRM } from "@/lib/crm/capture-lead";
import { routeEmergency } from "@/lib/notifications/route-emergency";
import { getAvailableSlots } from "@/lib/calendar/availability";
 
interface VapiFunctionCallPayload {
  message: {
    type: "function-call";
    functionCall: {
      name: string;
      parameters: Record<string, unknown>;
    };
    call: {
      id: string;
      phoneNumber?: { number: string };
    };
  };
}
 
export async function POST(req: NextRequest): Promise<NextResponse> {
  const body = (await req.json()) as VapiFunctionCallPayload;
  const { message } = body;
 
  if (message.type !== "function-call") {
    return NextResponse.json({ result: "ok" });
  }
 
  const { name, parameters } = message.functionCall;
  const callId = message.call.id;
 
  try {
    switch (name) {
      case "capture_lead":
        return await handleCaptureLead(parameters, callId);
 
      case "route_emergency":
        return await handleRouteEmergency(parameters, callId);
 
      case "check_availability":
        return await handleCheckAvailability(parameters);
 
      default:
        console.warn(`Unknown function called: ${name}`);
        return NextResponse.json({
          result: "Function not recognized. Apologize to the caller and offer a callback.",
        });
    }
  } catch (error) {
    console.error(`Webhook handler error for ${name}:`, error);
    // Return a graceful message - the agent will speak this to the caller
    return NextResponse.json({
      result: "There was a technical issue on our end. Please tell the caller a team member will call them back within the hour.",
    });
  }
}
 
async function handleCaptureLead(
  params: Record<string, unknown>,
  callId: string
): Promise<NextResponse> {
  const lead = {
    callerName: params.callerName as string,
    callbackPhone: params.callbackPhone as string,
    serviceAddress: params.serviceAddress as string,
    issueDescription: params.issueDescription as string,
    isEmergency: params.isEmergency as boolean,
    preferredTime: (params.preferredTime as string) ?? null,
    callId,
    source: "ai-receptionist",
    createdAt: new Date().toISOString(),
  };
 
  const savedLead = await captureLeadInCRM(lead);
 
  return NextResponse.json({
    result: `Lead saved successfully. Reference number ${savedLead.id}. Tell the caller their information has been recorded and confirm the callback number you collected.`,
  });
}
 
async function handleRouteEmergency(
  params: Record<string, unknown>,
  callId: string
): Promise<NextResponse> {
  await routeEmergency({
    callerName: params.callerName as string,
    callbackPhone: params.callbackPhone as string,
    serviceAddress: params.serviceAddress as string,
    issueDescription: params.issueDescription as string,
    callId,
  });
 
  return NextResponse.json({
    result: "Emergency alert sent. Tell the caller: an on-call plumber has been notified and will call them back within 15 minutes. Give them a confirmation.",
  });
}
 
async function handleCheckAvailability(
  params: Record<string, unknown>
): Promise<NextResponse> {
  const slots = await getAvailableSlots({
    preferredDate: params.preferredDate as string | undefined,
    timePreference: (params.timePreference as "morning" | "afternoon" | "any") ?? "any",
  });
 
  if (slots.length === 0) {
    return NextResponse.json({
      result: "No slots available this week. Offer the caller the first available slot next week or take their info for a callback when slots open.",
    });
  }
 
  const slotDescriptions = slots
    .slice(0, 3)
    .map((s) => s.label)
    .join(", ");
 
  return NextResponse.json({
    result: `Available slots: ${slotDescriptions}. Read these options to the caller and ask which works best.`,
  });
}

// lib/notifications/route-emergency.ts
import twilio from "twilio";
 
const twilioClient = twilio(
  process.env.TWILIO_ACCOUNT_SID!,
  process.env.TWILIO_AUTH_TOKEN!
);
 
interface EmergencyAlert {
  callerName: string;
  callbackPhone: string;
  serviceAddress: string;
  issueDescription: string;
  callId: string;
}
 
export async function routeEmergency(alert: EmergencyAlert): Promise<void> {
  const oncallNumbers = getOnCallNumbers(); // rotate through your on-call schedule
  const messageBody = buildEmergencyMessage(alert);
 
  // SMS all on-call staff simultaneously
  const smsPromises = oncallNumbers.map((number) =>
    twilioClient.messages.create({
      body: messageBody,
      from: process.env.TWILIO_FROM_NUMBER!,
      to: number,
    })
  );
 
  // Also call the primary on-call number - SMS can be missed
  const callPromise = twilioClient.calls.create({
    twiml: buildEmergencyTwiML(alert),
    from: process.env.TWILIO_FROM_NUMBER!,
    to: oncallNumbers[0],
  });
 
  await Promise.all([...smsPromises, callPromise]);
 
  // Log for audit trail
  console.log(`Emergency routed for call ${alert.callId}`, {
    caller: alert.callerName,
    address: alert.serviceAddress,
    notifiedNumbers: oncallNumbers.length,
  });
}
 
function buildEmergencyMessage(alert: EmergencyAlert): string {
  return [
    "EMERGENCY CALL - Captain Plumber",
    `Caller: ${alert.callerName}`,
    `Phone: ${alert.callbackPhone}`,
    `Address: ${alert.serviceAddress}`,
    `Issue: ${alert.issueDescription}`,
    "Please call back within 15 min.",
  ].join("\n");
}
 
function buildEmergencyTwiML(alert: EmergencyAlert): string {
  return `<Response>
    <Say voice="Polly.Joanna">
      Emergency plumbing call. Caller ${alert.callerName} at ${alert.serviceAddress}
      reports ${alert.issueDescription}.
      Call back ${alert.callbackPhone} within 15 minutes.
      Press 1 to acknowledge.
    </Say>
    <Gather numDigits="1" />
  </Response>`;
}
 
function getOnCallNumbers(): string[] {
  // In production, pull this from your scheduling system or a simple env var
  const raw = process.env.ONCALL_NUMBERS ?? "";
  return raw.split(",").filter(Boolean);
}

// lib/crm/capture-lead.ts
import Airtable from "airtable";
 
const base = new Airtable({ apiKey: process.env.AIRTABLE_API_KEY }).base(
  process.env.AIRTABLE_BASE_ID!
);
 
interface LeadRecord {
  callerName: string;
  callbackPhone: string;
  serviceAddress: string;
  issueDescription: string;
  isEmergency: boolean;
  preferredTime: string | null;
  callId: string;
  source: string;
  createdAt: string;
}
 
interface SavedLead {
  id: string;
}
 
export async function captureLeadInCRM(lead: LeadRecord): Promise<SavedLead> {
  const record = await base("Leads").create({
    Name: lead.callerName,
    Phone: lead.callbackPhone,
    Address: lead.serviceAddress,
    Issue: lead.issueDescription,
    Emergency: lead.isEmergency,
    "Preferred Time": lead.preferredTime ?? "Flexible",
    "Call ID": lead.callId,
    Source: lead.source,
    Status: lead.isEmergency ? "Emergency - Needs Immediate Follow-up" : "New Lead",
    "Created At": lead.createdAt,
  });
 
  return { id: record.id };
}

// lib/notifications/send-caller-confirmation.ts
import twilio from "twilio";
 
const client = twilio(
  process.env.TWILIO_ACCOUNT_SID!,
  process.env.TWILIO_AUTH_TOKEN!
);
 
export async function sendCallerConfirmation(
  phone: string,
  callerName: string,
  isEmergency: boolean
): Promise<void> {
  const message = isEmergency
    ? `Hi ${callerName}, this is Captain Plumber. An on-call plumber has been notified and will call you within 15 minutes. Save this number: ${process.env.BUSINESS_PHONE}.`
    : `Hi ${callerName}, thanks for calling Captain Plumber. We've got your info and will be in touch to confirm your appointment. Questions? Call or text ${process.env.BUSINESS_PHONE}.`;
 
  await client.messages.create({
    body: message,
    from: process.env.TWILIO_FROM_NUMBER!,
    to: phone,
  });
}

// Add to assistant config
silenceTimeoutSeconds: 10,
// Vapi will end the call after 10s of silence
// Set firstMessage to prompt immediately so callers know someone is there
firstMessage: "Thanks for calling Captain Plumber. Can you hear me okay? Take your time and let me know what you need.",

// app/api/vapi/call-end/route.ts
import { NextRequest, NextResponse } from "next/server";
 
interface CallEndPayload {
  message: {
    type: "end-of-call-report";
    call: { id: string };
    transcript: string;
    summary: string;
  };
}
 
export async function POST(req: NextRequest): Promise<NextResponse> {
  const body = (await req.json()) as CallEndPayload;
 
  if (body.message.type !== "end-of-call-report") {
    return NextResponse.json({ ok: true });
  }
 
  const { call, transcript, summary } = body.message;
 
  // Save the full transcript and summary to your database
  // Even if the lead capture function was never triggered, you have the transcript
  await saveCallRecord({
    callId: call.id,
    transcript,
    summary,
    endedAt: new Date().toISOString(),
  });
 
  return NextResponse.json({ ok: true });
}

// lib/vapi/connect-phone-number.ts
import { VapiClient } from "@vapi-ai/server-sdk";
 
const client = new VapiClient({ token: process.env.VAPI_API_KEY! });
 
export async function connectPhoneNumber(
  twilioPhoneNumber: string,
  assistantId: string
): Promise<void> {
  await client.phoneNumbers.create({
    number: twilioPhoneNumber,
    twilioAccountSid: process.env.TWILIO_ACCOUNT_SID!,
    twilioAuthToken: process.env.TWILIO_AUTH_TOKEN!,
    assistantId,
    name: "Captain Plumber Main Line",
  });
 
  console.log(`Phone number ${twilioPhoneNumber} connected to assistant ${assistantId}`);
}

// Twilio Webhook fallback TwiML (paste in your Twilio console)
<Response>
  <Say>
    Thanks for calling Captain Plumber. We're experiencing a brief technical issue.
    Please call back at 617-555-0100 or leave a message and we'll return your call shortly.
  </Say>
  <Record maxLength="60" />
</Response>