Create Call

POST

api

calls

object

systemPrompt

string

temperature

number

model

string

voice

string

languageHint

string

initialMessages

array

joinTimeout

string

maxDuration

string

timeExceededMessage

string

inactivityMessages

array

selectedTools

array

medium

object

webRtc

object

twilio

object

serverWebSocket

object

inputSampleRate

integer

outputSampleRate

integer

clientBufferSizeMs

integer

telnyx

object

plivo

object

initiator

enum<string>

recordingEnabled

boolean

firstSpeaker

enum<string>

transcriptOptional

boolean

initialOutputMedium

enum<string>

vadSettings

object

turnEndpointDelay

string

minimumTurnDuration

string

minimumInterruptionDuration

string

Authorizations

X-API-Key

string

headerrequired

API key

Query Parameters

priorCallId

string

The UUID of a prior call. When specified, the new call will use the same properites as the prior call unless overriden in this request's body. The new call will also use the prior call's message history as its own initial_messages. (It's illegal to also set initial_messages in the body.)

Body

application/json

A request to start a call.

systemPrompt

string

The system prompt provided to the model during generations.

temperature

number

The model temperature, between 0 and 1. Defaults to 0.

model

string

The model used for generations. Defaults to fixie-ai/ultravox.

voice

string

The ID (or name if unique) of the voice the agent should use for this call.

languageHint

string

A BCP47 language code that may be used to guide speech recognition and synthesis.

initialMessages

object[]

The conversation history to start from for this call.

joinTimeout

string

A timeout for joining the call. Defaults to 30 seconds.

maxDuration

string

The maximum duration of the call. Defaults to 1 hour.

timeExceededMessage

string

What the agent should say immediately before hanging up if the call's time limit is reached.

inactivityMessages

object[]

Messages spoken by the agent when the user is inactive for the specified duration. Durations are cumulative, so a message m > 1 with duration 30s will be spoken 30 seconds after message m-1.

selectedTools

object[]

The tools available to the agent for (the first stage of) this call.

selectedTools.toolId

string

The ID of an existing base tool.

selectedTools.toolName

string

The name of an existing base tool. The name must uniquely identify the tool.

selectedTools.temporaryTool

object

A temporary tool definition, available only for this call (and subsequent calls created using priorCallId without overriding selected tools).

selectedTools.temporaryTool.modelToolName

string

The name of the tool, as presented to the model. Must match ^[a-zA-Z0-9_-]{1,64}$.

selectedTools.temporaryTool.description

string

The description of the tool.

selectedTools.temporaryTool.dynamicParameters

object[]

The parameters that the tool accepts.

selectedTools.temporaryTool.staticParameters

object[]

The static parameters added when the tool is invoked.

selectedTools.temporaryTool.automaticParameters

object[]

Additional parameters that are automatically set by the system when the tool is invoked.

selectedTools.temporaryTool.requirements

object

Requirements that must be fulfilled when creating a call for the tool to be used.

selectedTools.temporaryTool.timeout

string

The maximum amount of time the tool is allowed for execution. The conversation is frozen while tools run, so prefer sticking to the default unless you're comfortable with that consequence. If your tool is too slow for the default and can't be made faster, still try to keep this timeout as low as possible.

selectedTools.temporaryTool.precomputable

boolean

The tool is guaranteed to be non-mutating, repeatable, and free of side-effects. Such tools can safely be executed speculatively, reducing their effective latency. However, the fact they were called may not be reflected in the call history if their result ends up unused.

selectedTools.temporaryTool.http

object

Details for an HTTP tool.

selectedTools.temporaryTool.client

object

Details for a client-implemented tool. Only body parameters are allowed for client tools.

selectedTools.nameOverride

string

An override for the model_tool_name. This is primarily useful when using multiple instances of the same durable tool (presumably with different parameter overrides.) The set of tools used within a call must have a unique set of model names and every name must match this pattern: ^[a-zA-Z0-9_-]{1,64}$.

selectedTools.authTokens

object

Auth tokens used to satisfy the tool's security requirements.

selectedTools.parameterOverrides

object

Static values to use in place of dynamic parameters. Any parameter included here will be hidden from the model and the static value will be used instead. Some tools may require certain parameters to be overridden, but any parameter can be overridden regardless of whether it is required to be.

medium

object

The medium used for this call.

initiator

enum<string>

Who was responsible for staring this call. Typically set to agent for outgoing calls and left as the default (user) otherwise. DEPRECATED: Use first_speaker instead. Will be removed in November 2024.

Available options:

INITIATOR_UNSPECIFIED,

INITIATOR_USER,

INITIATOR_AGENT

recordingEnabled

boolean

Whether the call should be recorded.

firstSpeaker

enum<string>

Who should talk first when the call starts. Typically set to FIRST_SPEAKER_USER for outgoing calls and left as the default (FIRST_SPEAKER_AGENT) otherwise.

Available options:

FIRST_SPEAKER_UNSPECIFIED,

FIRST_SPEAKER_AGENT,

FIRST_SPEAKER_USER

transcriptOptional

boolean

Indicates whether a transcript is optional for the call.

initialOutputMedium

enum<string>

The medium to use for the call initially. May be altered by the client later. Defaults to voice.

Available options:

MESSAGE_MEDIUM_UNSPECIFIED,

MESSAGE_MEDIUM_VOICE,

MESSAGE_MEDIUM_TEXT

vadSettings

object

VAD settings for the call.

Response

201 - application/json

callId

string

required

clientVersion

string | null

required

The version of the client that joined this call.

created

string

required

ended

string | null

required

endReason

required

The reason the call ended.

unjoined - Client never joined
hangup - Client hung up
timeout - Call timed out
connection_error - Connection error

Available options:

unjoined,

hangup,

timeout,

connection_error

firstSpeaker

enum<string>

required

Who was supposed to talk first when the call started. Typically set to FIRST_SPEAKER_USER for outgoing calls and left as the default (FIRST_SPEAKER_AGENT) otherwise.

Available options:

FIRST_SPEAKER_AGENT,

FIRST_SPEAKER_USER

initialOutputMedium

enum<string>

required

The medium used initially by the agent. May later be changed by the client.

Available options:

MESSAGE_MEDIUM_VOICE,

MESSAGE_MEDIUM_TEXT

joinUrl

string | null

required

errorCount

integer

default: 0required

The number of errors in this call.

inactivityMessages

object[]

Messages spoken by the agent when the user is inactive for the specified duration. Durations are cumulative, so a message m > 1 with duration 30s will be spoken 30 seconds after message m-1.

joinTimeout

string

default: 30s

languageHint

string | null

BCP47 language code that may be used to guide speech recognition.

Maximum length: 16

maxDuration

string

default: 3600s

medium

object

Details about a call's protocol. By default, calls occur over WebRTC using the Ultravox client SDK. Setting a different call medium will prepare the server for a call using a different protocol. At most one call medium may be set.

model

string

default: fixie-ai/ultravox

recordingEnabled

boolean

default: false

systemPrompt

string | null

temperature

number

default: 0

Required range: 0 < x < 1

timeExceededMessage

string | null

voice

string | null

transcriptOptional

boolean

default: true

Indicates whether a transcript is optional for the call.

vadSettings

object

VAD settings for the call.

Get Call List Call Messages

Accounts & API Keys

Calls, Messages, Stages

Tools

Voices

Webhooks

Schema

Other

Authorizations

Query Parameters

Body

Response