Call Definition - Ultravox Docs

callId

string<uuid>

required

read-only

clientVersion

string | null

required

The version of the client that joined this call.

created

string<date-time>

required

read-only

joined

string<date-time> | null

required

ended

string<date-time> | 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
system_error - System error

Available options:

unjoined,

hangup,

agent_hangup,

timeout,

connection_error,

system_error

billedDuration

string | null

required

billedSideInputTokens

integer | null

required

billedSideOutputTokens

integer | null

required

billingStatus

enum<string>

required

BILLING_STATUS_PENDING* - The call hasn't been billed yet, but will be in the future. This is the case for ongoing calls for example. (Note: Calls created before May 28, 2025 may have this status even if they were billed.)
BILLING_STATUS_FREE_CONSOLE* - The call was free because it was initiated on https://app.ultravox.ai.
BILLING_STATUS_FREE_ZERO_EFFECTIVE_DURATION* - The call was free because its effective duration was zero. (Note: There may still be a non-zero sip bill in this case.)
BILLING_STATUS_FREE_MINUTES* - The call was unbilled but counted against the account's free minutes. (Note: There may still be a non-zero sip bill in this case.)
BILLING_STATUS_FREE_SYSTEM_ERROR* - The call was free because it ended due to a system error.
BILLING_STATUS_FREE_OTHER* - The call is in an undocumented free billing state.
BILLING_STATUS_BILLED* - The call was billed. See billedDuration for the billed duration.
BILLING_STATUS_REFUNDED* - The call was billed but was later refunded.
BILLING_STATUS_UNSPECIFIED* - The call is in an unexpected billing state. Please contact support.

Available options:

BILLING_STATUS_PENDING,

BILLING_STATUS_FREE_CONSOLE,

BILLING_STATUS_FREE_ZERO_EFFECTIVE_DURATION,

BILLING_STATUS_FREE_MINUTES,

BILLING_STATUS_FREE_SYSTEM_ERROR,

BILLING_STATUS_FREE_OTHER,

BILLING_STATUS_BILLED,

BILLING_STATUS_REFUNDED,

BILLING_STATUS_UNSPECIFIED

firstSpeaker

enum<string>

required

deprecated

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.

Show child attributes

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.

agent

object

required

The agent used for this call.

Show child attributes

agentId

string | null

required

The ID of the agent used for this call.

experimentalSettings

any

required

Experimental settings for the call.

metadata

object

required

Optional metadata key-value pairs to associate with the call. All values must be strings.

Show child attributes

initialState

object

required

The initial state of the call which is readable/writable by tools.

Show child attributes

requestContext

any

required

sipDetails

object

required

SIP details for the call, if applicable.

Show child attributes

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.

Show child attributes

joinTimeout

string

default:30s

languageHint

string | null

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

Maximum string 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.

Show child attributes

model

string

default:ultravox-v0.7

recordingEnabled

boolean

default:false

retentionPolicy

The retention policy for the call's data after it ends.

retain - Retain indefinitely
auto_delete - Auto-delete after billing

Available options:

retain,

auto_delete

systemPrompt

string | null

temperature

number<double>

default:0

Required range: 0 <= x <= 1

timeExceededMessage

string | null

voice

string | null

externalVoice

object

A voice not known to Ultravox Realtime that can nonetheless be used for a call. Such voices are significantly less validated than normal voices and you'll be responsible for your own TTS-related errors. Exactly one field must be set.

Show child attributes

voiceOverrides

object

Overrides for the selected voice.

Show child attributes

transcriptOptional

boolean

default:true

deprecated

Indicates whether a transcript is optional for the call.

vadSettings

object

VAD settings for the call.

Show child attributes

dataConnectionConfig

object

Settings for exchanging data messages with an additional participant.

Show child attributes

callbacks

object

Callbacks configuration for the call.

Show child attributes

Base Tool Definition

⌘I

{
  "callId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientVersion": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "joined": "2023-11-07T05:31:56Z",
  "ended": "2023-11-07T05:31:56Z",
  "billedDuration": "<string>",
  "billedSideInputTokens": 123,
  "billedSideOutputTokens": 123,
  "firstSpeakerSettings": {
    "user": {
      "fallback": {
        "delay": "<string>",
        "text": "<string>",
        "prompt": "<string>"
      }
    },
    "agent": {
      "uninterruptible": true,
      "text": "<string>",
      "prompt": "<string>",
      "delay": "<string>"
    }
  },
  "joinUrl": "<string>",
  "shortSummary": "<string>",
  "summary": "<string>",
  "agent": {
    "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>"
  },
  "agentId": "<string>",
  "experimentalSettings": "<unknown>",
  "metadata": {},
  "initialState": {},
  "requestContext": "<unknown>",
  "sipDetails": {
    "billedDuration": "<string>"
  },
  "inactivityMessages": [
    {
      "duration": "<string>",
      "message": "<string>"
    }
  ],
  "joinTimeout": "30s",
  "languageHint": "<string>",
  "maxDuration": "3600s",
  "medium": {
    "webRtc": {
      "dataMessages": {
        "pong": true,
        "state": true,
        "transcript": true,
        "clientToolInvocation": true,
        "dataConnectionToolInvocation": true,
        "playbackClearBuffer": true,
        "callStarted": true,
        "debug": true,
        "callEvent": true,
        "toolUsed": true,
        "userStartedSpeaking": true,
        "userStoppedSpeaking": true,
        "invokingTool": true
      }
    },
    "twilio": {
      "outgoing": {
        "to": "<string>",
        "from": "<string>",
        "additionalParams": {}
      },
      "dtmfHandling": {
        "ignore": true,
        "userTextMessage": {
          "text": "<string>"
        }
      }
    },
    "serverWebSocket": {
      "inputSampleRate": 123,
      "outputSampleRate": 123,
      "clientBufferSizeMs": 123,
      "dataMessages": {
        "pong": true,
        "state": true,
        "transcript": true,
        "clientToolInvocation": true,
        "dataConnectionToolInvocation": true,
        "playbackClearBuffer": true,
        "callStarted": true,
        "debug": true,
        "callEvent": true,
        "toolUsed": true,
        "userStartedSpeaking": true,
        "userStoppedSpeaking": true,
        "invokingTool": true
      },
      "mediaIdleTimeout": "<string>"
    },
    "telnyx": {
      "outgoing": {
        "to": "<string>",
        "from": "<string>",
        "additionalParams": {}
      },
      "dtmfHandling": {
        "ignore": true,
        "userTextMessage": {
          "text": "<string>"
        }
      }
    },
    "plivo": {
      "outgoing": {
        "to": "<string>",
        "from": "<string>",
        "additionalParams": {}
      },
      "dtmfHandling": {
        "ignore": true,
        "userTextMessage": {
          "text": "<string>"
        }
      }
    },
    "exotel": {
      "dtmfHandling": {
        "ignore": true,
        "userTextMessage": {
          "text": "<string>"
        }
      }
    },
    "sip": {
      "incoming": {},
      "outgoing": {
        "to": "<string>",
        "from": "<string>",
        "username": "<string>",
        "password": "<string>"
      }
    }
  },
  "model": "ultravox-v0.7",
  "recordingEnabled": false,
  "systemPrompt": "<string>",
  "temperature": 0,
  "timeExceededMessage": "<string>",
  "voice": "<string>",
  "externalVoice": {
    "elevenLabs": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "useSpeakerBoost": true,
      "style": 123,
      "similarityBoost": 123,
      "stability": 123,
      "pronunciationDictionaries": [
        {
          "dictionaryId": "<string>",
          "versionId": "<string>"
        }
      ],
      "optimizeStreamingLatency": 123,
      "maxSampleRate": 123
    },
    "cartesia": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "emotion": "<string>",
      "emotions": [
        "<string>"
      ],
      "generationConfig": {
        "volume": 123,
        "speed": 123,
        "emotion": "<string>",
        "pronunciationDictId": "<string>"
      }
    },
    "lmnt": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "conversational": true
    },
    "google": {
      "voiceId": "<string>",
      "speakingRate": 123
    },
    "inworld": {
      "voiceId": "<string>",
      "modelId": "<string>",
      "speakingRate": 123,
      "temperature": 123,
      "applyTextNormalization": true
    },
    "respeecher": {
      "voiceId": "<string>",
      "model": "<string>",
      "seed": 123,
      "temperature": 123,
      "topK": 123,
      "topP": 123,
      "minP": 123,
      "presencePenalty": 123,
      "repetitionPenalty": 123,
      "frequencyPenalty": 123
    },
    "generic": {
      "url": "<string>",
      "headers": {},
      "body": {},
      "responseSampleRate": 123,
      "responseWordsPerMinute": 123,
      "responseMimeType": "<string>",
      "jsonAudioFieldPath": "<string>"
    }
  },
  "voiceOverrides": {
    "elevenLabs": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "useSpeakerBoost": true,
      "style": 123,
      "similarityBoost": 123,
      "stability": 123,
      "pronunciationDictionaries": [
        {
          "dictionaryId": "<string>",
          "versionId": "<string>"
        }
      ],
      "optimizeStreamingLatency": 123,
      "maxSampleRate": 123
    },
    "cartesia": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "emotion": "<string>",
      "emotions": [
        "<string>"
      ],
      "generationConfig": {
        "volume": 123,
        "speed": 123,
        "emotion": "<string>",
        "pronunciationDictId": "<string>"
      }
    },
    "lmnt": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "conversational": true
    },
    "google": {
      "voiceId": "<string>",
      "speakingRate": 123
    },
    "inworld": {
      "voiceId": "<string>",
      "modelId": "<string>",
      "speakingRate": 123,
      "temperature": 123,
      "applyTextNormalization": true
    },
    "respeecher": {
      "voiceId": "<string>",
      "model": "<string>",
      "seed": 123,
      "temperature": 123,
      "topK": 123,
      "topP": 123,
      "minP": 123,
      "presencePenalty": 123,
      "repetitionPenalty": 123,
      "frequencyPenalty": 123
    },
    "generic": {
      "url": "<string>",
      "headers": {},
      "body": {},
      "responseSampleRate": 123,
      "responseWordsPerMinute": 123,
      "responseMimeType": "<string>",
      "jsonAudioFieldPath": "<string>"
    }
  },
  "transcriptOptional": true,
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>",
    "frameActivationThreshold": 123
  },
  "dataConnectionConfig": {
    "websocketUrl": "<string>",
    "audioConfig": {
      "sampleRate": 123
    },
    "dataMessages": {
      "pong": true,
      "state": true,
      "transcript": true,
      "clientToolInvocation": true,
      "dataConnectionToolInvocation": true,
      "playbackClearBuffer": true,
      "callStarted": true,
      "debug": true,
      "callEvent": true,
      "toolUsed": true,
      "userStartedSpeaking": true,
      "userStoppedSpeaking": true,
      "invokingTool": true
    },
    "headers": {}
  },
  "callbacks": {
    "joined": {
      "url": "<string>",
      "secrets": [
        "<string>"
      ]
    },
    "ended": {
      "url": "<string>",
      "secrets": [
        "<string>"
      ]
    },
    "billed": {
      "url": "<string>",
      "secrets": [
        "<string>"
      ]
    }
  }
}

Documentation Index