Create Assistant

Create a new AI voice assistant. The assistant is automatically synced to the voice engine on creation.

Endpoint

POST /v1/assistants/

Request Body

Core

name

string

required

Assistant name (max 255 characters)

description

string

Assistant description

system_prompt

string

System instructions for the assistant

model

object

LLM configuration

provider — openai, google, groq, or custom
model — Model name (gpt-4o, llama-3, etc.)
temperature — Creativity (0-1)
max_tokens — Max response length
system_prompt — System instructions (inline override)
url and server_credential_id — required as appropriate for custom
fallback_providers — ordered fallback model configurations

voice

object

Voice (TTS) configuration

provider — 11labs/elevenlabs, spitch, inworld, fishaudio, deepgram, groq, cartesia, or custom
voice_id — Specific voice ID
language — Voice language
speed — Speaking rate
fallback_providers — ordered fallback voice configurations

transcriber

object

Transcriber (STT) configuration

provider — deepgram, 11labs/elevenlabs, spitch, or custom
model — Recognition model
language — Expected language
vocabulary — Optional array of special terms
fallback_providers — ordered fallback transcriber configurations

Provider configuration

The API uses the provider IDs above. 11labs and elevenlabs are equivalent voice and transcription aliases. A custom provider uses url (or base_url) and may reference server_credential_id; custom STT/TTS also accepts a protocol appropriate to the endpoint. fallback_providers is an ordered array. The runtime uses the primary configuration first and tries each fallback in sequence. Each fallback is a component-specific object, for example:

{
  "model": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "fallback_providers": [{ "provider": "groq", "model": "llama-3.1-8b-instant" }]
  },
  "voice": {
    "provider": "11labs",
    "voice_id": "VOICE_ID",
    "fallback_providers": [{ "provider": "cartesia", "voice_id": "VOICE_ID", "language": "en" }]
  }
}

Transcription vocabulary

Send transcriber.vocabulary as an array of strings. Empty and duplicate terms are removed before use.

Provider	Forwarding behavior
`spitch`	Special words
`deepgram`	Keyterms for Nova 3/Flux; boosted keywords for other models; first 100 terms
`11labs` / `elevenlabs`	Scribe v2 Realtime keyterms; first 50 terms of at most 20 characters
`custom` using OpenAI protocol	Transcription context; other custom protocols may ignore it

Messages

first_message

string

Opening greeting when the assistant picks up (text or URL to an audio file)

first_message_mode

string

default:"assistant-speaks-first"

assistant-speaks-first, assistant-waits-for-user, or user-speaks-first

first_message_interruptions_enabled

boolean

default:"true"

Whether the user can interrupt the first message

end_call_message

string

Message the assistant plays when ending the call

end_call_phrases

array

Phrases that trigger an early call end (case-insensitive), e.g. ["goodbye", "bye"]

voicemail_message

string

Message played if the call is forwarded to voicemail

Detection & Limits

voicemail_detection

object

Voicemail detection configuration (enabled, provider, thresholds)

max_duration_seconds

number

default:"600"

Maximum call duration in seconds (default 10 minutes)

silence_timeout_seconds

number

default:"30"

How long to wait before a call is automatically ended due to inactivity

Audio

background_sound

string

default:"office"

Background sound: office, off, or a custom URL

background_sound_volume

number

default:"0.8"

Background sound playback volume (0.0–1.0)

model_output_in_messages_enabled

boolean

default:"false"

Use model output in conversation history instead of transcription

audio_recording_enabled

boolean

default:"false"

Enable audio recording for calls

Post-call Analysis

summary_enabled

boolean

default:"false"

Enable post-call summary generation

analysis_enabled

boolean

default:"false"

Enable the post-call analysis pipeline

analysis_profile_id

string

Analysis profile UUID to use (null = organization default)

analysis_plan

object

Analysis plan configuration: summary, structuredData, successEvaluation. It may produce a summary, extracted structured data, and a success evaluation after a call.

Plans

artifact_plan

object

Artifact generation plan configuration

start_speaking_plan

object

Reply endpointing plan. Use turn_detection_mode (audio or vad), optional turn_detector_version (v1 or v1-mini), wait_seconds, and smart_endpointing_mode (off or livekit).

stop_speaking_plan

object

Interruption plan: num_words, voice_seconds, and optional backoff_seconds.

Voice behavior

voice.character_profile accepts neutral, warm_host, calm_professional, playful_guide, empathetic_support, or confident_expert. For supported expressive TTS, voice.expressive_delivery accepts enabled, style (restrained, warm, or playful), speech_steering.pace (slow, normal, or fast), speech_steering.disfluencies, speech_steering.nonverbal_sounds, and tts_instructions_append (maximum 4,000 characters). Sensitive, financial, health, safety, legal, error, and complaint contexts remain restrained. voice.backchanneling controls audio-only listener acknowledgements:

{
  "backchanneling": {
    "enabled": true,
    "frequency": "natural",
    "cues": ["mhm", "yeah", "right", "okay", "i-see"]
  }
}

frequency is minimal, natural, or expressive. Backchannel cues are never added to transcripts or LLM context.

monitor_plan

object

Real-time monitoring plan (listen, control)

avatar_behavior_profile

object

Avatar behavior controls and portable runtime hints (emotional_tone, animation, etc.)

background_speech_denoising_plan

object

Background speech denoising configuration (Krisp, Fourier)

keypad_input_plan

object

Keypad (DTMF) input handling configuration

observability_plan

object

Observability plan (e.g. Langfuse tracing integration)

Compliance

compliance_plan

object

Compliance controls enforced at runtime. The plan is inert unless enabled is true.

Section	Type	Description
`enabled`	boolean	Master switch — plan is ignored unless `true`
`ai_disclosure`	object	AI disclosure statement read at the start of every call
`recording_consent`	object	Verbal recording consent gate (see below)
`transcript_retention`	object	Whether transcripts are stored after the call
`sensitive_data`	object	PII redaction filters (see below)
`audio_redaction`	object	PII redaction controls for recorded call audio

ai_disclosure

Field	Type	Default	Description
`enabled`	boolean	`true`	If `false`, no disclosure is spoken
`message`	string	`You are speaking with an AI assistant.`	Disclosure text (max 500 chars)

recording_consent

Field	Type	Default	Description
`enabled`	boolean	`false`	If `false`, no consent gate runs
`message`	string	`This conversation may be recorded. Do you agree?`	Consent question (max 500 chars)
`accepted_responses`	array	`["yes", "i agree", "okay", "continue"]`	Phrases treated as consent (max 10, 100 chars each)
`declined_responses`	array	`["no", "i do not agree", "do not record"]`	Phrases treated as refusal (max 10)
`max_attempts`	integer	`2`	How many times the question is asked (1–3, validated)
`end_call_on_decline`	boolean	`false`	End the call immediately when consent is declined

The gate listens for the user’s verbal answer (12s timeout per attempt). Declined consent blocks audio recording and is persisted to the session compliance snapshot. transcript_retention

Field	Type	Default	Description
`enabled`	boolean	`true`	If `false`, transcripts are not persisted and event payloads are redacted

sensitive_data

Field	Type	Default	Description
`enabled`	boolean	`true`	If `false`, redaction filters are disabled
`categories`	array	all supported categories	PII groups to redact
`custom_patterns`	array	`[]`	Custom regex patterns (max 10, 200 chars each)

Supported categories are financial, credentials, government_identifiers, contact, names, locations, personal_profile, and telecom_identifiers. When enabled, transcripts, chat context, collected data, summaries, messages, and stored text artifacts are redacted. Redacted values become [REDACTED]. audio_redaction

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable post-call PII bleeping for recordings
`retain_redacted_only`	boolean	`true`	Must be `true` when supplied; raw audio is quarantined until redaction completes
`categories`	array	`[]`	Supported PII categories to bleep

Audio-redaction processing is fail-closed: if enabled recording redaction cannot complete, the recording is not released as a normal artifact.

"compliance_plan": {
  "enabled": true,
  "ai_disclosure": {
    "enabled": true,
    "message": "This call may be recorded for quality and training purposes."
  },
  "recording_consent": {
    "enabled": true,
    "message": "Do you agree to this conversation being recorded?",
    "accepted_responses": ["yes", "i agree", "okay", "continue"],
    "declined_responses": ["no", "i do not agree", "do not record"],
    "max_attempts": 2,
    "end_call_on_decline": true
  },
  "transcript_retention": {
    "enabled": false
  },
  "sensitive_data": {
    "enabled": true,
    "categories": ["financial", "credentials", "government_identifiers", "contact"],
    "custom_patterns": ["\\bACC-\\d{6}\\b"]
  },
  "audio_redaction": {
    "enabled": true,
    "retain_redacted_only": true,
    "categories": ["financial", "credentials"]
  }
}

Data Collection

data_collection

object

Structured data collection configuration.

Field	Type	Description
`enabled`	boolean	Master switch
`mode`	string	`task_group` — fields are collected in a fixed group at session start; `function_tool` — each field becomes a tool the LLM calls mid-conversation
`collections`	array	Per-field definitions (see below)

Collection item

Field	Type	Description
`name`	string	Field name; used as the stored variable key
`type`	string	Prebuilt task type (see below) or `custom`
`description`	string	Prompt shown to the user when asking for the field
`required`	boolean	If `false`, the field is optional
`config`	object	Prebuilt task-specific options (e.g. DTMF digits)

Field types: name, email, phone, address, dob, credit_card, dtmf, custom.

dtmf — keypad capture; config supports num_digits, dtmf_input_timeout, dtmf_stop_event
custom — a plain conversational question; the transcript answer is stored

"data_collection": {
  "enabled": true,
  "mode": "task_group",
  "collections": [
    {
      "name": "full_name",
      "type": "name",
      "description": "What is your full name?",
      "required": true
    },
    {
      "name": "email",
      "type": "email",
      "description": "What email should we send the receipt to?",
      "required": true
    },
    {
      "name": "marketing_opt_in",
      "type": "custom",
      "description": "Would you like to receive marketing updates?",
      "required": false
    }
  ]
}

Transport & Integration

transport_configurations

array

Transport provider configurations (e.g. Twilio)

credentials

array

Inline dynamic credentials for calls, e.g. [{ "provider": "openai", "api_key": "sk-..." }]

credential_ids

array

Vapi credential UUIDs to use for provider authentication (e.g. your own OpenAI or ElevenLabs API key). Create credentials via the Server Credentials API.

hooks

array

Event hooks configuration

server

object

Assistant callback configuration. This is separate from organization outbound webhook subscriptions.

url — Callback URL for call events
timeout — Request timeout in seconds
secret — HMAC signing secret for payload verification

Messages & Metadata

client_messages

array

Messages sent to Client SDKs (e.g. transcript, hang, status-update, speech-update)

server_messages

array

Events sent to the assistant server.url: status-update, call.started, assistant.started, call.ended, end-of-call-report, and error.

See Webhook event contracts for envelopes and field availability.

metadata

object

Custom key-value metadata for the assistant

Squad & Attachments

squad_id

string

Squad UUID this assistant belongs to

squad_role

string

Squad role: primary, fallback, or specialist

file_ids

array

UUIDs of knowledge-base files associated with this assistant

tool_ids

array

IDs of tools associated with this assistant

Example Request

Standard Provider (OpenAI LLM + ElevenLabs Voice + Deepgram STT)

curl -X POST https://api.vonative.com/v1/assistants/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "temperature": 0.7,
      "max_tokens": 250,
      "system_prompt": "You are a helpful customer support agent."
    },
    "voice": {
      "provider": "11labs",
      "voice_id": "21m00Tcm4TlvDq8ikWAM"
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-2",
      "language": "en"
    },
    "first_message": "Hello! How can I help you today?",
    "first_message_mode": "assistant-speaks-first"
  }'

Custom Provider (Spitch Voice + Spitch STT + BYO Credentials)

Spitch is routed through the platform; set its provider name, voice ID, and language. Use credential_ids to pass provider credentials without exposing keys in client-side code.

curl -X POST https://api.vonative.com/v1/assistants/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Yorùbá Support Agent",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "temperature": 0.7,
      "max_tokens": 250,
      "system_prompt": "You are a customer support agent that speaks Yorùbá."
    },
    "voice": {
      "provider": "spitch",
      "voice_id": "lina",
      "language": "yo"
    },
    "transcriber": {
      "provider": "spitch",
      "language": "yo"
    },
    "credential_ids": [
      "vapi-cred-uuid-1111",
      "vapi-cred-uuid-2222"
    ],
    "first_message": "Bawo ni mo se le ran e lọwọ loni?",
    "first_message_mode": "assistant-speaks-first"
  }'

Custom LLM Endpoint

Use a custom OpenAI-compatible endpoint by passing inline credentials:

curl -X POST https://api.vonative.com/v1/assistants/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom LLM Assistant",
    "model": {
      "provider": "custom",
      "model": "gpt-4o-mini",
      "url": "https://llm.example.com/v1",
      "temperature": 0.7,
      "max_tokens": 250,
      "system_prompt": "You are a helpful assistant."
    },
    "voice": {
      "provider": "11labs",
      "voice_id": "21m00Tcm4TlvDq8ikWAM"
    },
    "transcriber": {
      "provider": "deepgram",
      "model": "nova-2",
      "language": "en"
    },
    "credentials": [
      {
        "provider": "openai",
        "api_key": "sk-your-openai-key"
      }
    ],
    "first_message": "Hello! How can I help you today?"
  }'

Compliant, Data-Collecting Assistant

curl -X POST https://api.vonative.com/v1/assistants/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compliant Intake Agent",
    "model": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "temperature": 0.4
    },
    "voice": {
      "provider": "spitch",
      "voice_id": "funmi",
      "language": "yo"
    },
    "transcriber": {
      "provider": "spitch",
      "language": "yo"
    },
    "compliance_plan": {
      "enabled": true,
      "ai_disclosure": { "message": "This call is recorded for training purposes." },
      "recording_consent": { "enabled": true, "end_call_on_decline": true },
      "transcript_retention": { "enabled": true },
      "sensitive_data": { "enabled": true }
    },
    "data_collection": {
      "enabled": true,
      "mode": "task_group",
      "collections": [
        { "name": "email", "type": "email", "required": true },
        { "name": "phone", "type": "phone", "required": true }
      ]
    },
    "audio_recording_enabled": true,
    "summary_enabled": true,
    "analysis_enabled": true
  }'

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Customer Support Bot",
    "description": null,
    "system_prompt": "You are a helpful customer support agent.",
    "model": {},
    "voice": {},
    "transcriber": {},
    "first_message": "Hello! How can I help you today?",
    "first_message_mode": "assistant-speaks-first",
    "first_message_interruptions_enabled": true,
    "end_call_message": null,
    "end_call_phrases": [],
    "voicemail_message": null,
    "voicemail_detection": null,
    "max_duration_seconds": 600,
    "silence_timeout_seconds": 30,
    "background_sound": "office",
    "background_sound_url": null,
    "background_sound_volume": 0.8,
    "model_output_in_messages_enabled": false,
    "audio_recording_enabled": false,
    "summary_enabled": false,
    "analysis_enabled": false,
    "analysis_profile_id": null,
    "analysis_plan": null,
    "artifact_plan": null,
    "start_speaking_plan": null,
    "stop_speaking_plan": null,
    "monitor_plan": null,
    "compliance_plan": null,
    "avatar_behavior_profile": null,
    "background_speech_denoising_plan": null,
    "keypad_input_plan": null,
    "observability_plan": null,
    "transport_configurations": [],
    "credentials": [],
    "credential_ids": [],
    "hooks": [],
    "server": null,
    "client_messages": [],
    "server_messages": [],
    "metadata_json": {},
    "squad_id": null,
    "squad_role": null,
    "file_ids": [],
    "tool_ids": [],
    "data_collection": null,
    "vapi_assistant_id": null,
    "status": "draft",
    "organization_id": "org-uuid-1234",
    "owner_id": "user-uuid-5678",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Authentication

Introduction

Assistants

Phone Numbers

Workflows

Calls

Meets

Files

Tools

Server Credentials

Sessions

Call Logs

Webhooks

Campaigns

Create Assistant

Create Assistant

Endpoint

Request Body

Core

Provider configuration

Transcription vocabulary

Messages

Detection & Limits

Audio

Post-call Analysis

Plans

Voice behavior

Compliance

Data Collection

Transport & Integration

Messages & Metadata

Squad & Attachments

Example Request

Standard Provider (OpenAI LLM + ElevenLabs Voice + Deepgram STT)

Custom Provider (Spitch Voice + Spitch STT + BYO Credentials)

Custom LLM Endpoint

Compliant, Data-Collecting Assistant

Response

​Create Assistant

​Endpoint

​Request Body

​Core

​Provider configuration

​Transcription vocabulary

​Messages

​Detection & Limits

​Audio

​Post-call Analysis

​Plans

​Voice behavior

​Compliance

​Data Collection

​Transport & Integration

​Messages & Metadata

​Squad & Attachments

​Example Request

​Standard Provider (OpenAI LLM + ElevenLabs Voice + Deepgram STT)

​Custom Provider (Spitch Voice + Spitch STT + BYO Credentials)

​Custom LLM Endpoint

​Compliant, Data-Collecting Assistant

​Response

Create Assistant

Endpoint

Request Body

Core

Provider configuration

Transcription vocabulary

Messages

Detection & Limits

Audio

Post-call Analysis

Plans

Voice behavior

Compliance

Data Collection

Transport & Integration

Messages & Metadata

Squad & Attachments

Example Request

Standard Provider (OpenAI LLM + ElevenLabs Voice + Deepgram STT)

Custom Provider (Spitch Voice + Spitch STT + BYO Credentials)

Custom LLM Endpoint

Compliant, Data-Collecting Assistant

Response