Create Assistant

POST

assistant

object

transcriber

DeepgramTranscriber · object

provider

enum<string>

model

enum<string>

language

enum<string>

smartFormat

boolean

keywords

array

model

AnyscaleModel · object

messages

array

tools

array

toolIds

array

provider

enum<string>

model

string

temperature

number

knowledgeBase

object

provider

enum<string>

topK

number

fileIds

array

maxTokens

number

emotionRecognitionEnabled

boolean

voice

AzureVoice · object

inputPreprocessingEnabled

boolean

inputReformattingEnabled

boolean

inputMinCharacters

number

inputPunctuationBoundaries

array

fillerInjectionEnabled

boolean

provider

enum<string>

voiceId

Preset Voice Options · enum<string>

speed

number

firstMessageMode

enum<string>

recordingEnabled

boolean

hipaaEnabled

boolean

clientMessages

array

serverMessages

array

silenceTimeoutSeconds

number

responseDelaySeconds

number

llmRequestDelaySeconds

number

numWordsToInterruptAssistant

number

maxDurationSeconds

number

backgroundSound

enum<string>

backchannelingEnabled

boolean

backgroundDenoisingEnabled

boolean

modelOutputInMessagesEnabled

boolean

name

string

firstMessage

string

voicemailDetection

object

provider

enum<string>

voicemailDetectionTypes

array

enabled

boolean

machineDetectionTimeout

number

machineDetectionSpeechThreshold

number

machineDetectionSpeechEndThreshold

number

machineDetectionSilenceTimeout

number

voicemailMessage

string

endCallMessage

string

endCallPhrases

array

metadata

object

serverUrl

string

serverUrlSecret

string

analysisPlan

object

summaryPrompt

string

summaryRequestTimeoutSeconds

number

structuredDataRequestTimeoutSeconds

number

successEvaluationPrompt

string

successEvaluationRubric

enum<string>

successEvaluationRequestTimeoutSeconds

number

structuredDataPrompt

string

structuredDataSchema

object

type

enum<string>

items

object

properties

object

description

string

required

array

artifactPlan

object

videoRecordingEnabled

boolean

messagePlan

object

idleMessages

array

idleMessageMaxSpokenCount

number

idleTimeoutSeconds

number

curl --request POST \
  --url https://api.vapi.ai/assistant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2",
    "language": "bg",
    "smartFormat": true,
    "keywords": [
      "<string>"
    ]
  },
  "model": {
    "messages": [
      {
        "content": "<string>",
        "role": "assistant"
      }
    ],
    "tools": [
      {
        "async": true,
        "messages": [
          {
            "type": "request-start",
            "content": "<string>",
            "conditions": [
              {
                "param": "<string>",
                "value": "<string>",
                "operator": "eq"
              }
            ]
          }
        ],
        "type": "dtmf",
        "function": {
          "name": "<string>",
          "description": "<string>",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": [
              "<string>"
            ]
          }
        },
        "server": {
          "timeoutSeconds": 20,
          "url": "<string>",
          "secret": "<string>"
        }
      }
    ],
    "toolIds": [
      "<string>"
    ],
    "provider": "anyscale",
    "model": "<string>",
    "temperature": 1,
    "knowledgeBase": {
      "provider": "canonical",
      "topK": 5.5,
      "fileIds": [
        "<string>"
      ]
    },
    "maxTokens": 525,
    "emotionRecognitionEnabled": true
  },
  "voice": {
    "inputPreprocessingEnabled": true,
    "inputReformattingEnabled": true,
    "inputMinCharacters": 30,
    "inputPunctuationBoundaries": [
      "。",
      "，",
      ".",
      "!",
      "?",
      ";",
      ")",
      "،",
      "۔",
      "।",
      "॥",
      "|",
      "||",
      ",",
      ":"
    ],
    "fillerInjectionEnabled": true,
    "provider": "azure",
    "voiceId": "andrew",
    "speed": 1.25
  },
  "firstMessageMode": "assistant-speaks-first",
  "recordingEnabled": true,
  "hipaaEnabled": true,
  "clientMessages": [
    "conversation-update",
    "function-call",
    "hang",
    "model-output",
    "speech-update",
    "status-update",
    "transcript",
    "tool-calls",
    "user-interrupted",
    "voice-input"
  ],
  "serverMessages": [
    "conversation-update",
    "end-of-call-report",
    "function-call",
    "hang",
    "speech-update",
    "status-update",
    "tool-calls",
    "transfer-destination-request",
    "user-interrupted"
  ],
  "silenceTimeoutSeconds": 30,
  "responseDelaySeconds": 0.4,
  "llmRequestDelaySeconds": 0.1,
  "numWordsToInterruptAssistant": 5,
  "maxDurationSeconds": 1800,
  "backgroundSound": "office",
  "backchannelingEnabled": true,
  "backgroundDenoisingEnabled": true,
  "modelOutputInMessagesEnabled": true,
  "name": "<string>",
  "firstMessage": "<string>",
  "voicemailDetection": {
    "provider": "twilio",
    "voicemailDetectionTypes": [
      "machine_end_beep",
      "machine_end_silence"
    ],
    "enabled": true,
    "machineDetectionTimeout": 31,
    "machineDetectionSpeechThreshold": 3500,
    "machineDetectionSpeechEndThreshold": 2750,
    "machineDetectionSilenceTimeout": 6000
  },
  "voicemailMessage": "<string>",
  "endCallMessage": "<string>",
  "endCallPhrases": [
    "<string>"
  ],
  "metadata": {},
  "serverUrl": "<string>",
  "serverUrlSecret": "<string>",
  "analysisPlan": {
    "summaryPrompt": "<string>",
    "summaryRequestTimeoutSeconds": 10.5,
    "structuredDataRequestTimeoutSeconds": 10.5,
    "successEvaluationPrompt": "<string>",
    "successEvaluationRubric": "NumericScale",
    "successEvaluationRequestTimeoutSeconds": 10.5,
    "structuredDataPrompt": "<string>",
    "structuredDataSchema": {
      "type": "string",
      "items": {},
      "properties": {},
      "description": "<string>",
      "required": [
        "<string>"
      ]
    }
  },
  "artifactPlan": {
    "videoRecordingEnabled": true
  },
  "messagePlan": {
    "idleMessages": [
      "<string>"
    ],
    "idleMessageMaxSpokenCount": 5.5,
    "idleTimeoutSeconds": 7.5
  }
}'

{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2",
    "language": "bg",
    "smartFormat": true,
    "keywords": [
      "<string>"
    ]
  },
  "model": {
    "messages": [
      {
        "content": "<string>",
        "role": "assistant"
      }
    ],
    "tools": [
      {
        "async": true,
        "messages": [
          {
            "type": "request-start",
            "content": "<string>",
            "conditions": [
              {
                "param": "<string>",
                "value": "<string>",
                "operator": "eq"
              }
            ]
          }
        ],
        "type": "dtmf",
        "function": {
          "name": "<string>",
          "description": "<string>",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": [
              "<string>"
            ]
          }
        },
        "server": {
          "timeoutSeconds": 20,
          "url": "<string>",
          "secret": "<string>"
        }
      }
    ],
    "toolIds": [
      "<string>"
    ],
    "provider": "anyscale",
    "model": "<string>",
    "temperature": 1,
    "knowledgeBase": {
      "provider": "canonical",
      "topK": 5.5,
      "fileIds": [
        "<string>"
      ]
    },
    "maxTokens": 525,
    "emotionRecognitionEnabled": true
  },
  "voice": {
    "inputPreprocessingEnabled": true,
    "inputReformattingEnabled": true,
    "inputMinCharacters": 30,
    "inputPunctuationBoundaries": [
      "。",
      "，",
      ".",
      "!",
      "?",
      ";",
      ")",
      "،",
      "۔",
      "।",
      "॥",
      "|",
      "||",
      ",",
      ":"
    ],
    "fillerInjectionEnabled": true,
    "provider": "azure",
    "voiceId": "andrew",
    "speed": 1.25
  },
  "firstMessageMode": "assistant-speaks-first",
  "recordingEnabled": true,
  "hipaaEnabled": true,
  "clientMessages": [
    "conversation-update",
    "function-call",
    "hang",
    "model-output",
    "speech-update",
    "status-update",
    "transcript",
    "tool-calls",
    "user-interrupted",
    "voice-input"
  ],
  "serverMessages": [
    "conversation-update",
    "end-of-call-report",
    "function-call",
    "hang",
    "speech-update",
    "status-update",
    "tool-calls",
    "transfer-destination-request",
    "user-interrupted"
  ],
  "silenceTimeoutSeconds": 30,
  "responseDelaySeconds": 0.4,
  "llmRequestDelaySeconds": 0.1,
  "numWordsToInterruptAssistant": 5,
  "maxDurationSeconds": 1800,
  "backgroundSound": "office",
  "backchannelingEnabled": true,
  "backgroundDenoisingEnabled": true,
  "modelOutputInMessagesEnabled": true,
  "isServerUrlSecretSet": {},
  "name": "<string>",
  "firstMessage": "<string>",
  "voicemailDetection": {
    "provider": "twilio",
    "voicemailDetectionTypes": [
      "machine_end_beep",
      "machine_end_silence"
    ],
    "enabled": true,
    "machineDetectionTimeout": 31,
    "machineDetectionSpeechThreshold": 3500,
    "machineDetectionSpeechEndThreshold": 2750,
    "machineDetectionSilenceTimeout": 6000
  },
  "voicemailMessage": "<string>",
  "endCallMessage": "<string>",
  "endCallPhrases": [
    "<string>"
  ],
  "metadata": {},
  "serverUrl": "<string>",
  "serverUrlSecret": "<string>",
  "analysisPlan": {
    "summaryPrompt": "<string>",
    "summaryRequestTimeoutSeconds": 10.5,
    "structuredDataRequestTimeoutSeconds": 10.5,
    "successEvaluationPrompt": "<string>",
    "successEvaluationRubric": "NumericScale",
    "successEvaluationRequestTimeoutSeconds": 10.5,
    "structuredDataPrompt": "<string>",
    "structuredDataSchema": {
      "type": "string",
      "items": {},
      "properties": {},
      "description": "<string>",
      "required": [
        "<string>"
      ]
    }
  },
  "artifactPlan": {
    "videoRecordingEnabled": true
  },
  "messagePlan": {
    "idleMessages": [
      "<string>"
    ],
    "idleMessageMaxSpokenCount": 5.5,
    "idleTimeoutSeconds": 7.5
  },
  "id": "<string>",
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

headerrequired

Retrieve your API Key from Dashboard.

Body

application/json

transcriber

object

These are the options for the assistant's transcriber.

model

object

These are the options for the assistant's LLM.

model.messages

object[]

This is the starting state for the conversation.

model.tools

object[]

These are the tools that the assistant can use during the call. To use existing tools, use toolIds.

Both tools and toolIds can be used together.

model.tools.async

boolean

This determines if the tool is async.

If async, the assistant will move forward without waiting for your server to respond. This is useful if you just want to trigger something on your server.

If sync, the assistant will wait for your server to respond. This is useful if want assistant to respond with the result from your server.

Defaults to synchronous (false).

model.tools.messages

object[]

These are the messages that will be spoken to the user as the tool is running.

For some tools, this is auto-filled based on special fields like tool.destinations. For others like the function tool, these can be custom configured.

model.tools.type

enum<string>

required

The type of tool. "dtmf" for DTMF tool.

Available options:

dtmf

model.tools.function

object

This is the function definition of the tool.

For endCall, transferCall, and dtmf tools, this is auto-filled based on tool-specific fields like tool.destinations. But, even in those cases, you can provide a custom function definition for advanced use cases.

An example of an advanced use case is if you want to customize the message that's spoken for endCall tool. You can specify a function where it returns an argument "reason". Then, in messages array, you can have many "request-complete" messages. One of these messages will be triggered if the messages[].conditions matches the "reason" argument.

model.tools.server

object

This is the server that will be hit when this tool is requested by the model.

All requests will be sent with the call object among other things. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org and the phoneNumber. Order of precedence: highest tool.server.url, then assistant.serverUrl, then phoneNumber.serverUrl, then org.serverUrl.

model.toolIds

string[]

These are the tools that the assistant can use during the call. To use transient tools, use tools.

Both tools and toolIds can be used together.

model.provider

enum<string>

required

Available options:

anyscale

model.model

string

required

This is the name of the model. Ex. cognitivecomputations/dolphin-mixtral-8x7b

model.temperature

number

This is the temperature that will be used for calls. Default is 0 to leverage caching for lower latency.

model.knowledgeBase

object

These are the options for the knowledge base.

model.maxTokens

number

This is the max number of tokens that the assistant will be allowed to generate in each turn of the conversation. Default is 250.

model.emotionRecognitionEnabled

boolean

This determines whether we detect user's emotion while they speak and send it as an additional info to model.

Default false because the model is usually are good at understanding the user's emotion from text.

voice

object

These are the options for the assistant's voice.

voice.inputPreprocessingEnabled

boolean

This determines whether the model output is preprocessed into chunks before being sent to the voice provider.

Default true because voice generation sounds better with chunking (and reformatting them).

To send every token from the model output directly to the voice provider and rely on the voice provider's audio generation logic, set this to false.

If disabled, vapi-provided audio control tokens like <flush /> will not work.

voice.inputReformattingEnabled

boolean

This determines whether the chunk is reformatted before being sent to the voice provider. Many things are reformatted including phone numbers, emails and addresses to improve their enunciation.

Default true because voice generation sounds better with reformatting.

To disable chunk reformatting, set this to false.

To disable chunking completely, set inputPreprocessingEnabled to false.

voice.inputMinCharacters

number

This is the minimum number of characters before a chunk is created. The chunks that are sent to the voice provider for the voice generation as the model tokens are streaming in. Defaults to 30.

Increasing this value might add latency as it waits for the model to output a full chunk before sending it to the voice provider. On the other hand, increasing might be a good idea if you want to give voice provider bigger chunks so it can pronounce them better.

Decreasing this value might decrease latency but might also decrease quality if the voice provider struggles to pronounce the text correctly.

voice.inputPunctuationBoundaries

enum<string>[]

These are the punctuations that are considered valid boundaries before a chunk is created. The chunks that are sent to the voice provider for the voice generation as the model tokens are streaming in. Defaults are chosen differently for each provider.

Constraining the delimiters might add latency as it waits for the model to output a full chunk before sending it to the voice provider. On the other hand, constraining might be a good idea if you want to give voice provider longer chunks so it can sound less disjointed across chunks. Eg. ['.'].

Available options:

。,

，,

.,

!,

?,

;,

),

،,

۔,

।,

॥,

|,

||,

,,

:

voice.fillerInjectionEnabled

boolean

This determines whether fillers are injected into the model output before inputting it into the voice provider.

Default false because you can achieve better results with prompting the model.

voice.provider

enum<string>

required

This is the voice provider that will be used.

Available options:

azure

voice.voiceId

required

This is the provider-specific ID that will be used.

Available options:

andrew,

brian,

emma

voice.speed

number

This is the speed multiplier that will be used.

firstMessageMode

enum<string>

This is the mode for the first message. Default is 'assistant-speaks-first'.

Use:

'assistant-speaks-first' to have the assistant speak first.
'assistant-waits-for-user' to have the assistant wait for the user to speak first.
'assistant-speaks-first-with-model-generated-message' to have the assistant speak first with a message generated by the model based on the conversation state. (assistant.model.messages at call start, call.messages at squad transfer points).

@default 'assistant-speaks-first'

Available options:

assistant-speaks-first,

assistant-speaks-first-with-model-generated-message,

assistant-waits-for-user

recordingEnabled

boolean

This sets whether the assistant's calls are recorded. Defaults to true.

hipaaEnabled

boolean

When this is enabled, no logs, recordings, or transcriptions will be stored. At the end of the call, you will still receive an end-of-call-report message to store on your server. Defaults to false.

clientMessages

enum<string>[]

These are the messages that will be sent to your Client SDKs. Default is conversation-update,function-call,hang,model-output,speech-update,status-update,transcript,tool-calls,user-interrupted,voice-input. You can check the shape of the messages in ClientMessage schema.

Available options:

conversation-update,

function-call,

function-call-result,

hang,

metadata,

model-output,

speech-update,

status-update,

transcript,

tool-calls,

tool-calls-result,

user-interrupted,

voice-input

serverMessages

enum<string>[]

These are the messages that will be sent to your Server URL. Default is conversation-update,end-of-call-report,function-call,hang,speech-update,status-update,tool-calls,transfer-destination-request,user-interrupted. You can check the shape of the messages in ServerMessage schema.

Available options:

conversation-update,

end-of-call-report,

function-call,

hang,

model-output,

phone-call-control,

speech-update,

status-update,

transcript,

tool-calls,

transfer-destination-request,

user-interrupted,

voice-input

silenceTimeoutSeconds

number

How many seconds of silence to wait before ending the call. Defaults to 30.

@default 30

responseDelaySeconds

number

The minimum number of seconds after user speech to wait before the assistant starts speaking. Defaults to 0.4.

@default 0.4

llmRequestDelaySeconds

number

The minimum number of seconds to wait after punctuation before sending a request to the LLM. Defaults to 0.1.

@default 0.1

numWordsToInterruptAssistant

number

The number of words to wait for before interrupting the assistant.

Words like "stop", "actually", "no", etc. will always interrupt immediately regardless of this value.

Words like "okay", "yeah", "right" will never interrupt.

When set to 0, it will rely solely on the VAD (Voice Activity Detector) and will not wait for any transcription. Defaults to this (0).

@default 0

maxDurationSeconds

number

This is the maximum number of seconds that the call will last. When the call reaches this duration, it will be ended.

@default 1800 (~30 minutes)

backgroundSound

enum<string>

This is the background sound in the call. Default for phone calls is 'office' and default for web calls is 'off'.

Available options:

off,

office

backchannelingEnabled

boolean

This determines whether the model says 'mhmm', 'ahem' etc. while user is speaking.

Default false while in beta.

@default false

backgroundDenoisingEnabled

boolean

This enables filtering of noise and background speech while the user is talking.

Default false while in beta.

@default false

modelOutputInMessagesEnabled

boolean

This determines whether the model's output is used in conversation history rather than the transcription of assistant's speech.

Default false while in beta.

@default false

name

string

This is the name of the assistant.

This is required when you want to transfer between assistants in a call.

firstMessage

string

This is the first message that the assistant will say. This can also be a URL to a containerized audio file (mp3, wav, etc.).

If unspecified, assistant will wait for user to speak and use the model to respond once they speak.

voicemailDetection

object

These are the settings to configure or disable voicemail detection. Alternatively, voicemail detection can be configured using the model.tools=[VoicemailTool]. This uses Twilio's built-in detection while the VoicemailTool relies on the model to detect if a voicemail was reached. You can use neither of them, one of them, or both of them. By default, Twilio built-in detection is enabled while VoicemailTool is not.

voicemailDetection.provider

enum<string>

required

This is the provider to use for voicemail detection.

Available options:

twilio

voicemailDetection.voicemailDetectionTypes

enum<string>[]

These are the AMD messages from Twilio that are considered as voicemail. Default is ['machine_end_beep', 'machine_end_silence'].

@default {Array} ['machine_end_beep', 'machine_end_silence']

Available options:

machine_start,

human,

fax,

unknown,

machine_end_beep,

machine_end_silence,

machine_end_other

voicemailDetection.enabled

boolean

This sets whether the assistant should detect voicemail. Defaults to true.

@default true

voicemailDetection.machineDetectionTimeout

number

The number of seconds that Twilio should attempt to perform answering machine detection before timing out and returning AnsweredBy as unknown. Default is 30 seconds.

Increasing this value will provide the engine more time to make a determination. This can be useful when DetectMessageEnd is provided in the MachineDetection parameter and there is an expectation of long answering machine greetings that can exceed 30 seconds.

Decreasing this value will reduce the amount of time the engine has to make a determination. This can be particularly useful when the Enable option is provided in the MachineDetection parameter and you want to limit the time for initial detection.

Check the Twilio docs for more info.

@default 30

voicemailDetection.machineDetectionSpeechThreshold

number

The number of milliseconds that is used as the measuring stick for the length of the speech activity. Durations lower than this value will be interpreted as a human, longer as a machine. Default is 2400 milliseconds.

Increasing this value will reduce the chance of a False Machine (detected machine, actually human) for a long human greeting (e.g., a business greeting) but increase the time it takes to detect a machine.

Decreasing this value will reduce the chances of a False Human (detected human, actually machine) for short voicemail greetings. The value of this parameter may need to be reduced by more than 1000ms to detect very short voicemail greetings. A reduction of that significance can result in increased False Machine detections. Adjusting the MachineDetectionSpeechEndThreshold is likely the better approach for short voicemails. Decreasing MachineDetectionSpeechThreshold will also reduce the time it takes to detect a machine.

Check the Twilio docs for more info.

@default 2400

voicemailDetection.machineDetectionSpeechEndThreshold

number

The number of milliseconds of silence after speech activity at which point the speech activity is considered complete. Default is 1200 milliseconds.

Increasing this value will typically be used to better address the short voicemail greeting scenarios. For short voicemails, there is typically 1000-2000ms of audio followed by 1200-2400ms of silence and then additional audio before the beep. Increasing the MachineDetectionSpeechEndThreshold to ~2500ms will treat the 1200-2400ms of silence as a gap in the greeting but not the end of the greeting and will result in a machine detection. The downsides of such a change include:

Increasing the delay for human detection by the amount you increase this parameter, e.g., a change of 1200ms to 2500ms increases human detection delay by 1300ms.
Cases where a human has two utterances separated by a period of silence (e.g. a "Hello", then 2000ms of silence, and another "Hello") may be interpreted as a machine.

Decreasing this value will result in faster human detection. The consequence is that it can lead to increased False Human (detected human, actually machine) detections because a silence gap in a voicemail greeting (not necessarily just in short voicemail scenarios) can be incorrectly interpreted as the end of speech.

Check the Twilio docs for more info.

@default 1200

voicemailDetection.machineDetectionSilenceTimeout

number

The number of milliseconds of initial silence after which an unknown AnsweredBy result will be returned. Default is 5000 milliseconds.

Increasing this value will result in waiting for a longer period of initial silence before returning an 'unknown' AMD result.

Decreasing this value will result in waiting for a shorter period of initial silence before returning an 'unknown' AMD result.

Check the Twilio docs for more info.

@default 5000

voicemailMessage

string

This is the message that the assistant will say if the call is forwarded to voicemail.

If unspecified, it will hang up.

endCallMessage

string

This is the message that the assistant will say if it ends the call.

If unspecified, it will hang up without saying anything.

endCallPhrases

string[]

This list contains phrases that, if spoken by the assistant, will trigger the call to be hung up. Case insensitive.

metadata

object

This is for metadata you want to store on the assistant.

serverUrl

string

This is the URL Vapi will communicate with via HTTP GET and POST Requests. This is used for retrieving context, function calling, and end-of-call reports.

All requests will be sent with the call object among other things relevant to that message. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org and the phoneNumber. Order of precedence: tool.server.url > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl

serverUrlSecret

string

This is the secret you can set that Vapi will send with every request to your server. Will be sent as a header called x-vapi-secret.

Same precedence logic as serverUrl.

analysisPlan

object

This is the plan for analysis of assistant's calls. Stored in call.analysis.

analysisPlan.summaryPrompt

string

This is the prompt that's used to summarize the call. The output is stored in call.analysis.summary.

Default is "You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences, if applicable.".

Set to '' or 'off' to disable.

analysisPlan.summaryRequestTimeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty. Increasing this timeout will delay the end of call report.

Default is 5 seconds.

analysisPlan.structuredDataRequestTimeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.structuredData will be empty. Increasing this timeout will delay the end of call report.

Default is 5 seconds.

analysisPlan.successEvaluationPrompt

string

This is the prompt that's used to evaluate if the call was successful. The output is stored in call.analysis.successEvaluation.

Default is "You are an expert call evaluator. You will be given a transcript of a call and the system prompt of the AI participant. Determine if the call was successful based on the objectives inferred from the system prompt.".

Set to '' or 'off' to disable.

You can use this standalone or in combination with successEvaluationRubric. If both are provided, they are concatenated into appropriate instructions.

analysisPlan.successEvaluationRubric

enum<string>

This enforces the rubric of the evaluation. The output is stored in call.analysis.successEvaluation.

Options include:

'NumericScale': A scale of 1 to 10.
'DescriptiveScale': A scale of Excellent, Good, Fair, Poor.
'Checklist': A checklist of criteria and their status.
'Matrix': A grid that evaluates multiple criteria across different performance levels.
'PercentageScale': A scale of 0% to 100%.
'LikertScale': A scale of Strongly Agree, Agree, Neutral, Disagree, Strongly Disagree.
'AutomaticRubric': Automatically break down evaluation into several criteria, each with its own score.
'PassFail': A simple 'true' if call passed, 'false' if not.

For 'Checklist' and 'Matrix', provide the criteria in successEvaluationPrompt.

Default is 'PassFail' if successEvaluationPrompt is not provided, and null if successEvaluationPrompt is provided.

You can use this standalone or in combination with successEvaluationPrompt. If both are provided, they are concatenated into appropriate instructions.

Available options:

NumericScale,

DescriptiveScale,

Checklist,

Matrix,

PercentageScale,

LikertScale,

AutomaticRubric,

PassFail

analysisPlan.successEvaluationRequestTimeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.successEvaluation will be empty. Increasing this timeout will delay the end of call report.

Default is 5 seconds.

analysisPlan.structuredDataPrompt

string

This is the prompt that's used to extract structured data from the call. The output is stored in call.analysis.structuredData.

Disabled by default.

You can use this standalone or in combination with structuredDataSchema. If both are provided, they are concatenated into appropriate instructions.

analysisPlan.structuredDataSchema

object

This enforces the schema of the structured data. This output is stored in call.analysis.structuredData.

Complete guide on JSON Schema can be found here.

Disabled by default.

You can use this standalone or in combination with structuredDataPrompt. If both are provided, they are concatenated into appropriate instructions.

artifactPlan

object

This is the plan for artifacts generated during assistant's calls. Stored in call.artifact.

messagePlan

object

This is the plan for static messages that can be spoken by the assistant during the call, like idleMessages.

Note: firstMessage, voicemailMessage, and endCallMessage are currently at the root level. They will be moved to messagePlan in the future, but will remain backwards compatible.

Response

201 - application/json

transcriber

object

These are the options for the assistant's transcriber.

model

object

These are the options for the assistant's LLM.

model.messages

object[]

This is the starting state for the conversation.

model.tools

object[]

These are the tools that the assistant can use during the call. To use existing tools, use toolIds.

Both tools and toolIds can be used together.

model.tools.async

boolean

This determines if the tool is async.

If async, the assistant will move forward without waiting for your server to respond. This is useful if you just want to trigger something on your server.

If sync, the assistant will wait for your server to respond. This is useful if want assistant to respond with the result from your server.

Defaults to synchronous (false).

model.tools.messages

object[]

These are the messages that will be spoken to the user as the tool is running.

For some tools, this is auto-filled based on special fields like tool.destinations. For others like the function tool, these can be custom configured.

model.tools.type

enum<string>

required

The type of tool. "dtmf" for DTMF tool.

Available options:

dtmf

model.tools.function

object

This is the function definition of the tool.

model.tools.server

object

This is the server that will be hit when this tool is requested by the model.

All requests will be sent with the call object among other things. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org and the phoneNumber. Order of precedence: highest tool.server.url, then assistant.serverUrl, then phoneNumber.serverUrl, then org.serverUrl.

model.toolIds

string[]

These are the tools that the assistant can use during the call. To use transient tools, use tools.

Both tools and toolIds can be used together.

model.provider

enum<string>

required

Available options:

anyscale

model.model

string

required

This is the name of the model. Ex. cognitivecomputations/dolphin-mixtral-8x7b

model.temperature

number

This is the temperature that will be used for calls. Default is 0 to leverage caching for lower latency.

model.knowledgeBase

object

These are the options for the knowledge base.

model.maxTokens

number

This is the max number of tokens that the assistant will be allowed to generate in each turn of the conversation. Default is 250.

model.emotionRecognitionEnabled

boolean

This determines whether we detect user's emotion while they speak and send it as an additional info to model.

Default false because the model is usually are good at understanding the user's emotion from text.

voice

object

These are the options for the assistant's voice.

voice.inputPreprocessingEnabled

boolean

This determines whether the model output is preprocessed into chunks before being sent to the voice provider.

Default true because voice generation sounds better with chunking (and reformatting them).

To send every token from the model output directly to the voice provider and rely on the voice provider's audio generation logic, set this to false.

If disabled, vapi-provided audio control tokens like <flush /> will not work.

voice.inputReformattingEnabled

boolean

This determines whether the chunk is reformatted before being sent to the voice provider. Many things are reformatted including phone numbers, emails and addresses to improve their enunciation.

Default true because voice generation sounds better with reformatting.

To disable chunk reformatting, set this to false.

To disable chunking completely, set inputPreprocessingEnabled to false.

voice.inputMinCharacters

number

This is the minimum number of characters before a chunk is created. The chunks that are sent to the voice provider for the voice generation as the model tokens are streaming in. Defaults to 30.

Decreasing this value might decrease latency but might also decrease quality if the voice provider struggles to pronounce the text correctly.

voice.inputPunctuationBoundaries

enum<string>[]

Available options:

。,

，,

.,

!,

?,

;,

),

،,

۔,

।,

॥,

|,

||,

,,

:

voice.fillerInjectionEnabled

boolean

This determines whether fillers are injected into the model output before inputting it into the voice provider.

Default false because you can achieve better results with prompting the model.

voice.provider

enum<string>

required

This is the voice provider that will be used.

Available options:

azure

voice.voiceId

required

This is the provider-specific ID that will be used.

Available options:

andrew,

brian,

emma

voice.speed

number

This is the speed multiplier that will be used.

firstMessageMode

enum<string>

This is the mode for the first message. Default is 'assistant-speaks-first'.

Use:

'assistant-speaks-first' to have the assistant speak first.
'assistant-waits-for-user' to have the assistant wait for the user to speak first.
'assistant-speaks-first-with-model-generated-message' to have the assistant speak first with a message generated by the model based on the conversation state. (assistant.model.messages at call start, call.messages at squad transfer points).

@default 'assistant-speaks-first'

Available options:

assistant-speaks-first,

assistant-speaks-first-with-model-generated-message,

assistant-waits-for-user

recordingEnabled

boolean

This sets whether the assistant's calls are recorded. Defaults to true.

hipaaEnabled

boolean

When this is enabled, no logs, recordings, or transcriptions will be stored. At the end of the call, you will still receive an end-of-call-report message to store on your server. Defaults to false.

clientMessages

enum<string>[]

Available options:

conversation-update,

function-call,

function-call-result,

hang,

metadata,

model-output,

speech-update,

status-update,

transcript,

tool-calls,

tool-calls-result,

user-interrupted,

voice-input

serverMessages

enum<string>[]

Available options:

conversation-update,

end-of-call-report,

function-call,

hang,

model-output,

phone-call-control,

speech-update,

status-update,

transcript,

tool-calls,

transfer-destination-request,

user-interrupted,

voice-input

silenceTimeoutSeconds

number

How many seconds of silence to wait before ending the call. Defaults to 30.

@default 30

responseDelaySeconds

number

The minimum number of seconds after user speech to wait before the assistant starts speaking. Defaults to 0.4.

@default 0.4

llmRequestDelaySeconds

number

The minimum number of seconds to wait after punctuation before sending a request to the LLM. Defaults to 0.1.

@default 0.1

numWordsToInterruptAssistant

number

The number of words to wait for before interrupting the assistant.

Words like "stop", "actually", "no", etc. will always interrupt immediately regardless of this value.

Words like "okay", "yeah", "right" will never interrupt.

When set to 0, it will rely solely on the VAD (Voice Activity Detector) and will not wait for any transcription. Defaults to this (0).

@default 0

maxDurationSeconds

number

This is the maximum number of seconds that the call will last. When the call reaches this duration, it will be ended.

@default 1800 (~30 minutes)

backgroundSound

enum<string>

This is the background sound in the call. Default for phone calls is 'office' and default for web calls is 'off'.

Available options:

off,

office

backchannelingEnabled

boolean

This determines whether the model says 'mhmm', 'ahem' etc. while user is speaking.

Default false while in beta.

@default false

backgroundDenoisingEnabled

boolean

This enables filtering of noise and background speech while the user is talking.

Default false while in beta.

@default false

modelOutputInMessagesEnabled

boolean

This determines whether the model's output is used in conversation history rather than the transcription of assistant's speech.

Default false while in beta.

@default false

isServerUrlSecretSet

object

required

name

string

This is the name of the assistant.

This is required when you want to transfer between assistants in a call.

firstMessage

string

This is the first message that the assistant will say. This can also be a URL to a containerized audio file (mp3, wav, etc.).

If unspecified, assistant will wait for user to speak and use the model to respond once they speak.

voicemailDetection

object

voicemailDetection.provider

enum<string>

required

This is the provider to use for voicemail detection.

Available options:

twilio

voicemailDetection.voicemailDetectionTypes

enum<string>[]

These are the AMD messages from Twilio that are considered as voicemail. Default is ['machine_end_beep', 'machine_end_silence'].

@default {Array} ['machine_end_beep', 'machine_end_silence']

Available options:

machine_start,

human,

fax,

unknown,

machine_end_beep,

machine_end_silence,

machine_end_other

voicemailDetection.enabled

boolean

This sets whether the assistant should detect voicemail. Defaults to true.

@default true

voicemailDetection.machineDetectionTimeout

number

The number of seconds that Twilio should attempt to perform answering machine detection before timing out and returning AnsweredBy as unknown. Default is 30 seconds.

Check the Twilio docs for more info.

@default 30

voicemailDetection.machineDetectionSpeechThreshold

number

Check the Twilio docs for more info.

@default 2400

voicemailDetection.machineDetectionSpeechEndThreshold

number

The number of milliseconds of silence after speech activity at which point the speech activity is considered complete. Default is 1200 milliseconds.

Increasing the delay for human detection by the amount you increase this parameter, e.g., a change of 1200ms to 2500ms increases human detection delay by 1300ms.
Cases where a human has two utterances separated by a period of silence (e.g. a "Hello", then 2000ms of silence, and another "Hello") may be interpreted as a machine.

Check the Twilio docs for more info.

@default 1200

voicemailDetection.machineDetectionSilenceTimeout

number

The number of milliseconds of initial silence after which an unknown AnsweredBy result will be returned. Default is 5000 milliseconds.

Increasing this value will result in waiting for a longer period of initial silence before returning an 'unknown' AMD result.

Decreasing this value will result in waiting for a shorter period of initial silence before returning an 'unknown' AMD result.

Check the Twilio docs for more info.

@default 5000

voicemailMessage

string

This is the message that the assistant will say if the call is forwarded to voicemail.

If unspecified, it will hang up.

endCallMessage

string

This is the message that the assistant will say if it ends the call.

If unspecified, it will hang up without saying anything.

endCallPhrases

string[]

This list contains phrases that, if spoken by the assistant, will trigger the call to be hung up. Case insensitive.

metadata

object

This is for metadata you want to store on the assistant.

serverUrl

string

This is the URL Vapi will communicate with via HTTP GET and POST Requests. This is used for retrieving context, function calling, and end-of-call reports.

All requests will be sent with the call object among other things relevant to that message. You can find more details in the Server URL documentation.

This overrides the serverUrl set on the org and the phoneNumber. Order of precedence: tool.server.url > assistant.serverUrl > phoneNumber.serverUrl > org.serverUrl

serverUrlSecret

string

This is the secret you can set that Vapi will send with every request to your server. Will be sent as a header called x-vapi-secret.

Same precedence logic as serverUrl.

analysisPlan

object

This is the plan for analysis of assistant's calls. Stored in call.analysis.

analysisPlan.summaryPrompt

string

This is the prompt that's used to summarize the call. The output is stored in call.analysis.summary.

Default is "You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences, if applicable.".

Set to '' or 'off' to disable.

analysisPlan.summaryRequestTimeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.summary will be empty. Increasing this timeout will delay the end of call report.

Default is 5 seconds.

analysisPlan.structuredDataRequestTimeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.structuredData will be empty. Increasing this timeout will delay the end of call report.

Default is 5 seconds.

analysisPlan.successEvaluationPrompt

string

This is the prompt that's used to evaluate if the call was successful. The output is stored in call.analysis.successEvaluation.

Set to '' or 'off' to disable.

You can use this standalone or in combination with successEvaluationRubric. If both are provided, they are concatenated into appropriate instructions.

analysisPlan.successEvaluationRubric

enum<string>

This enforces the rubric of the evaluation. The output is stored in call.analysis.successEvaluation.

Options include:

'NumericScale': A scale of 1 to 10.
'DescriptiveScale': A scale of Excellent, Good, Fair, Poor.
'Checklist': A checklist of criteria and their status.
'Matrix': A grid that evaluates multiple criteria across different performance levels.
'PercentageScale': A scale of 0% to 100%.
'LikertScale': A scale of Strongly Agree, Agree, Neutral, Disagree, Strongly Disagree.
'AutomaticRubric': Automatically break down evaluation into several criteria, each with its own score.
'PassFail': A simple 'true' if call passed, 'false' if not.

For 'Checklist' and 'Matrix', provide the criteria in successEvaluationPrompt.

Default is 'PassFail' if successEvaluationPrompt is not provided, and null if successEvaluationPrompt is provided.

You can use this standalone or in combination with successEvaluationPrompt. If both are provided, they are concatenated into appropriate instructions.

Available options:

NumericScale,

DescriptiveScale,

Checklist,

Matrix,

PercentageScale,

LikertScale,

AutomaticRubric,

PassFail

analysisPlan.successEvaluationRequestTimeoutSeconds

number

This is how long the request is tried before giving up. When request times out, call.analysis.successEvaluation will be empty. Increasing this timeout will delay the end of call report.

Default is 5 seconds.

analysisPlan.structuredDataPrompt

string

This is the prompt that's used to extract structured data from the call. The output is stored in call.analysis.structuredData.

Disabled by default.

You can use this standalone or in combination with structuredDataSchema. If both are provided, they are concatenated into appropriate instructions.

analysisPlan.structuredDataSchema

object

This enforces the schema of the structured data. This output is stored in call.analysis.structuredData.

Complete guide on JSON Schema can be found here.

Disabled by default.

You can use this standalone or in combination with structuredDataPrompt. If both are provided, they are concatenated into appropriate instructions.

artifactPlan

object

This is the plan for artifacts generated during assistant's calls. Stored in call.artifact.

messagePlan

object

This is the plan for static messages that can be spoken by the assistant during the call, like idleMessages.

Note: firstMessage, voicemailMessage, and endCallMessage are currently at the root level. They will be moved to messagePlan in the future, but will remain backwards compatible.

string

required

This is the unique identifier for the assistant.

orgId

string

required

This is the unique identifier for the org that this assistant belongs to.

createdAt

string

required

This is the ISO 8601 date-time string of when the assistant was created.

updatedAt

string

required

This is the ISO 8601 date-time string of when the assistant was last updated.

Was this page helpful?

Get Assistant

curl --request POST \
  --url https://api.vapi.ai/assistant \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2",
    "language": "bg",
    "smartFormat": true,
    "keywords": [
      "<string>"
    ]
  },
  "model": {
    "messages": [
      {
        "content": "<string>",
        "role": "assistant"
      }
    ],
    "tools": [
      {
        "async": true,
        "messages": [
          {
            "type": "request-start",
            "content": "<string>",
            "conditions": [
              {
                "param": "<string>",
                "value": "<string>",
                "operator": "eq"
              }
            ]
          }
        ],
        "type": "dtmf",
        "function": {
          "name": "<string>",
          "description": "<string>",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": [
              "<string>"
            ]
          }
        },
        "server": {
          "timeoutSeconds": 20,
          "url": "<string>",
          "secret": "<string>"
        }
      }
    ],
    "toolIds": [
      "<string>"
    ],
    "provider": "anyscale",
    "model": "<string>",
    "temperature": 1,
    "knowledgeBase": {
      "provider": "canonical",
      "topK": 5.5,
      "fileIds": [
        "<string>"
      ]
    },
    "maxTokens": 525,
    "emotionRecognitionEnabled": true
  },
  "voice": {
    "inputPreprocessingEnabled": true,
    "inputReformattingEnabled": true,
    "inputMinCharacters": 30,
    "inputPunctuationBoundaries": [
      "。",
      "，",
      ".",
      "!",
      "?",
      ";",
      ")",
      "،",
      "۔",
      "।",
      "॥",
      "|",
      "||",
      ",",
      ":"
    ],
    "fillerInjectionEnabled": true,
    "provider": "azure",
    "voiceId": "andrew",
    "speed": 1.25
  },
  "firstMessageMode": "assistant-speaks-first",
  "recordingEnabled": true,
  "hipaaEnabled": true,
  "clientMessages": [
    "conversation-update",
    "function-call",
    "hang",
    "model-output",
    "speech-update",
    "status-update",
    "transcript",
    "tool-calls",
    "user-interrupted",
    "voice-input"
  ],
  "serverMessages": [
    "conversation-update",
    "end-of-call-report",
    "function-call",
    "hang",
    "speech-update",
    "status-update",
    "tool-calls",
    "transfer-destination-request",
    "user-interrupted"
  ],
  "silenceTimeoutSeconds": 30,
  "responseDelaySeconds": 0.4,
  "llmRequestDelaySeconds": 0.1,
  "numWordsToInterruptAssistant": 5,
  "maxDurationSeconds": 1800,
  "backgroundSound": "office",
  "backchannelingEnabled": true,
  "backgroundDenoisingEnabled": true,
  "modelOutputInMessagesEnabled": true,
  "name": "<string>",
  "firstMessage": "<string>",
  "voicemailDetection": {
    "provider": "twilio",
    "voicemailDetectionTypes": [
      "machine_end_beep",
      "machine_end_silence"
    ],
    "enabled": true,
    "machineDetectionTimeout": 31,
    "machineDetectionSpeechThreshold": 3500,
    "machineDetectionSpeechEndThreshold": 2750,
    "machineDetectionSilenceTimeout": 6000
  },
  "voicemailMessage": "<string>",
  "endCallMessage": "<string>",
  "endCallPhrases": [
    "<string>"
  ],
  "metadata": {},
  "serverUrl": "<string>",
  "serverUrlSecret": "<string>",
  "analysisPlan": {
    "summaryPrompt": "<string>",
    "summaryRequestTimeoutSeconds": 10.5,
    "structuredDataRequestTimeoutSeconds": 10.5,
    "successEvaluationPrompt": "<string>",
    "successEvaluationRubric": "NumericScale",
    "successEvaluationRequestTimeoutSeconds": 10.5,
    "structuredDataPrompt": "<string>",
    "structuredDataSchema": {
      "type": "string",
      "items": {},
      "properties": {},
      "description": "<string>",
      "required": [
        "<string>"
      ]
    }
  },
  "artifactPlan": {
    "videoRecordingEnabled": true
  },
  "messagePlan": {
    "idleMessages": [
      "<string>"
    ],
    "idleMessageMaxSpokenCount": 5.5,
    "idleTimeoutSeconds": 7.5
  }
}'

{
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-2",
    "language": "bg",
    "smartFormat": true,
    "keywords": [
      "<string>"
    ]
  },
  "model": {
    "messages": [
      {
        "content": "<string>",
        "role": "assistant"
      }
    ],
    "tools": [
      {
        "async": true,
        "messages": [
          {
            "type": "request-start",
            "content": "<string>",
            "conditions": [
              {
                "param": "<string>",
                "value": "<string>",
                "operator": "eq"
              }
            ]
          }
        ],
        "type": "dtmf",
        "function": {
          "name": "<string>",
          "description": "<string>",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": [
              "<string>"
            ]
          }
        },
        "server": {
          "timeoutSeconds": 20,
          "url": "<string>",
          "secret": "<string>"
        }
      }
    ],
    "toolIds": [
      "<string>"
    ],
    "provider": "anyscale",
    "model": "<string>",
    "temperature": 1,
    "knowledgeBase": {
      "provider": "canonical",
      "topK": 5.5,
      "fileIds": [
        "<string>"
      ]
    },
    "maxTokens": 525,
    "emotionRecognitionEnabled": true
  },
  "voice": {
    "inputPreprocessingEnabled": true,
    "inputReformattingEnabled": true,
    "inputMinCharacters": 30,
    "inputPunctuationBoundaries": [
      "。",
      "，",
      ".",
      "!",
      "?",
      ";",
      ")",
      "،",
      "۔",
      "।",
      "॥",
      "|",
      "||",
      ",",
      ":"
    ],
    "fillerInjectionEnabled": true,
    "provider": "azure",
    "voiceId": "andrew",
    "speed": 1.25
  },
  "firstMessageMode": "assistant-speaks-first",
  "recordingEnabled": true,
  "hipaaEnabled": true,
  "clientMessages": [
    "conversation-update",
    "function-call",
    "hang",
    "model-output",
    "speech-update",
    "status-update",
    "transcript",
    "tool-calls",
    "user-interrupted",
    "voice-input"
  ],
  "serverMessages": [
    "conversation-update",
    "end-of-call-report",
    "function-call",
    "hang",
    "speech-update",
    "status-update",
    "tool-calls",
    "transfer-destination-request",
    "user-interrupted"
  ],
  "silenceTimeoutSeconds": 30,
  "responseDelaySeconds": 0.4,
  "llmRequestDelaySeconds": 0.1,
  "numWordsToInterruptAssistant": 5,
  "maxDurationSeconds": 1800,
  "backgroundSound": "office",
  "backchannelingEnabled": true,
  "backgroundDenoisingEnabled": true,
  "modelOutputInMessagesEnabled": true,
  "isServerUrlSecretSet": {},
  "name": "<string>",
  "firstMessage": "<string>",
  "voicemailDetection": {
    "provider": "twilio",
    "voicemailDetectionTypes": [
      "machine_end_beep",
      "machine_end_silence"
    ],
    "enabled": true,
    "machineDetectionTimeout": 31,
    "machineDetectionSpeechThreshold": 3500,
    "machineDetectionSpeechEndThreshold": 2750,
    "machineDetectionSilenceTimeout": 6000
  },
  "voicemailMessage": "<string>",
  "endCallMessage": "<string>",
  "endCallPhrases": [
    "<string>"
  ],
  "metadata": {},
  "serverUrl": "<string>",
  "serverUrlSecret": "<string>",
  "analysisPlan": {
    "summaryPrompt": "<string>",
    "summaryRequestTimeoutSeconds": 10.5,
    "structuredDataRequestTimeoutSeconds": 10.5,
    "successEvaluationPrompt": "<string>",
    "successEvaluationRubric": "NumericScale",
    "successEvaluationRequestTimeoutSeconds": 10.5,
    "structuredDataPrompt": "<string>",
    "structuredDataSchema": {
      "type": "string",
      "items": {},
      "properties": {},
      "description": "<string>",
      "required": [
        "<string>"
      ]
    }
  },
  "artifactPlan": {
    "videoRecordingEnabled": true
  },
  "messagePlan": {
    "idleMessages": [
      "<string>"
    ],
    "idleMessageMaxSpokenCount": 5.5,
    "idleTimeoutSeconds": 7.5
  },
  "id": "<string>",
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Assistants

Calls

Squads

Phone Numbers

Tools

Files

Analytics

Call Logs

Server and Client

Create Assistant

Authorizations

Body

Response