Get Call

GET

api

calls

{call_id}

curl --request GET \
  --url https://api.ultravox.ai/api/calls/{call_id} \
  --header 'X-API-Key: <api-key>'

{
  "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",
  "endReason": "unjoined",
  "firstSpeaker": "FIRST_SPEAKER_AGENT",
  "firstSpeakerSettings": {
    "user": {
      "fallback": {
        "delay": "<string>",
        "text": "<string>",
        "prompt": "<string>"
      }
    },
    "agent": {
      "uninterruptible": true,
      "text": "<string>",
      "prompt": "<string>",
      "delay": "<string>"
    }
  },
  "inactivityMessages": [
    {
      "duration": "<string>",
      "message": "<string>",
      "endBehavior": "END_BEHAVIOR_UNSPECIFIED"
    }
  ],
  "initialOutputMedium": "MESSAGE_MEDIUM_VOICE",
  "joinTimeout": "30s",
  "joinUrl": "<string>",
  "languageHint": "<string>",
  "maxDuration": "3600s",
  "medium": {
    "webRtc": {},
    "twilio": {},
    "serverWebSocket": {
      "inputSampleRate": 123,
      "outputSampleRate": 123,
      "clientBufferSizeMs": 123
    },
    "telnyx": {},
    "plivo": {},
    "exotel": {},
    "sip": {
      "incoming": {},
      "outgoing": {
        "to": "<string>",
        "from": "<string>",
        "username": "<string>",
        "password": "<string>"
      }
    }
  },
  "model": "fixie-ai/ultravox",
  "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
    },
    "cartesia": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "emotion": "<string>",
      "emotions": [
        "<string>"
      ]
    },
    "playHt": {
      "userId": "<string>",
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "quality": "<string>",
      "temperature": 123,
      "emotion": 123,
      "voiceGuidance": 123,
      "styleGuidance": 123,
      "textGuidance": 123,
      "voiceConditioningSeconds": 123
    },
    "lmnt": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "conversational": true
    }
  },
  "transcriptOptional": true,
  "errorCount": 0,
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>",
    "frameActivationThreshold": 123
  },
  "shortSummary": "<string>",
  "summary": "<string>",
  "experimentalSettings": "<any>",
  "metadata": {},
  "initialState": {},
  "requestContext": "<any>",
  "dataConnectionConfig": {
    "websocketUrl": "<string>",
    "audioConfig": {
      "sampleRate": 123,
      "channelMode": "CHANNEL_MODE_UNSPECIFIED"
    }
  }
}

Authorizations

X-API-Key

string

header

required

API key

Path Parameters

call_id

string

required

Response

200 - application/json

callId

string

required

clientVersion

string | null

required

The version of the client that joined this call.

created

string

required

joined

string | null

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
system_error - System error

Available options:

unjoined,

hangup,

agent_hangup,

timeout,

connection_error,

system_error

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.

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:0

required

The number of errors in this call.

shortSummary

string | null

required

A short summary of the call.

summary

string | null

required

A summary of the 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.

initialState

object

required

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

requestContext

any

required

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.

A message the agent should say after some duration. The duration's meaning varies depending on the context.

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.

medium.webRtc

object

The call will use WebRTC with the Ultravox client SDK. This is the default.

medium.twilio

object

The call will use Twilio's "Media Streams" protocol. Once you have a join URL from starting a call, include it in your TwiML like so: <Connect><Stream url=${your-join-url} /></Connect> This works for both inbound and outbound calls.

medium.serverWebSocket

object

The call will use a plain websocket connection. This is unlikely to yield an acceptable user experience if used from a browser or mobile client, but may be suitable for a server-to-server connection. This option provides a simple way to connect your own server to an Ultravox inference instance.

medium.telnyx

object

The call will use Telnyx's media streaming protocol. Once you have a join URL from starting a call, include it in your TexML like so: <Connect><Stream url=${your-join-url} bidirectionalMode="rtp" /></Connect> This works for both inbound and outbound calls.

medium.plivo

object

The call will use Plivo's AudioStreams protocol. Once you have a join URL from starting a call, include it in your Plivo XML like so: <Stream keepCallAlive="true" bidirectional="true" contentType="audio/x-l16;rate=16000">${your-join-url}</Stream> This works for both inbound and outbound calls.

medium.exotel

object

The call will use Exotel's "Voicebot" protocol. Once you have a join URL from starting a call, provide it to Exotel as the wss target URL for your Voicebot (either directly or more likely dynamically from your own server).

medium.sip

object

The call will be connected using Session Initiation Protocol (SIP). Note that SIP incurs additional charges and must be enabled for your account.

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

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.

transcriptOptional

boolean

default:true

deprecated

Indicates whether a transcript is optional for the call.

vadSettings

object

VAD settings for the call.

dataConnectionConfig

object

Settings for exchanging data messages with an additional participant.

List Calls Create Call

curl --request GET \
  --url https://api.ultravox.ai/api/calls/{call_id} \
  --header 'X-API-Key: <api-key>'

{
  "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",
  "endReason": "unjoined",
  "firstSpeaker": "FIRST_SPEAKER_AGENT",
  "firstSpeakerSettings": {
    "user": {
      "fallback": {
        "delay": "<string>",
        "text": "<string>",
        "prompt": "<string>"
      }
    },
    "agent": {
      "uninterruptible": true,
      "text": "<string>",
      "prompt": "<string>",
      "delay": "<string>"
    }
  },
  "inactivityMessages": [
    {
      "duration": "<string>",
      "message": "<string>",
      "endBehavior": "END_BEHAVIOR_UNSPECIFIED"
    }
  ],
  "initialOutputMedium": "MESSAGE_MEDIUM_VOICE",
  "joinTimeout": "30s",
  "joinUrl": "<string>",
  "languageHint": "<string>",
  "maxDuration": "3600s",
  "medium": {
    "webRtc": {},
    "twilio": {},
    "serverWebSocket": {
      "inputSampleRate": 123,
      "outputSampleRate": 123,
      "clientBufferSizeMs": 123
    },
    "telnyx": {},
    "plivo": {},
    "exotel": {},
    "sip": {
      "incoming": {},
      "outgoing": {
        "to": "<string>",
        "from": "<string>",
        "username": "<string>",
        "password": "<string>"
      }
    }
  },
  "model": "fixie-ai/ultravox",
  "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
    },
    "cartesia": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "emotion": "<string>",
      "emotions": [
        "<string>"
      ]
    },
    "playHt": {
      "userId": "<string>",
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "quality": "<string>",
      "temperature": 123,
      "emotion": 123,
      "voiceGuidance": 123,
      "styleGuidance": 123,
      "textGuidance": 123,
      "voiceConditioningSeconds": 123
    },
    "lmnt": {
      "voiceId": "<string>",
      "model": "<string>",
      "speed": 123,
      "conversational": true
    }
  },
  "transcriptOptional": true,
  "errorCount": 0,
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>",
    "frameActivationThreshold": 123
  },
  "shortSummary": "<string>",
  "summary": "<string>",
  "experimentalSettings": "<any>",
  "metadata": {},
  "initialState": {},
  "requestContext": "<any>",
  "dataConnectionConfig": {
    "websocketUrl": "<string>",
    "audioConfig": {
      "sampleRate": 123,
      "channelMode": "CHANNEL_MODE_UNSPECIFIED"
    }
  }
}

Accounts

Agents

Calls, Messages, Stages

Corpora, Query, Sources

Tools

Voices

Webhooks

Schema

Other

Authorizations

Path Parameters

Response