Create Call

POST

api

calls

curl --request POST \
  --url https://api.ultravox.ai/api/calls \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "systemPrompt": "<string>",
  "temperature": 123,
  "model": "<string>",
  "voice": "<string>",
  "languageHint": "<string>",
  "initialMessages": [
    {
      "role": "MESSAGE_ROLE_UNSPECIFIED",
      "text": "<string>",
      "invocationId": "<string>",
      "toolName": "<string>",
      "errorDetails": "<string>",
      "medium": "MESSAGE_MEDIUM_UNSPECIFIED",
      "callStageMessageIndex": 123,
      "callStageId": "<string>"
    }
  ],
  "joinTimeout": "<string>",
  "maxDuration": "<string>",
  "timeExceededMessage": "<string>",
  "inactivityMessages": [
    {
      "duration": "<string>",
      "message": "<string>",
      "endBehavior": "END_BEHAVIOR_UNSPECIFIED"
    }
  ],
  "selectedTools": [
    {
      "toolId": "<string>",
      "toolName": "<string>",
      "temporaryTool": {
        "modelToolName": "<string>",
        "description": "<string>",
        "dynamicParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "schema": {},
            "required": true
          }
        ],
        "staticParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "value": "<any>"
          }
        ],
        "automaticParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "knownValue": "KNOWN_PARAM_UNSPECIFIED"
          }
        ],
        "requirements": {
          "httpSecurityOptions": {
            "options": [
              {
                "requirements": {},
                "ultravoxCallTokenRequirement": {
                  "scopes": [
                    "<string>"
                  ]
                }
              }
            ]
          },
          "requiredParameterOverrides": [
            "<string>"
          ]
        },
        "timeout": "<string>",
        "precomputable": true,
        "http": {
          "baseUrlPattern": "<string>",
          "httpMethod": "<string>"
        },
        "client": {}
      },
      "nameOverride": "<string>",
      "authTokens": {},
      "parameterOverrides": {}
    }
  ],
  "medium": {
    "webRtc": {},
    "twilio": {},
    "serverWebSocket": {
      "inputSampleRate": 123,
      "outputSampleRate": 123,
      "clientBufferSizeMs": 123
    },
    "telnyx": {},
    "plivo": {},
    "exotel": {}
  },
  "recordingEnabled": true,
  "firstSpeaker": "FIRST_SPEAKER_UNSPECIFIED",
  "transcriptOptional": true,
  "initialOutputMedium": "MESSAGE_MEDIUM_UNSPECIFIED",
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>"
  },
  "firstSpeakerSettings": {
    "user": {},
    "agent": {
      "uninterruptible": true,
      "text": "<string>"
    }
  },
  "experimentalSettings": {}
}'

{
  "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": {},
    "agent": {
      "uninterruptible": true,
      "text": "<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": {}
  },
  "model": "fixie-ai/ultravox",
  "recordingEnabled": false,
  "systemPrompt": "<string>",
  "temperature": 0,
  "timeExceededMessage": "<string>",
  "voice": "<string>",
  "transcriptOptional": true,
  "errorCount": 0,
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>"
  },
  "shortSummary": "<string>",
  "summary": "<string>",
  "experimentalSettings": "<any>"
}

Authorizations

X-API-Key

string

header

required

API key

Query Parameters

enableGreetingPrompt

boolean

default:

true

Adds a prompt for a greeting if there's not an initial message that the model would naturally respond to (a user message or tool result).

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.

systemPrompt

string

The system prompt provided to the model during generations.

temperature

number

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

model

string

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

voice

string

The ID (or name if unique) of the voice the agent should use for this call.

languageHint

string

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

initialMessages

object[]

The conversation history to start from for this call.

joinTimeout

string

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

maxDuration

string

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

timeExceededMessage

string

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

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.

selectedTools

object[]

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

selectedTools.toolId

string

The ID of an existing base tool.

selectedTools.toolName

string

The name of an existing base tool. The name must uniquely identify the tool.

selectedTools.temporaryTool

object

A temporary tool definition, available only for this call (and subsequent calls created using priorCallId without overriding selected tools).

selectedTools.temporaryTool.modelToolName

string

The name of the tool, as presented to the model. Must match ^[a-zA-Z0-9_-]{1,64}$.

selectedTools.temporaryTool.description

string

The description of the tool.

selectedTools.temporaryTool.dynamicParameters

object[]

The parameters that the tool accepts.

selectedTools.temporaryTool.staticParameters

object[]

The static parameters added when the tool is invoked.

selectedTools.temporaryTool.automaticParameters

object[]

Additional parameters that are automatically set by the system when the tool is invoked.

selectedTools.temporaryTool.requirements

object

Requirements that must be fulfilled when creating a call for the tool to be used.

selectedTools.temporaryTool.timeout

string

The maximum amount of time the tool is allowed for execution. The conversation is frozen while tools run, so prefer sticking to the default unless you're comfortable with that consequence. If your tool is too slow for the default and can't be made faster, still try to keep this timeout as low as possible.

selectedTools.temporaryTool.precomputable

boolean

The tool is guaranteed to be non-mutating, repeatable, and free of side-effects. Such tools can safely be executed speculatively, reducing their effective latency. However, the fact they were called may not be reflected in the call history if their result ends up unused.

selectedTools.temporaryTool.http

object

Details for an HTTP tool.

selectedTools.temporaryTool.client

object

Details for a client-implemented tool. Only body parameters are allowed for client tools.

selectedTools.nameOverride

string

An override for the model_tool_name. This is primarily useful when using multiple instances of the same durable tool (presumably with different parameter overrides.) The set of tools used within a call must have a unique set of model names and every name must match this pattern: ^[a-zA-Z0-9_-]{1,64}$.

selectedTools.authTokens

object

Auth tokens used to satisfy the tool's security requirements.

selectedTools.parameterOverrides

object

Static values to use in place of dynamic parameters. Any parameter included here will be hidden from the model and the static value will be used instead. Some tools may require certain parameters to be overridden, but any parameter can be overridden regardless of whether it is required to be.

medium

object

The medium used for this call.

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).

recordingEnabled

boolean

Whether the call should be recorded.

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

transcriptOptional

boolean

Indicates whether a transcript is optional for the 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

vadSettings

object

VAD settings for the call.

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.)

experimentalSettings

object

Experimental settings for the call.

Response

201 - 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

Available options:

unjoined,

hangup,

agent_hangup,

timeout,

connection_error

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

errorCount

integer

default:

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.

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.

medium.webRtc

object

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

medium.twilio

object

medium.serverWebSocket

object

medium.telnyx

object

medium.plivo

object

medium.exotel

object

model

string

default:

fixie-ai/ultravox

recordingEnabled

boolean

default:

false

systemPrompt

string | null

temperature

number

default:

Required range: 0 < x < 1

timeExceededMessage

string | null

voice

string | null

transcriptOptional

boolean

default:

true

deprecated

Indicates whether a transcript is optional for the call.

vadSettings

object

VAD settings for the call.

Get Call List Call Messages

curl --request POST \
  --url https://api.ultravox.ai/api/calls \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "systemPrompt": "<string>",
  "temperature": 123,
  "model": "<string>",
  "voice": "<string>",
  "languageHint": "<string>",
  "initialMessages": [
    {
      "role": "MESSAGE_ROLE_UNSPECIFIED",
      "text": "<string>",
      "invocationId": "<string>",
      "toolName": "<string>",
      "errorDetails": "<string>",
      "medium": "MESSAGE_MEDIUM_UNSPECIFIED",
      "callStageMessageIndex": 123,
      "callStageId": "<string>"
    }
  ],
  "joinTimeout": "<string>",
  "maxDuration": "<string>",
  "timeExceededMessage": "<string>",
  "inactivityMessages": [
    {
      "duration": "<string>",
      "message": "<string>",
      "endBehavior": "END_BEHAVIOR_UNSPECIFIED"
    }
  ],
  "selectedTools": [
    {
      "toolId": "<string>",
      "toolName": "<string>",
      "temporaryTool": {
        "modelToolName": "<string>",
        "description": "<string>",
        "dynamicParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "schema": {},
            "required": true
          }
        ],
        "staticParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "value": "<any>"
          }
        ],
        "automaticParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "knownValue": "KNOWN_PARAM_UNSPECIFIED"
          }
        ],
        "requirements": {
          "httpSecurityOptions": {
            "options": [
              {
                "requirements": {},
                "ultravoxCallTokenRequirement": {
                  "scopes": [
                    "<string>"
                  ]
                }
              }
            ]
          },
          "requiredParameterOverrides": [
            "<string>"
          ]
        },
        "timeout": "<string>",
        "precomputable": true,
        "http": {
          "baseUrlPattern": "<string>",
          "httpMethod": "<string>"
        },
        "client": {}
      },
      "nameOverride": "<string>",
      "authTokens": {},
      "parameterOverrides": {}
    }
  ],
  "medium": {
    "webRtc": {},
    "twilio": {},
    "serverWebSocket": {
      "inputSampleRate": 123,
      "outputSampleRate": 123,
      "clientBufferSizeMs": 123
    },
    "telnyx": {},
    "plivo": {},
    "exotel": {}
  },
  "recordingEnabled": true,
  "firstSpeaker": "FIRST_SPEAKER_UNSPECIFIED",
  "transcriptOptional": true,
  "initialOutputMedium": "MESSAGE_MEDIUM_UNSPECIFIED",
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>"
  },
  "firstSpeakerSettings": {
    "user": {},
    "agent": {
      "uninterruptible": true,
      "text": "<string>"
    }
  },
  "experimentalSettings": {}
}'

{
  "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": {},
    "agent": {
      "uninterruptible": true,
      "text": "<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": {}
  },
  "model": "fixie-ai/ultravox",
  "recordingEnabled": false,
  "systemPrompt": "<string>",
  "temperature": 0,
  "timeExceededMessage": "<string>",
  "voice": "<string>",
  "transcriptOptional": true,
  "errorCount": 0,
  "vadSettings": {
    "turnEndpointDelay": "<string>",
    "minimumTurnDuration": "<string>",
    "minimumInterruptionDuration": "<string>"
  },
  "shortSummary": "<string>",
  "summary": "<string>",
  "experimentalSettings": "<any>"
}

Accounts

Calls, Messages, Stages

Corpora, Query, Sources

Tools

Voices

Webhooks

Schema

Other

Authorizations

Query Parameters

Body

Response