Vapi

View saved version →

---
name: create-assistant
description: Design, create, or validate saved and transient Vapi voice assistants. Use for new phone or web agents, production system prompts and first messages, saved-versus-transient architecture, model/voice/transcriber selection, multilingual compatibility, existing tool attachment, native call-control tools, assistant hooks, and Create Assistant API validation errors.
license: MIT
---

# Vapi Assistant Creation

Design the assistant's behavior before assembling its configuration. Treat persistence and execution as separate decisions: a returned configuration can still describe a saved assistant, and creating a saved assistant does not deploy it, attach a phone number, or prove it is production-ready.

## Source and Safety Rules

- Use the configured Vapi documentation MCP when available for current product guidance. Otherwise use the bundled references and their public Vapi links. Validate the final payload against the current Create Assistant API schema.
- Never print, request in chat, or embed API keys, provider secrets, credential values, private URLs, or real customer data.
- Never invent IDs, destinations, integrations, server URLs, model names, voices, transcribers, schemas, or business policy.
- Keep a saved assistant's `name` at 40 characters or fewer.
- Do not enable paid, HIPAA, PCI, recording, retention, or other compliance behavior unless the user requests it and the current docs support the exact configuration.
- Treat prompts as behavioral instructions, not capabilities or security boundaries. Scheduling, lookup, transfer, messaging, authentication, and other actions require real tools or server-side support.

## Procedure

1. Decide the assistant architecture and requested action.
   - Prefer a **saved assistant** for a reusable agent that should be shared, attached by ID, or managed over time. If the user simply asks to create or build an agent, use this shape unless the request indicates otherwise.
   - Use a **transient assistant** only when the user asks for an inline or call-scoped configuration, or when the use case specifically needs per-call configuration, short-lived testing, or an `assistant-request` response. Put it in the call's `assistant` field; do not send it to `POST /assistant`.
   - If the user asks for JSON, an example, a draft, or an implementation without account mutation, return the appropriate configuration without calling the API.
   - If the user asks to create or save the assistant in Vapi and `VAPI_API_KEY` is available, create a saved assistant with `POST /assistant`. Do not ask for redundant confirmation after an unambiguous create request.
   - If creation is requested but credentials are unavailable, return a save-ready configuration and command, and state clearly that the assistant has not been saved. Do not relabel it as transient.

2. Run a focused requirements intake.
   - Infer what is clear from the request, then collect only missing facts that materially affect the design: business and audience, call direction, primary objective and success criteria, workflows, authoritative business knowledge, real tools or integrations, escalation boundaries, information to collect or avoid, languages, and brand voice.
   - Ask a compact group of clarifying questions when several business facts are required to produce a credible agent. Learn enough about the business before claiming the agent is ready.
   - Decide whether one assistant can own the workflow reliably. Use the `create-squad` skill when distinct specialists, routing, or handoffs are central to the design.
   - Do not ask the user to choose infrastructure providers unless they expressed a preference or the use case creates a real language, latency, compliance, or credential constraint.

3. Design a production-quality system prompt.
   - Use the `vapi-prompt-builder` skill for every new assistant or substantial prompt rewrite when it is available. Otherwise read [Prompt Design](references/prompt-

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: create-call
description: Create one-off outbound phone calls, web calls, scheduled calls, and simple batch calls using the Vapi API. Use when making or testing individual calls or initiating a bounded /call request programmatically. Use create-campaign for a persistent multi-contact Campaign with lifecycle, reporting, cancellation, duplication, or campaign webhooks.
license: MIT
---

# Vapi Call Creation

Initiate outbound phone calls, web calls, and batch calls using Vapi's API. Connect your voice assistants to real phone numbers and test them programmatically.

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

## Quick Start — Outbound Phone Call

### cURL

```bash
curl -X POST https://api.vapi.ai/call \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "your-assistant-id",
    "phoneNumberId": "your-phone-number-id",
    "customer": {
      "number": "+11234567890"
    }
  }'
```

### TypeScript (Server SDK)

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

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

const call = await vapi.calls.create({
  assistantId: "your-assistant-id",
  phoneNumberId: "your-phone-number-id",
  customer: {
    number: "+11234567890",
  },
});

console.log("Call created:", call.id);
```

### Python

```python
import requests
import os

response = requests.post(
    "https://api.vapi.ai/call",
    headers={
        "Authorization": f"Bearer {os.environ['VAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "assistantId": "your-assistant-id",
        "phoneNumberId": "your-phone-number-id",
        "customer": {"number": "+11234567890"},
    },
)

call = response.json()
print(f"Call initiated: {call['id']}")
```

## Call Types

### Outbound Phone Call

Requires an assistant, a Vapi phone number, and a customer number.

```json
{
  "assistantId": "assistant-id",
  "phoneNumberId": "phone-number-id",
  "customer": {
    "number": "+11234567890",
    "name": "John Doe",
    "numberE164CheckEnabled": true
  }
}
```

### Web Call

For browser-based calls — no phone number needed. Use the Vapi Web SDK on the client side.

```json
{
  "assistantId": "assistant-id"
}
```

Client-side (JavaScript):
```javascript
import Vapi from "@vapi-ai/web";

const vapi = new Vapi("your-public-key");
vapi.start("your-assistant-id");
```

### Transient Assistant Call

Define an assistant inline instead of referencing a saved one:

```json
{
  "assistant": {
    "name": "Quick Test",
    "firstMessage": "Hello! This is a test call.",
    "model": {
      "provider": "openai",
      "model": "gpt-4.1",
      "messages": [
        {
          "role": "system",
          "content": "You are a test assistant. Confirm the call is working and end politely."
        }
      ]
    },
    "voice": { "provider": "vapi", "voiceId": "Elliot", "version": 2 },
    "transcriber": { "provider": "deepgram", "model": "nova-3", "language": "en" }
  },
  "phoneNumberId": "phone-number-id",
  "customer": {
    "number": "+11234567890"
  }
}
```

## Scheduled Calls

Schedule a call for a future time:

```json
{
  "assistantId": "assistant-id",
  "phoneNumberId": "phone-number-id",
  "customer": {
    "number": "+11234567890"
  },
  "schedulePlan": {
    "earliestAt": "2025-06-15T14:00:00Z",
    "latestAt": "2025-06-15T15:00:00Z"
  }
}
```

- `earliestAt` — Earliest time to attempt the call (ISO 8601)
- `latestAt` — Latest time to attempt the call (optional)
- If using `assistantId`, the latest version of the assistant is used at call time
- For a fixed assistant config, use `assistant` (transient) instead

## Batch Calls

Call multiple numbers in one request:

```json
{
  "assistantId": "assistant-id",
  "phoneNumberId": "phone-number-id",
  "customers": [
    { "number": "+11234567890", "name": "Alice" },
    { "number": "+10987654321", "name": "Bob" },
    { "number": "+1

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: create-campaign
description: Create, schedule, duplicate, inspect, cancel, archive, and troubleshoot Vapi outbound Campaigns. Use for persistent multi-contact calling, CSV or API contact personalization, campaign concurrency, campaign webhooks, pre-dial eligibility, contact outcomes, or rerunning an audience. Do not use for a single call or a simple one-off /call batch.
license: MIT
---

# Vapi Outbound Campaigns

Use Campaigns for a persistent outbound run whose contacts, lifecycle, and results must be managed together. Creating a campaign launches it immediately or schedules it; there is no draft or separate start action.

The current public API uses `/v2/campaign`. The unversioned `/campaign` endpoints are legacy and have different behavior. Use `/v2/campaign` for new integrations, and touch `/campaign` only when the user explicitly asks to maintain an existing legacy integration.

## Source and Safety Rules

- Verify live payloads against the current Vapi documentation MCP, [Campaigns documentation](https://docs.vapi.ai/outbound-campaigns/overview), or public API reference. Do not silently fall back from `/v2/campaign` to legacy `/campaign` behavior.
- Use a private API key only on a trusted server. Read it from `VAPI_API_KEY`; never print it, request it in chat, or put it in client-side code, examples, logs, or committed files.
- Treat phone numbers, names, contact variables, call records, transcripts, and recordings as sensitive. Report counts and redacted samples unless the user needs specific records.
- Never invent resource IDs, recipients, consent, schedules, time zones, campaign state, counters, or call outcomes. Resolve saved resources by exact ID or an unambiguous API result.
- Launching can place real, chargeable calls. Before a live create or duplicate, review the exact target, outbound number, audience count, timing, concurrency, and webhook behavior. Obtain confirmation unless the user's current instruction already unambiguously authorizes that exact launch.
- Do not make a legal determination. Tell the user to verify the consent, caller-identification, recording, opt-out, quiet-hours, and telemarketing requirements that apply to every recipient and destination. Use Vapi's [TCPA consent guidance](https://docs.vapi.ai/tcpa-consent) when relevant.
- A timeout or ambiguous response to `POST /v2/campaign` does not prove failure. Search for the intended campaign before retrying so the audience is not called twice.

## Procedure

1. Choose the API and execution mode.
   - Use `POST /call` and the `create-call` skill for one call or a simple one-off batch that does not need campaign-level lifecycle, reporting, cancellation, duplication, or webhooks.
   - Return a plan, CSV, payload, or implementation without calling Vapi when the user asks to draft, explain, review, or prepare.
   - Use live API operations only when the user asks to create, duplicate, cancel, or archive and `VAPI_API_KEY` is available.

2. Resolve the caller and outbound number.
   - Select exactly one saved `assistantId` or `squadId`. Do not use deprecated Workflows for a new campaign.
   - Resolve one outbound-capable `phoneNumberId`. Vapi Free Numbers cannot launch campaigns. The current `/v2/campaign` API does not support legacy `dialPlan` routing across multiple outbound numbers.
   - Inspect the assistant or squad before launch. Ensure its prompt, tools, variables, call-ending behavior, and published configuration match this outbound use case.
   - Configure one voicemail approach on every assistant that may handle a campaign call: the assistant-driven voicemail tool or built-in voicemail detection, never both. Test representative voicemail and call-screening paths before scaling.

3. Prepare and validate contacts.
   - Allow 1 to 10,000 contacts. Prefer E.164 numbers such as `+14155550100`. In an API request, an intentional non-E.164 SIP-trunk destination requires `numberE164CheckEnabled: false` on that customer; the number must stil

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: create-phone-number
description: Plan, provision, import, route, update, and verify Vapi phone numbers through the public API. Use for Vapi-hosted US PSTN numbers, explicitly requested SIP addresses, Twilio/Vonage/Telnyx or BYO carrier numbers, secure credential handling, assistant or squad routing, area-code requests, outbound limitations, and phone-provider troubleshooting.
license: MIT
---

# Vapi Phone Number Setup

Default to a payload or implementation plan. Provision, import, route, or release a number only when the user explicitly requests the live mutation. Require a final explicit confirmation immediately before provisioning or another potentially chargeable action.

## Security and Source Rules

- Never ask for carrier passwords, auth tokens, API keys, API secrets, or private keys in chat.
- Use an existing Vapi `credentialId` for provider imports when the current public schema supports it. If a required credential does not exist, stop and state that API prerequisite.
- If the public API requires raw carrier secrets and exposes no credential-based alternative, source them from local environment variables without displaying them, writing them to payload files, or logging the request body.
- Verify provider fields against the current [Create Phone Number API](https://docs.vapi.ai/api-reference/phone-numbers/create) or public OpenAPI schema.
- Never invent phone numbers, SIP realms, credentials, resource IDs, area-code availability, or routing destinations.

## Procedure

1. Determine the execution mode.
   - Return a payload or plan when the user asks for a draft or does not clearly authorize a live mutation.
   - For a live request, confirm that `VAPI_API_KEY` is set without printing it.

2. Choose the transport path.
   - For a nontechnical request for an ordinary number, prefer the documented Vapi-hosted US PSTN path.
   - Use SIP only when the user explicitly asks for SIP. Require an exact supported SIP URI from the user or current public API documentation; if it is unavailable, stop and state the missing prerequisite. Do not invent a regional realm.
   - Use a carrier import only when the user owns the number and the required secure credential path is available.

3. Resolve routing before mutation.
   - List or get assistants and squads through public endpoints. Match a supplied name to one resource.
   - If several resources are plausible, ask the user to choose. Never guess an ID.
   - Route to either one `assistantId` or one `squadId`; clear conflicting destination fields when changing an existing route.

4. Check inventory safely.
   - Review existing phone numbers with `GET /phone-number` to avoid duplicate provisioning.
   - The current public OpenAPI accepts `numberDesiredAreaCode` but does not expose a public available-area-code inventory endpoint. Accept the user's desired three-digit US area code after explaining that fulfillment is not guaranteed.
   - Do not purchase a number merely to test availability. Do not infer global unavailability from one provisioning response.

5. Confirm and execute.
   - Show the provider, area code or exact owned number, routing destination, and whether the action may incur carrier or usage charges.
   - Obtain explicit confirmation immediately before `POST /phone-number` or another potentially chargeable mutation.
   - Validate the response for `id`, provider, number or SIP URI, status when present, and resolved route.

6. Update without destroying configuration.
   - `GET /phone-number/{id}` first.
   - Build the provider-specific update DTO. Change only requested writable fields and preserve the current provider, hooks, server, fallback destination, and provider-specific settings by omission or exact carry-forward as required by the public schema.
   - Do not send response-only fields such as `id`, timestamps, or organization metadata.
   - Re-fetch the number and verify the requested route or setting.

7. Handle failures precisely.
   - `400`: report the rej

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: create-squad
description: Design, create, update, and verify Vapi Squads and documented handoff tools through the public API. Use for choosing a single assistant versus a multi-assistant Squad, persistent or transient members, entry-member ordering, specialization boundaries, context engineering, variable extraction, model-specific handoff patterns, assistant-version pins, and safe Squad updates.
license: MIT
---

# Vapi Squad Creation

Use a Squad only when multiple focused assistants improve the design. Default to a payload or implementation plan unless the user explicitly requests live Vapi mutations.

## Decide Whether to Use a Squad

Prefer one assistant when one focused prompt and one compatible tool set can handle the use case reliably. Use a Squad for genuine boundaries such as:

- distinct domains or personas;
- different tool or credential access;
- deliberate context isolation;
- separately maintained specialists.

Do not create one assistant per conversational step. Keep related steps in one member and make each handoff boundary earn its latency and operational cost.

## Safety and Source Rules

- Verify squad, member, handoff, context, and version fields against the current public [Squads documentation](https://docs.vapi.ai/squads), [Handoff tool guide](https://docs.vapi.ai/squads/handoff), and OpenAPI schema.
- Never invent assistant IDs, names, tool IDs, destinations, versions, credentials, server URLs, or extracted variables.
- Prompt text does not create a handoff. Configure and attach a documented `handoff` tool.
- Keep member order explicit: the first member starts the call.
- Prefer saved assistants, reusable tools, and a saved Squad for production. Use transient members or Squads only when the request is intentionally ephemeral or a prototype.

## Persistent Squad Procedure

1. Determine the execution mode.
   - Return JSON or a plan when the user asks for a draft or does not clearly authorize live writes.
   - Perform live creates or updates only with explicit intent and an available `VAPI_API_KEY`.

2. Define focused members.
   - State each member's responsibility, tools, and handoff boundaries.
   - Choose the entry member and place it first.
   - Reuse existing assistants by resolving names through `GET /assistant`; create missing assistants first with the `create-assistant` skill.

3. Create handoff relationships after destinations exist.
   - Resolve every destination assistant before building a persistent handoff tool.
   - Use `type: "assistant"` plus a verified `assistantId` for saved cross-assistant destinations.
   - Use clear descriptions that state when the model should hand off and what should be collected first.
   - Create reusable handoff tools through `POST /tool`, then attach them to the source assistants with the configuration-preserving procedure in the `create-tool` skill.
   - For OpenAI models, current public guidance recommends one handoff tool per destination. For Anthropic models, one tool with multiple destinations is supported and recommended.

4. Configure public context controls only when needed.
   - Use `contextEngineeringPlan` on a handoff destination: `all`, `lastNMessages`, `userAndAssistantMessages`, `previousAssistantMessages`, or `none` when supported by the current schema.
   - Use `variableExtractionPlan.schema` only for specific structured values needed downstream. Do not invent values or claim extraction occurred before a real handoff.
   - Keep sensitive tool results out of downstream context when the use case requires isolation.

5. Create and verify the Squad.
   - Build `members` from verified assistant IDs in explicit order.
   - Optionally set `assistantVersion` only to a version returned by the public assistant API when the user wants an immutable pin. Omit it to follow latest.
   - Before a production-affecting create or update, recap member order, handoffs, and target and obtain explicit confirmation unless the user's current instruction alread

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: create-structured-output
description: Design, create, inspect, update, attach, detach, preview, execute, and verify reusable Vapi Structured Outputs through public API or Server SDK workflows. Use for post-call extraction, typed call artifacts, AI-versus-regex extraction, JSON Schema design, backfilling existing calls, or retrieving structured results programmatically.
license: MIT
---

# Vapi Structured Output Creation

Build the smallest reusable post-call extraction that represents the user's actual downstream contract. Keep definition creation, assistant attachment, execution, and result retrieval separate: success at one stage does not prove the next stage occurred.

## Source and Safety Rules

- Use the configured Vapi documentation MCP when available. Otherwise use current public Vapi API documentation and [API Examples](references/api-examples.md). Revalidate request fields and SDK methods before final implementation.
- Use a private Vapi API key only on a trusted server. Read it from `VAPI_API_KEY`; never print, request in chat, or embed it in source, client-side code, or examples.
- Never invent resource IDs, call IDs, extraction fields, enum values, data-retention requirements, or customer data.
- Do not enable `compliancePlan.forceStoreOnHipaaEnabled` unless the user explicitly requests it and confirms that the output cannot contain PHI or other sensitive data.
- Treat call transcripts, messages, tool results, and extracted values as sensitive customer data. Minimize what is logged or reproduced.

## Procedure

1. Choose the output mode.
   - For a schema, payload, review, or implementation example, return an artifact without calling Vapi. State that nothing was saved, attached, or executed.
   - For a reusable saved definition, use `POST /structured-output` only when the user asks to create or save it and credentials are available.
   - For a one-call experiment that does not need a saved definition, pass a transient `structuredOutput` to `POST /structured-output/run` with `previewEnabled: true`.
   - Treat attachment, detachment, and execution against existing calls as separate requested actions. Do not infer them from creation alone.

2. Define the extraction contract.
   - Identify the downstream consumer, required fields, optional fields, allowed categories, formats, and behavior when evidence is absent or ambiguous.
   - Ask only for missing facts that materially change the schema. State safe assumptions for the rest.
   - Split unrelated outputs when they have different consumers, retention policies, or iteration cycles. Keep one output when the fields form one stable business record.

3. Choose AI or regex.
   - Use `type: "ai"` for meaning, classification, summarization, sentiment, outcome detection, normalization, or facts expressed in varied language.
   - Use `type: "regex"` only for deterministic transcript matching with a stable pattern. Use RE2-compatible syntax and choose a top-level schema type that matches the documented regex result: boolean, string, number/integer, or array.
   - Do not use regex to infer meaning. Do not use AI when a literal, stable pattern is the entire requirement.

4. Design the smallest useful JSON Schema.
   - Include only fields the caller can provide or the call evidence can support.
   - Add concise descriptions that distinguish semantically similar fields.
   - Use `enum` for a closed category set, `format` or `pattern` for externally validated strings, and numeric bounds when the business contract defines them.
   - Mark a field required only when every valid call should produce it. Make conditionally available values optional instead of forcing guesses.
   - Prefer a primitive schema for a single value and an object only for a cohesive record. Avoid deep nesting unless the downstream contract needs it.
   - Validate the schema with a standard JSON Schema validator before sending it.

5. Create, inspect, or update the definition.
   - Keep saved names betwee

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: create-tool
description: Select, define, create, inspect, update, attach, detach, and verify reusable Vapi tools through the public API. Use for native call-control tools, supported provider integrations, API Request tools, custom function tools, MCP tools, tool messages, credentials, or configuration-preserving assistant attachment changes.
license: MIT
---

# Vapi Tool Management

Choose the documented tool type that directly provides the requested capability. Default to a payload or implementation plan unless the user explicitly requests a live Vapi mutation.

## Safety and Source Rules

- Verify the type and every field against the current [Create Tool API](https://docs.vapi.ai/api-reference/tools/create), public OpenAPI schema, or type-specific public guide before using it.
- Never imitate a documented Vapi capability with a custom function tool.
- Never invent an endpoint, request schema, destination, phone number, assistant ID, tool ID, integration connection, credential, or secret.
- Keep secrets in Vapi credentials or the user's backend. Treat an MCP server URL containing a token as a credential.
- Distinguish tool configuration, assistant attachment, provider connection, and external implementation. They are separate deliverables and success in one does not imply success in another.

## Select the Tool Family

| Need | Select |
|---|---|
| End calls, transfer calls, hand off between assistants, send DTMF or SMS, make a SIP request, or handle voicemail | The matching native Vapi tool |
| Use a publicly documented Google Calendar, Google Sheets, Slack, GoHighLevel, or other supported provider action | The exact integration tool after resolving its connection and required resource |
| Call a known HTTP endpoint with a declarative method, URL, headers, and body | `apiRequest` |
| Send a model-selected function call to custom backend logic that implements Vapi's callback contract | `function` |
| Discover and use tools from an existing MCP server | `mcp` with the default Streamable HTTP transport |

Do not choose `function` merely because the model invokes the capability. Native, integration, API Request, and MCP tools are also model-invoked.

Do not proactively recommend or create a Code Tool (`type: "code"`); it is not generally available on most accounts. Prefer `apiRequest` for a known HTTP endpoint or `function` with the user's `server.url` for user-hosted callback logic. Discuss a Code Tool only when the user explicitly asks about it, and do not present it as the recommended option.

Read [Tool Type Selection](references/tool-types.md) before building a payload. Read only the section for the selected family.

## Procedure

1. Determine the execution mode.
   - Return JSON, code, or a contract when the user asks for a draft or does not clearly authorize a live mutation.
   - Call the Vapi API only when the user explicitly asks to create, update, attach, or detach and `VAPI_API_KEY` is available.
   - If the key is unavailable, return ready artifacts and local commands without asking the user to paste it into chat.

2. Inspect before creating.
   - Use `GET /tool` and match any supplied name and capability to existing tools.
   - Reuse one suitable existing tool when the match is unambiguous and the user does not require a new resource.
   - If several tools plausibly match, ask the user to choose. Never guess an ID.
   - Use `GET /tool/{id}` before updating an existing tool.

3. Resolve the capability and dependencies.
   - Select the tool family using the table above and current public documentation.
   - Resolve every required endpoint, destination, provider connection, calendar, spreadsheet, channel, credential, or MCP server before a live create.
   - If one value blocks a valid tool, show the useful proposed contract first and ask only for that value.

4. Build the smallest valid payload.
   - Give the model a concise, specific description of when to invoke the tool.
   - For types with `function.name`

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 5 — file references are metadata, not package contents.

View saved version →

---
name: setup-api-key
description: Guide users through obtaining and configuring a Vapi API key. Use when the user needs to set up Vapi, when API calls fail due to missing keys, or when the user mentions needing access to Vapi's voice AI platform.
license: MIT
---

# Vapi API Key Setup

Guide the user through obtaining and configuring a Vapi API key for the voice AI platform.

## Workflow

### Step 1: Request the API key

Tell the user:

> To set up Vapi, open the API keys page in the Vapi Dashboard: https://dashboard.vapi.ai/org/api-keys
>
> (Need an account? Create one at https://dashboard.vapi.ai/signup first)
>
> If you don't have an API key yet:
> 1. Click **"Create Key"**
> 2. Name your key (e.g., "development")
> 3. Copy the key immediately — it is only shown once
>
> Do not paste a private API key into this chat. Save it locally using the steps below, then tell me when the file is ready.

Then wait for the user to confirm that the local environment file is ready. Do not ask them to send or display the key.

### Step 2: Validate and configure

Once the user confirms the key is stored locally:

1. **Confirm the key is available without printing it.** Prefer an existing environment variable. Otherwise, ask the user to save it as `VAPI_API_KEY` in a local `.env.local` file using their editor. Never display the file contents.

2. **Validate the key** by making a request from the environment where it is loaded:
   ```bash
    curl -s -o /dev/null -w "%{http_code}" https://api.vapi.ai/assistant \
      -H "Authorization: Bearer $VAPI_API_KEY"
   ```

3. **If validation fails** (non-200 response):
   - Tell the user the API key appears to be invalid
   - Ask them to double-check and try again
   - Remind them of the URL: https://dashboard.vapi.ai/org/api-keys

4. **If validation succeeds**, confirm that the local environment file contains this variable without showing its value:
   ```
   VAPI_API_KEY=<the-api-key>
   ```

5. **Confirm success:**
   > Your Vapi API key is configured locally as `VAPI_API_KEY`.
   >
   > You can now use Vapi's API to create assistants, make calls, and build voice AI agents.
   >
   > Keep this key safe — do not commit it to version control.

### Step 3: Verify .gitignore

Check whether `.gitignore` protects local environment files. If not, add:
```
.env*
!.env.example
```

## Environment Variable

All Vapi skills expect the API key in the `VAPI_API_KEY` environment variable. The base URL for all API requests is:

```
https://api.vapi.ai
```

Authentication is via Bearer token:
```
Authorization: Bearer $VAPI_API_KEY
```

## Additional Resources

Vapi provides a **documentation MCP server** that gives compatible AI agents access to the Vapi knowledge base. Use its documentation search for advanced configuration, troubleshooting, SDK details, and anything beyond this skill.


See the [Vapi MCP integration guide](https://docs.vapi.ai/cli/mcp) for setup instructions across supported agents.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: setup-webhook
description: Configure Vapi server URLs and webhooks to receive real-time call events, transcripts, tool calls, and end-of-call reports. Use when setting up webhook endpoints, building tool servers, or integrating Vapi events into your application.
license: MIT
---

# Vapi Webhook / Server URL Setup

Configure server URLs to receive real-time events from Vapi during calls — transcripts, tool calls, status changes, and end-of-call reports.

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

## Overview

Vapi uses "Server URLs" (webhooks) to communicate with your application. Unlike traditional one-way webhooks, Vapi server URLs support bidirectional communication — your server can respond with data that affects the call.

## Where to Set Server URLs

### On an Assistant

```bash
curl -X PATCH https://api.vapi.ai/assistant/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "url": "https://your-server.com/vapi/webhook",
      "credentialId": "cred_abc123"
    }
  }'
```

Create the optional `credentialId` in **Dashboard > Custom Credentials**. Omit it only for a deliberately public endpoint.

### On a Phone Number

Phone-number updates also use a `server` object with `url` and optional `credentialId`. When updating through the API, first retrieve the number and preserve its existing `provider` discriminator in the PATCH body. The dashboard is the safest choice when the provider is unknown.

### At the Organization Level

Set a default server URL in the Vapi Dashboard under **Settings > Server URL**.

Priority order: Tool server URL > Assistant server URL > Phone Number server URL > Organization server URL.

## Event Types

| Event | Description | Expects Response? |
|-------|-------------|-------------------|
| `assistant-request` | Request for dynamic assistant config | Yes — return assistant config |
| `tool-calls` | Assistant is calling a tool | Yes — return tool results |
| `status-update` | Call status changed | No |
| `transcript` | Real-time transcript update | No |
| `end-of-call-report` | Call completed with summary | No |
| `hang` | Assistant failed to respond | No |
| `speech-update` | Speech activity detected | No |

## Webhook Server Example (Express.js)

```typescript
import express from "express";
const app = express();
app.use(express.json());

app.post("/vapi/webhook", (req, res) => {
  const { message } = req.body;

  switch (message.type) {
    case "assistant-request":
      // Dynamically configure the assistant based on the caller
      res.json({
        assistant: {
          name: "Dynamic Assistant",
          firstMessage: `Hello ${message.call.customer?.name || "there"}!`,
          model: {
            provider: "openai",
            model: "gpt-4.1",
            messages: [
              { role: "system", content: "You are a helpful assistant." },
            ],
          },
          voice: { provider: "vapi", voiceId: "Elliot", version: 2 },
          transcriber: { provider: "deepgram", model: "nova-3", language: "en" },
        },
      });
      break;

    case "tool-calls":
      // Handle tool calls from the assistant
      const results = (message.toolCallList || []).map((toolCall: any) => ({
        toolCallId: toolCall.id,
        result: handleToolCall(
          toolCall.name,
          toolCall.parameters || toolCall.arguments
        ),
      }));
      res.json({ results });
      break;

    case "end-of-call-report":
      // Process the call report
      console.log("Call ended:", {
        callId: message.call.id,
        endedReason: message.endedReason,
        cost: message.cost,
        analysis: message.analysis,
        artifact: message.artifact,
      });
      res.json({});
      break;

    case "status-update":
      console.log("Call status:", message.status);
      res.json({});
      break;

    case "transcript":
      console.log(`[${mess

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: simulations
description: Design, create, run, monitor, and maintain Vapi Simulations for assistants and squads. Use for simulation personalities, scenarios, structured-output success criteria, simulations, suites, chat or voice runs, tool mocks, target variables, lifecycle webhooks, regression coverage, CI quality gates, run-result analysis, and simulation API validation errors. Do not use for fixed-turn mock-conversation Evals unless the user is deciding between Evals and Simulations.
license: MIT
---

# Vapi Simulations

Build realistic conversation tests in five layers: a personality controls the AI tester, a scenario defines its intent and measurable outcomes, a simulation pairs them, a suite groups simulations, and a run executes them against an assistant or squad.

## Source and Safety Rules

- Verify live payloads against the current Vapi documentation MCP, API reference, or public OpenAPI before sending them. Simulations use the `/eval/simulation` API family.
- Never print, request in chat, or embed API keys, provider secrets, credential values, private webhook URLs, or real customer data.
- Treat running a simulation as an external action. It can consume credits, use concurrency, send webhooks, and call the target's real tools unless they are mocked.
- Do not run, cancel, update, or delete resources unless the user clearly requests that operation. Draft configurations when mutation is not requested.
- Resolve every assistant, squad, personality, scenario, simulation, suite, tool, structured-output, and credential ID from user input or the API. Never invent an ID.
- Do not create legacy Test Suites. Use Evals for deterministic turn-by-turn checks and Simulations for dynamic conversations over chat or voice.

## Procedure

1. Choose the test type and execution mode.
   - Use Simulations for multi-turn behavior, personality variation, squad handoffs, realistic tool paths, or audio behavior.
   - Use Evals instead when the requirement is an exact response, regex, fixed mock conversation, or precise tool-call argument check.
   - Return a test plan or payload when the user asks to design, draft, review, or explain. Perform live mutations only when explicitly requested and `VAPI_API_KEY` is available.

2. Inspect the target and existing test resources.
   - Fetch the assistant or squad and identify its core paths, guardrails, tools, variables, languages, and failure behavior.
   - List existing personalities, scenarios, simulations, suites, and reusable structured outputs before creating duplicates.
   - Reuse an existing resource only when its intent and configuration match unambiguously. Otherwise create a clearly named new resource or ask the user to choose among plausible matches.

3. Design coverage before payloads.
   - Start with one smoke simulation for the core path, one or two required Boolean outcomes, chat transport, and one iteration.
   - Add regression simulations for repaired defects. Add separate edge cases for ambiguity, interruption, refusal, unavailable dependencies, failed tools, escalation, and handoffs.
   - Keep scenario intent, personality behavior, and evaluation criteria independent so each can be reused.
   - Name resources by behavior and expected outcome, not implementation details.

4. Define the personality.
   - Prefer a suitable existing personality when available.
   - When creating one, provide a complete valid assistant configuration for the AI tester. Put stable temperament, speaking style, and caller behavior in its system prompt; put the situation-specific goal in the scenario.
   - Use the `create-assistant` skill to assemble or validate the personality's assistant configuration when available.
   - Configure voice and transcriber only when voice runs need them. Chat runs use the personality's model but skip its audio path.

5. Define the scenario and evaluations.
   - Write `instructions` as the AI tester's intent and facts. Describe the goal and constraints without script

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: vapi-prompt-builder
description: Create, improve, or audit Vapi voice agent and Squad system prompts for production phone and web based voice agents. Use when the user wants help designing a Vapi assistant prompt, multi-assistant Squad prompt set, refining an existing prompt, creating prompt sections, building an intake or handoff workflow, improving tool-use instructions, adding guardrails, or optimizing voice-agent behavior for brevity, turn-taking, error handling, caller data collection, escalation, handoffs, and spoken formatting.
license: MIT
---

# Vapi Prompt Builder

## Core Workflow

Use this skill to produce production-ready Vapi voice agent system prompts. Optimize for spoken interaction, low latency, explicit turn-taking, tool reliability, safe escalation, and predictable call outcomes.

Start by classifying the request:

- Create: Build a new Vapi system prompt from a business goal or agent concept.
- Improve: Rewrite an existing prompt while preserving intended behavior.
- Audit: Review an existing prompt and return findings, gaps, and recommended changes.

Then resolve deployment shape:

- Single assistant: one Vapi assistant owns the call flow.
- Squad: multiple specialized assistants hand off between each other.

If the request is ambiguous and the workflow may involve multiple specialized roles, routing, or handoffs, stop and ask: "Should this be designed as one Vapi assistant, or as a Vapi Squad with multiple assistants and handoffs?" Do not draft until this is resolved.

Read `references/squad-prompting.md` when the user mentions squads, Handoff Tools, handoffs between assistants or squads, silent handoffs, dynamic routing, router/triage assistants, specialist assistants, or a workflow that is too broad for one reliable prompt.

Before writing or preserving workflow details, run a capability-grounding pass. Verify that every claimed input, artifact, tool action, side effect, and example is possible through the actual call channel, runtime context, visible Vapi tools, or explicitly described backend behavior. Read `references/capability-grounding.md` when the prompt mentions files, uploads, attachments, documents, screenshots, browser/web actions, async jobs, integrations, or any action the phone caller cannot perform directly during the call.

Read `references/voice-prompt-patterns.md` when creating or substantially rewriting a prompt, or when the request involves voice style, examples, tool behavior, information collection, or call endings.

Run an identifier-hygiene pass before finalizing. Read `references/identifier-hygiene.md` when the prompt uses tool names, resource IDs, snake_case identifiers, placeholder names, or generic values such as `the_tool_name`.

Run a Vapi trust-boundary pass when the prompt, tools, or configuration mention authentication, caller identity, account IDs, permissions, secrets, secure values, verified values, static parameters, `function.parameters`, dynamic variables, `variableExtractionPlan`, tool aliases, handoff arguments, or sensitive tool responses. Read `references/vapi-security-trust.md` before recommending where those values belong.

Run a Vapi readiness pass before presenting an artifact as ready to build or configure. Read `references/vapi-readiness.md` when the output includes tools, structured outputs, dynamic variables, Squads, handoffs, pronunciation guidance, testing/evals, or configuration notes. Separate confirmed Vapi configuration from assumptions and missing deployment inputs.

## Intake

Ask the fewest questions needed to make a useful first draft. Prefer a complete draft with clear assumptions over a long upfront questionnaire.

Always collect or infer:

- Business or use case
- Deployment shape: single assistant or Squad
- Agent role and call objective
- Caller type and likely intents
- Success criteria
- Required workflows
- Handoff/routing boundaries when using a Squad
- Tools or actions the agent can use
- Tool schemas, structured outputs, a

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 9 — file references are metadata, not package contents.