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

initator	string	Who was responsible for starting this call. Typically set to INITIATOR_AGENT for outgoing calls and left as the default (INITIATOR_USER) otherwise.
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.
voice	string	The voice the AI will use for speaking. There are currently two options: lily (default) and terrence. 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.

Examples

List All Calls

cURL

curl --request GET \
--url https://api.ultravox.ai/api/voices \
--header 'X-API-Key: aBCDef.123456'

JavaScript

fetch('https://api.ultravox.ai/api/voices', {
  method: 'GET',
  headers: {
    'X-API-Key': 'aBCDef.123456'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Response

cURL

{
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "lily",
      "description": "Default Female",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/lily_preview.wav"
    },
    {
      "name": "terrence",
      "description": "Default Male",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/terrence_preview.wav"
    }
  ]
}

JavaScript

{
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "lily",
      "description": "Default Female",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/lily_preview.wav"
    },
    {
      "name": "terrence",
      "description": "Default Male",
      "previewUrl": "https://zfmrfvimiaqahezndsse.supabase.co/storage/v1/object/public/ultravox-voice-previews/terrence_preview.wav"
    }
  ]
}