Calls

API Key Required

The Ultravox API requires an API key. For more details see Authentication.

Calls are what drive all speech-to-speech interactions between your end users and AI. At their most basic level, calls consist of a set of instructions to instruct the LLM how to behave (i.e. the systemPrompt) and the selection of the voice the AI should use when speaking.

List Calls

GET /calls

Lists all calls that have been created. Account scoped.

Parameters

Parameters

cursor	Pagination cursor.

Request Body

none

Response

callId	string	Unique identifier for the call.
created	string	Datetime in UTC when the call was created.
ended	string	Datetime in UTC when the call was ended. Will be null upon call creation and while call is underway.
model	string	Name of the model used for the call.
systemPrompt	string	The system prompt used to create the call.
temperature	float	The temperature setting used for the model in this call.
voice	string	The name of the AI voice used for the call.
languageHint	string	BCP47 identifier used as a hint to indentify the user’s spoken language.
maxDuration	string	Maximum length (in seconds) that was set for the call.
timeExceededMessage	string	Message that the agent will say if the call reaches the maxDuration.
joinUrl	string	URL to use with the ultravox client library to join (AKA start) the call.

Create Call

POST /calls

Creates a new call using the specified system prompt. Account scoped.

Optional parameters can be used to specify voice, temperature, language hint, and recordingEnabled.

An optional query parameter called priorCallId can be provided to continue a previous conversation. If used, all properties of the prior call (e.g. systemPrompt, voice, etc.) will be used for the new call. Can also be used in combination with overriding individual properties (e.g. inherit all properties but override the voice).

Parameters

Parameters

priorCallId	string	The UUID of an existing call. If provided, the new call will inherit all call properties (unless overridden in the current request body). The prior call’s message history will be used in place of initialMessages. Setting initialMessages in the body is not allowed.

Request Body

initiator	string	Who was responsible for starting this call. Typically set to INITIATOR_AGENT for outgoing calls and left as the default (INITIATOR_USER) otherwise.
initialOutputMedium	string	The initial medium (MESSAGE_MEDIUM_VOICE or MESSAGE_MEDIUM_TEXT) to use for the call. Defaults to MESSAGE_MEDIUM_VOICE. Once the call has started, the output medium can be changed by the client using setOutputMedium.
languageHint	string	A hint about the language to be used if your end users are speaking a language other than English. Must be a valid BCP47 language code. Best effort is made to select the closest supported language. (default: “en”)
maxDuration	string	Maximum length (in seconds) for the call. Must contain s and can be fractional. E.g. 300s or 245.5s. Used to limit the length of the call. Optionally, set timeExceededMessage to have the agent say a message when the allotted time is reached. For the free plan, defaults to amount of free time remaining (less any calls that are currently in-progress). For paid plans, defaults to the system maximum of one hour (“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. Can be "webRtc":{} (default) or "twilio":{}.
model	string	The model to be used for the call. If not specified, defaults to fixie-ai/ultravox. See available models.
recordingEnabled	boolean	A recording will be saved for the call when set to true. Recording can be retrieved via GET /calls/{call_id}/recording. Default value of false.
selectedTools	array	Each object is a tool selected for the call.
systemPrompt required	string	The system prompt to use for the AI.
temperature	float	The temperature setting for the model. Value between 0.0 and 1.0. (default: 0.0)
timeExceededMessage	string	Message that the agent will say if the call reaches the maxDuration.
transcriptOptional	boolean	Defaults to true. Setting to false (not recommended) enables live user transcripts at the expense of latency. Furthermore, these transcripts may not match what the model actually hears.
voice	string	The voice the AI will use for speaking. If not specified, defaults to Mark. See List Voices for all available voices. Please contact us if you have other voice requirements.

Response

callId	string	Unique identifier for the call.
created	string	Datetime in UTC when the call was created.
ended	string	Datetime in UTC when the call was ended. Will be null upon call creation and while call is underway.
model	string	Name of the model used for the call.
systemPrompt	string	The system prompt used to create the call.
temperature	float	The temperature setting used for the model in this call.
voice	string	The name of the AI voice used for the call.
languageHint	string	BCP47 identifier used as a hint to indentify the user’s spoken language.
maxDuration	string	Maximum length (in seconds) that was set for the call.
timeExceededMessage	string	Message that the agent will say if the call reaches the maxDuration.
joinUrl	string	URL to use with the ultravox client library to join (AKA start) the call.

Get Call

GET /calls/{call_id}

Gets details for the call with call_id specified in the path. Account scoped.

Parameters

Parameters

callId required	Unique identifier for the call to retrieve.

Request Body

None

Response

callId	string	Unique identifier for the call.
created	string	Datetime in UTC when the call was created.
ended	string	Datetime in UTC when the call was ended. Will be null upon call creation and while call is underway.
model	string	Name of the model used for the call.
systemPrompt	string	The system prompt used to create the call.
temperature	float	The temperature setting used for the model in this call.
voice	string	The name of the AI voice used for the call.
languageHint	string	BCP47 identifier used as a hint to indentify the user’s spoken language.
joinUrl	string	URL to use with the ultravox client library to join (AKA start) the call.

Delete Call

DELETE /calls/{call_id}

Deletes the specified call.

Parameters

Parameters

callId required	Unique identifier for the call to delete.

Request Body

No request body

Response

None

List Call Messages

GET /calls/{call_id}/messages

Lists all messages generated during the given call.

Parameters

Parameters

callId required	Unique identifier of the call for which messages are being retrieved.
cursor	Pagination cursor.

Request Body

No request body

Response

next	string	URL with the cursor value for the next page of results.
previous	string	URL with the cursor value for the previous page of results.
results	array	Array of message objects. Each message object contains:
ordinal	number	Ordinal position of the message. Used to determine sequence.
role	string	Role that generated the message. Corresponds to one of the following: USER or AGENT.
text	string	The message text.

Get Call Recording

GET /calls/{call_id}/recording

Returns a link to the recording of the call (via a 302 redirect to the file location). The recording only becomes available after the call ends. If the recording is not yet available, a 425 (Too Early) HTTP status will be returned.

Note

Call recordings are only generated if you add "recordingEnabled": true to the request body when creating a call.

Parameters

Parameters

callId required	Unique identifier of the call for which the recording is being retrieved.

Request Body

No request body

Response

detail	string	Only returned if call recording was not enabled. If a recording was enabled, there is no response body and the call recording location is provided via a 302 redirect.