Non-obvious behaviors, proven recipes, and troubleshooting guides for the Vapi platform. This is a companion to the API reference — it covers what the docs don't tell you.
Each file targets a specific topic so you can load only the context you need.
| If you're working on... | Read this |
|---|---|
| Creating or editing an assistant | assistants.md |
| Configuring tools (apiRequest, function, transferCall, handoff, code, endCall) | tools.md |
| Setting up a squad / multi-agent handoffs | squads.md |
| Transfers not working | transfers.md |
| Structured outputs or post-call analysis | structured-outputs.md |
| Writing simulations or test suites | simulations.md |
| Webhook / server configuration | webhooks.md |
| Making your agent faster | latency.md |
| Adding fallback providers (transcriber, voice, error hooks) | fallbacks.md |
| Using your own Azure OpenAI credentials with regional failover | azure-openai-fallback.md |
| Building a multilingual agent (English/Spanish, language switching) | multilingual.md |
| Streaming audio via WebSocket transport | websocket.md |
| Building an outbound calling agent | outbound-agents.md |
| Bulk-dialing from a CSV (Outbound Call Campaigns) | outbound-campaigns.md |
| Voicemail detection / VM vs human classification | voicemail-detection.md |
| Enforcing call time limits / graceful call ending | call-duration.md |
| Voice provider field cheat-sheet (Cartesia vs 11labs vs others) | voice-providers.md |
| YAML authoring conventions, .vapi-ignore lifecycle | yaml-conventions.md |
Centralizing repeated values with {{variables}} |
variables.md |
| What will pull/push/apply do in situation X? | sync-behavior.md |
Gotchas and silent defaults for each resource type:
| File | What it covers |
|---|---|
| tools.md | apiRequest, function, transferCall, endCall, handoff, voicemail, dtmf, code tools; tool messages; strict mode |
| assistants.md | Model defaults, voice, transcriber, firstMessage, outbound modes, voicemailMessage, hooks, idle messages, endpointing, interruption, analysis, artifacts, background sound, server messages, HIPAA, tool resolution |
| squads.md | Name uniqueness, tools:append, assistantDestinations, handoff context, contextEngineeringPlan, VM detection relay pattern, override merge order, membersOverrides structuredDataPlan + fullMessageHistory |
| structured-outputs.md | Schema type gotchas, assistant_ids, default models, target modes, KPI patterns, squad membersOverrides vs standalone SOs |
| simulations.md | Personalities, evaluation comparators, chat-mode gotcha, missing references, full /eval/simulation/* API reference |
| webhooks.md | Default server messages, timeouts, unreachable servers, credential resolution, payload shape |
| voice-providers.md | Per-provider voice block layout (Cartesia vs 11labs vs OpenAI/Azure/Rime/LMNT/Minimax/Neuphonic/SmallestAI) — saves 400s at push time |
Step-by-step diagnostic guides for common problems:
| File | What it covers |
|---|---|
| transfers.md | Transfers not working: LLM not calling tool, wrong tool type, telephony failures, transient assistant issues |
| voicemail-detection.md | Voicemail vs human classification, detection priority hierarchy, trigger phrases, false positives, beep detection, testing matrix |
Proven patterns and setup guides:
| File | What it covers |
|---|---|
| outbound-agents.md | Outbound agent design, IVR navigation (DTMF), opening statements, identity handling, pacing, conversation flow, metrics |
| outbound-campaigns.md | Outbound Call Campaigns feature: CSV format, dynamic variables (extra columns → variableValues), concurrency, scheduling, completion semantics |
| latency.md | Pipeline latency budget, quick-win matrix, iron triangle, model selection, prompt optimization, endpointing tuning |
| fallbacks.md | Error-handling hooks, endedReason filters, transcriber/voice fallback chains, phone number fallback |
| azure-openai-fallback.md | BYOK Azure OpenAI multi-region setup, credential isolation, region pinning, runtime failover behavior |
| multilingual.md | Three approaches to multilingual agents, provider recommendations, tool message patterns, common pitfalls |
| websocket.md | Audio formats, timing rules, silence values, control messages, connection management, error codes |
| call-duration.md | Call time limits, maxDurationSeconds, call.timeElapsed hooks, graceful shutdown recipes, wrap-up patterns |
How the gitops sync engine itself behaves:
| File | What it covers |
|---|---|
| sync-behavior.md | The full pull/push/apply scenario matrix: state file vs hash-store baseline vs dashboard, drift directions (clean / local-ahead / dashboard-ahead / both-diverged), per-resource conflict prompt, existence cases (local-only file, dashboard-only resource, deletions either side, fresh clone, renames, legacy-state migration), .bkp backup copies, flag cheat sheet |
| yaml-conventions.md | YAML authoring conventions, .vapi-ignore lifecycle |
| variables.md | Managed {{variables}} in the state file: whole-value substitution at push, placeholder restoration at pull, type preservation, drift-stays-clean, validation of undefined names |