Vapi Tutorial 2026: Build Your First AI Voice Agent

This Vapi AI tutorial takes you from an empty account to a voice agent that answers a real phone number and books appointments into Google Calendar, in eight steps and without code for the first version. Vapi gives you $5 in credits and one free US number to do it, which is enough for a dozen or more test calls.

Checked October 2026 against Vapi's assistants quickstart, Create Assistant API reference, Google Calendar and Function tools docs, free phone numbers page and pricing page. Steps and code follow those docs; the costs are calculated from published rates, not from logged calls.

At the end you will have an assistant with a prompt you wrote, two calendar tools, a phone number and a call log you can read. For how Vapi compares with building the same thing on other stacks, see our voice AI hub on building AI phone agents.

What is a Vapi voice AI agent made of?

A Vapi assistant is a saved configuration with three engines and a set of tools. Every turn of a call passes through them in the same order.

You pick each engine yourself or take a model preset. New assistants start on Balanced; the other presets are High Intelligence, Ultra Fast and Cost Saver. Swapping any single component moves the assistant to Customized.

Before you start: the pre-flight check

Vapi AI tutorial: the eight steps

Each step lists what you should see when it has worked. Menu names are the ones in Vapi's docs as of October 2026.

Two details in those steps save the most time. First, edits are saved as a draft and do not affect calls until you publish, so "it ignored my change" usually means an unpublished draft. Second, the tool description is what the model reads when it decides whether to call a tool, so write it as an instruction: when to use it, and what must be known first.

The assistant config, field by field

The dashboard and the API edit the same object. These are the fields that decide how a booking call feels, with the defaults from the API reference.

Here is the same assistant as one API call. It follows the request shape in Vapi's quickstart and Google Calendar docs, and assumes you have already connected Google Calendar in the dashboard. Northside Dental is a made-up example.

export VAPI_API_KEY="YOUR_PRIVATE_API_KEY"

curl --request POST \
  --url https://api.vapi.ai/assistant \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Front Desk",
    "firstMessage": "Thanks for calling Northside Dental. How can I help?",
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are the front desk assistant for Northside Dental. Keep replies under 30 words and ask one question at a time. To book, collect the caller name, the reason for the visit and a preferred day and time. Call checkAvailability first. If the slot is free, call scheduleAppointment with the reason as the summary. Read the date and time back before you book. All appointments are 30 minutes. Current date and time: {{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. All appointments are 30 minutes." }
      ]
    },
    "voice": { "provider": "11labs", "voiceId": "cgSgspJ2msm6clMCkdW9" },
    "endCallMessage": "Thanks for calling. Goodbye.",
    "maxDurationSeconds": 600
  }'

Copy the id from the response; you need it to attach a phone number or start a web call. The quickstart uses gpt-4o, and the API reference lists newer OpenAI IDs such as gpt-5.4-mini and gpt-6-luna as accepted values, so swap the model once the flow works.

One trap: {{now}} is the current time in UTC, and the calendar tools also default to UTC. If your callers are not in UTC, give the prompt local time with the date filter Vapi documents, and state the timezone in the tool description too:

Current date and time: {{"now" | date: "%A, %B %d, %Y, %I:%M %p", "America/New_York"}}

Wiring the booking function: built-in tool or your own

The Google Calendar tools need no server. The Create Event tool takes a summary, start and end times in ISO 8601, attendees, a timezone and a calendar ID that defaults to the primary calendar. Reach for a Function tool when the booking has to land in your own system.

A Function tool is a JSON schema plus a server URL. Create it once and reuse it across assistants:

curl --request POST \
  --url https://api.vapi.ai/tool \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "function",
    "function": {
      "name": "book_appointment",
      "description": "Books an appointment after the caller has confirmed the service, date and time.",
      "parameters": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Caller full name" },
          "service": { "type": "string", "description": "Service requested" },
          "startDateTime": { "type": "string", "description": "Start time in ISO 8601 with a timezone offset" }
        },
        "required": ["name", "service", "startDateTime"]
      }
    },
    "server": { "url": "https://YOUR_DOMAIN/vapi/tools" }
  }'

When the model calls it, Vapi sends a POST with a tool-calls message. Your server replies with one result per call. This Express handler follows the request and response format in the Function tools docs; createBooking stands for your own code.

import express from 'express'

const app = express()
app.use(express.json())

// Vapi posts every Function tool call here as a "tool-calls" message
app.post('/vapi/tools', async (req, res) => {
  const message = req.body.message
  if (!message || message.type !== 'tool-calls') return res.sendStatus(200)

  const results = []
  for (const toolCall of message.toolCallList) {
    const { name, arguments: args } = toolCall.function
    try {
      if (name !== 'book_appointment') throw new Error('Unknown tool: ' + name)
      const booking = await createBooking(args) // your scheduling API or database
      results.push({
        toolCallId: toolCall.id,
        result: 'Booked for ' + args.startDateTime + '. Reference ' + booking.id + '.',
      })
    } catch (err) {
      results.push({ toolCallId: toolCall.id, error: String(err.message).replace(/\s+/g, ' ') })
    }
  }

  // Always HTTP 200. A failure goes in "error", never in the status code.
  res.status(200).json({ results })
})

app.listen(3000)

To test locally, Vapi's CLI forwards events to your machine with vapi listen --forward-to localhost:3000/vapi/tools, but it does not create a public URL, so run a tunnel alongside it. If your backend is a workflow tool, Vapi documents an n8n route using an API Request tool and a published webhook; our n8n webhook guide covers the receiving side.

How do you run a Vapi AI demo call?

The fastest demo is the Talk button: a browser call to the published assistant, no phone number needed. To let other people try it on your site, use the Web SDK with a public API key. Restrict that key to your domain under Allowed Origins and to this assistant under Allowed Assistants.

import Vapi from '@vapi-ai/web';

const vapi = new Vapi('YOUR_PUBLIC_API_KEY');
vapi.start('YOUR_ASSISTANT_ID');

vapi.on('call-start', () => console.log('Call started'));
vapi.on('call-end', () => console.log('Call ended'));

Install it with npm install @vapi-ai/web. Never ship the private key to a browser; it is for server-side requests only.

What a call costs, from Vapi's own calculator

Vapi bills a hosting fee per minute and passes the transcriber, model and voice through at provider cost. The figures below are the ranges shown on the pricing page calculator, checked October 2026, applied to a three-minute call. The call length is an illustrative input, and we have not logged production calls for this tutorial.

Three things to take from it. The hosting fee is the floor: nothing you configure lowers it. The model is the widest range, and Vapi's cost docs say prompt and tool-definition size is the biggest lever you control, because both are resent on every request. And a number on your own Twilio account adds the carrier's rate, listed at $0.008 a minute inbound.

At these rates the $5 credit covers roughly 12 to 20 three-minute test calls. Usage-only accounts get 4 concurrent calls; the Core package at $29 a month raises that to 10. Your real figure is in the Call Cost tab of each call log. For the raw model rates behind the middle row, see our LLM API pricing comparison.

Troubleshooting

• Changes do not show up on calls. You edited the draft. Publish, then Quick Publish.
• The tool never fires. Use the exact tool name in the prompt and make the description specific. Vapi's troubleshooting guide also suggests strict: true on the function to surface schema errors in the call log.
• "No result returned". Wrong response shape or a non-200 status. Check Logs, Webhooks for what your server sent.
• Tool arguments are cut off. Raise maxTokens on the model, not on the tool. It accepts 50 to 10,000.
• Bookings land at the wrong hour. A UTC default somewhere. Set the timezone in the prompt and in the tool description.
• The number does not ring. New numbers take a few minutes to activate. Free numbers are US-only and inbound-only.
• It interrupts callers. Raise startSpeakingPlan.waitSeconds from its 0.4 second default.

Before real customers call, test against a sandbox calendar and re-run the awkward cases: a taken slot, a caller who changes their mind, a tool error. If you are choosing a platform as well as learning one, our Bland AI vs Vapi vs Retell comparison prices the same call on each, and the LiveKit Agents guide covers the open-source route.

A working agent is the easy half. If you plan to sell it, as a product or as a service to local businesses, our AI SaaS Builder program covers the parts around it: validating demand, pricing from your unit costs and billing with Stripe.

Vapi tutorial: FAQ