create-assistant

SKILL.md

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.

Provider
Models
Notes

openai
gpt-4o, gpt-4o-mini, gpt-4-turbo
Most popular, best tool calling

anthropic
claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022
Strong reasoning

google
gemini-1.5-pro, gemini-1.5-flash
Multimodal capable

groq
llama-3.1-70b-versatile, llama-3.1-8b-instant
Ultra-fast inference

deepinfra
meta-llama/Meta-Llama-3.1-70B-Instruct
Open-source models

openrouter
Various
Access 100+ models

perplexity
llama-3.1-sonar-large-128k-online
Web-connected

together-ai
Various open-source
Cost-effective

{
  "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.

Provider
Popular Voices
Notes

vapi
Elliot, Lily, Rohan, Paola, Kian
Vapi's optimized voices, lowest latency

11labs
Use voice IDs from ElevenLabs
High quality, many voices

playht
Use voice IDs from PlayHT
Expressive voices

cartesia
Use voice IDs from Cartesia
Fast, high quality

openai
alloy, echo, fable, onyx, nova, shimmer
OpenAI TTS voices

azure
Azure voice names
Enterprise-grade

deepgram
aura-asteria-en, aura-luna-en
Low latency

rime-ai
Use voice IDs from Rime
Specialized voices

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

Transcriber

The speech-to-text engine for understanding callers.

Provider
Models
Notes

deepgram
nova-3, nova-2
Fastest, most accurate

google
latest_long, latest_short
Google Cloud STT

gladia
fast, accurate
European provider

assembly-ai
best, nano
High accuracy

speechmatics
Various
Enterprise STT

talkscriber
Default
Specialized

{
  "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.