Create Assistant

Vapi Assistant Creation

Create fully configured voice AI assistants using the Vapi API. Assistants combine a language model, voice, and transcriber to handle real-time phone and web conversations.

Setup: Ensure VAPI_API_KEY is set. See the setup-api-key skill if needed.

Quick Start

cURL

curl -X POST https://api.vapi.ai/assistant \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Assistant",
    "firstMessage": "Hello! How can I help you today?",
    "model": {
      "provider": "openai",
      "model": "gpt-4.1",
      "messages": [
        {
          "role": "system",
          "content": "You are a friendly phone support assistant. Keep responses concise and under 30 words."
        }
      ]
    },
    "voice": {
      "provider": "vapi",
      "voiceId": "Elliot"
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-3",
      "language": "en"
    }
  }'

TypeScript (Server SDK)

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

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

const assistant = await vapi.assistants.create({
  name: "Support Assistant",
  firstMessage: "Hello! How can I help you today?",
  model: {
    provider: "openai",
    model: "gpt-4.1",
    messages: [
      {
        role: "system",
        content: "You are a friendly phone support assistant. Keep responses concise and under 30 words.",
      },
    ],
  },
  voice: {
    provider: "vapi",
    voiceId: "Elliot",
  },
  transcriber: {
    provider: "deepgram",
    model: "nova-3",
    language: "en",
  },
});

console.log("Assistant created:", assistant.id);

Python

import requests
import os

response = requests.post(
    "https://api.vapi.ai/assistant",
    headers={
        "Authorization": f"Bearer {os.environ['VAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Support Assistant",
        "firstMessage": "Hello! How can I help you today?",
        "model": {
            "provider": "openai",
            "model": "gpt-4.1",
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly phone support assistant. Keep responses concise and under 30 words.",
                }
            ],
        },
        "voice": {"provider": "vapi", "voiceId": "Elliot"},
        "transcriber": {"provider": "deepgram", "model": "nova-3", "language": "en"},
    },
)

assistant = response.json()
print(f"Assistant created: {assistant['id']}")

Core Configuration

Model (required)

The language model powering the assistant's intelligence.

{
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "temperature": 0.7,
    "maxTokens": 1000,
    "messages": [
      {
        "role": "system",
        "content": "Your system prompt here. Define the assistant's personality, rules, and behavior."
      }
    ]
  }
}

Voice

The text-to-speech voice for the assistant.

{
  "voice": {
    "provider": "vapi",
    "voiceId": "Elliot"
  }
}

Transcriber

The speech-to-text engine for understanding callers.

{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-3",
    "language": "en",
    "keywords": ["Vapi:2", "AI:1"]
  }
}

The keywords field boosts recognition of specific words (word:boost format, boost 1-10).

Behavior Configuration

First Message

{
  "firstMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?",
  "firstMessageMode": "assistant-speaks-first"
}

firstMessageMode options:

• "assistant-speaks-first" — Assistant greets immediately (default)
• "assistant-waits-for-user" — Assistant waits for caller to speak first
• "assistant-speaks-first-with-model-generated-message" — LLM generates the greeting

Background Sound

{
  "backgroundSound": "office"
}

Options: "off", "office", "static"

Backchanneling

Enable natural conversational acknowledgments ("uh-huh", "I see"):

{
  "backgroundDenoisingEnabled": true,
  "backchannelingEnabled": true
}

HIPAA Compliance

{
  "hipaaEnabled": true
}

When enabled, Vapi won't store call recordings or transcripts.

Adding Tools

Attach tools so the assistant can take actions during calls.

Using saved tool IDs

{
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "toolIds": ["tool-id-1", "tool-id-2"],
    "messages": [{"role": "system", "content": "..."}]
  }
}

Inline tool definition

{
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "check_availability",
          "description": "Check appointment availability for a given date",
          "parameters": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "description": "Date in YYYY-MM-DD format"
              }
            },
            "required": ["date"]
          }
        },
        "server": {
          "url": "https://your-server.com/api/tools"
        }
      }
    ],
    "messages": [{"role": "system", "content": "..."}]
  }
}

Hooks

Automate actions when specific call events occur. See hooks reference for details.

{
  "hooks": [
    {
      "on": "customer.speech.timeout",
      "options": {
        "timeoutSeconds": 10,
        "triggerMaxCount": 3
      },
      "do": [
        {
          "type": "say",
          "exact": "Are you still there?"
        }
      ]
    },
    {
      "on": "call.ending",
      "filters": [
        {
          "type": "oneOf",
          "key": "call.endedReason",
          "oneOf": ["pipeline-error"]
        }
      ],
      "do": [
        {
          "type": "tool",
          "tool": {
            "type": "transferCall",
            "destinations": [
              {
                "type": "number",
                "number": "+1234567890"
              }
            ]
          }
        }
      ]
    }
  ]
}

Managing Assistants

List

curl https://api.vapi.ai/assistant \
  -H "Authorization: Bearer $VAPI_API_KEY"

Get

curl https://api.vapi.ai/assistant/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY"

Update

curl -X PATCH https://api.vapi.ai/assistant/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstMessage": "Updated greeting!"
  }'

Delete

curl -X DELETE https://api.vapi.ai/assistant/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY"

Common Patterns

Customer Support Agent

{
  "name": "Customer Support",
  "firstMessage": "Thank you for calling! How can I assist you today?",
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful customer support agent for Acme Corp. Be empathetic, concise, and solution-oriented. If you cannot resolve an issue, offer to transfer to a human agent. Keep responses under 30 words."
      }
    ]
  },
  "voice": { "provider": "vapi", "voiceId": "Lily" },
  "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" },
  "backchannelingEnabled": true
}

Appointment Scheduler

{
  "name": "Appointment Scheduler",
  "firstMessage": "Hi there! I can help you schedule an appointment. What date works best for you?",
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "system",
        "content": "You are an appointment scheduling assistant. Collect the customer's preferred date, time, and service type. Confirm details before booking. Be friendly and efficient."
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "book_appointment",
          "description": "Book an appointment for the given date, time, and service",
          "parameters": {
            "type": "object",
            "properties": {
              "date": { "type": "string", "description": "YYYY-MM-DD" },
              "time": { "type": "string", "description": "HH:MM in 24h format" },
              "service": { "type": "string", "description": "Type of service" },
              "name": { "type": "string", "description": "Customer name" }
            },
            "required": ["date", "time", "service", "name"]
          }
        },
        "server": { "url": "https://your-server.com/api/book" }
      }
    ]
  },
  "voice": { "provider": "vapi", "voiceId": "Paola" },
  "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
}

Multilingual Agent

{
  "name": "Multilingual Support",
  "firstMessage": "Hello! How can I help you? / Hola! Como puedo ayudarte?",
  "model": {
    "provider": "openai",
    "model": "gpt-4.1",
    "messages": [
      {
        "role": "system",
        "content": "You are a multilingual support assistant. Detect the caller's language and respond in the same language. You support English and Spanish."
      }
    ]
  },
  "voice": { "provider": "vapi", "voiceId": "Paola" },
  "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "multi" }
}

References

• Hooks Configuration — Complete hook events and actions
• Voice & Model Providers — All supported providers and models
• Vapi API Docs — Official documentation

Additional Resources

This skills repository includes a Vapi documentation MCP server (vapi-docs) that gives your AI agent access to the full Vapi knowledge base. Use the searchDocs tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.

Auto-configured: If you cloned or installed these skills, the MCP server is already configured via .mcp.json (Claude Code), .cursor/mcp.json (Cursor), or .vscode/mcp.json (VS Code Copilot).

Manual setup: If your agent doesn't auto-detect the config, run:

claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server

See the README for full setup instructions across all supported agents.