POST
/
api
/
calls

Authorizations

X-API-Key
string
header
required

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.

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. Deprecated. Prefer firstSpeakerSettings. If both are set, they must match.

Available options:
FIRST_SPEAKER_UNSPECIFIED,
FIRST_SPEAKER_AGENT,
FIRST_SPEAKER_USER
firstSpeakerSettings
object

The settings for the initial message to get a conversation started. Defaults to agent: {} which means the agent will start the conversation with an (interruptible) greeting generated based on the system prompt and any initial messages. (If first_speaker is set and this is not, first_speaker will be used instead.)

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.

initialMessages
object[]

The conversation history to start from for this 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
joinTimeout
string

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

languageHint
string

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

maxDuration
string

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

medium
object

The medium used for this call.

model
string

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

recordingEnabled
boolean

Whether the call should be recorded.

selectedTools
object[]

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

systemPrompt
string

The system prompt provided to the model during generations.

temperature
number

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

timeExceededMessage
string

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

transcriptOptional
boolean

Indicates whether a transcript is optional for the call.

vadSettings
object

VAD settings for the call.

voice
string

The ID (or name if unique) of the voice the agent should use for this 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
  • agent_hangup - Agent hung up
  • timeout - Call timed out
  • connection_error - Connection error
Available options:
unjoined,
hangup,
agent_hangup,
timeout,
connection_error
errorCount
integer
default:
0
required

The number of errors in this call.

firstSpeaker
enum<string>
requireddeprecated

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
firstSpeakerSettings
object
required

Settings for the initial message to get the call started.

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
shortSummary
string | null
required

A short summary of the call.

summary
string | null
required

A summary of the 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
transcriptOptional
boolean
default:
true

Indicates whether a transcript is optional for the call.

vadSettings
object

VAD settings for the call.

voice
string | null