Skip to content
Ultravox API

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

cursorPagination cursor.

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

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

Get Call

GET /calls/{call_id}

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

Parameters

callId
required		Unique identifier for the call to retrieve.

List Call Messages

GET /calls/{call_id}/messages

Lists all messages generated during the given call.

Parameters

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

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.

Parameters

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

List Call Stages

GET /calls/{call_id}/stages

Lists all stages that occurred during the specified call. Stages represent distinct segments of the conversation where different parameters (e.g. system prompt or tools) may have been used.

Parameters

callId
required		Unique identifier of the call for which stages are being retrieved.
cursorPagination cursor.

Get Call Stage

GET /calls/{call_id}/stages/{call_stage_id}

Retrieves details for a specific stage of a call.

Parameters

callId
required		Unique identifier of the call.
callStageId
required		Unique identifier of the stage to retrieve.

List Call Stage Messages

GET /calls/{call_id}/stages/{call_stage_id}/messages

Lists all messages that were exchanged during a specific stage of a call.

Parameters

callId
required		Unique identifier of the call.
callStageId
required		Unique identifier of the stage.
cursorPagination cursor.

List Call Stage Tools

GET /calls/{call_id}/stages/{call_stage_id}/tools

Lists all tools that were available during a specific stage of a call.

Parameters

callId
required		Unique identifier of the call.
callStageId
required		Unique identifier of the stage.

List Call Tools

GET /calls/{call_id}/tools

Lists all tools that were available at any point during the call.

Parameters

callId
required		Unique identifier of the call.

More Info

This section contains additional details for some properties.

inactivityMessages

Inactivity messages allow your agent to gracefully handle periods of user silence and end the call after a period of user inactivity. This feature helps maintain engagement and ensures calls don’t remain open indefinitely when users have disconnected or finished their interaction.

  • Messages are Ordered → Messages are delivered by the agent in the order provided.
  • Message Durations are Cumulative → The first message is delivered when the user has been inactive for its duration. Each subsequent message m is delivered its duration after message m-1 (provided the user remains inactive).
  • User Interactions Reset → Any activity from the user will reset the message sequence.
  • Different Behaviors → Messages can have different end behaviors and can terminate the call.
Best Practices
  • Keep messages concise and natural-sounding.
  • Start with friendly check-in messages before moving to call termination.
  • Provide clear context in messages if the call will be terminated.
Message Format

When creating a new call, inactivityMessages are an array of message objects. Each message must provide the following:

duration
string - The duration (in seconds) after which the message should be spoken.
pattern - ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
examples - ”60s”, “5.5s”
message
string - The message to speak.
examples - “Are you still there?”, “If there’s nothing else, I will end the call now.”
endBehavior
string - The behavior to exhibit when the message is finished being spoken. Must be one of the enumerated values.
enum
  • END_BEHAVIOR_UNSPECIFIED - Default. The system will continue to wait for user input.
  • END_BEHAVIOR_HANG_UP_SOFT - Will end the call unless the user interacts while the agent is delivering the message.
  • END_BEHAVIOR_HANG_UP_STRICT - Will end the call after speaking the message, regardless of whether the user interrupts.
Example
{
  "systemPrompt": "You are a helpful assistant.",
  "inactivityMessages": [
    {
      "duration": "30s",
      "message": "Are you still there?"
    },
    {
      "duration": "15s",
      "message": "If there's nothing else, may I end the call?"
    },
    {
      "duration": "10s",
      "message": "Thank you for calling. Have a great day. Goodbye.",
      "endBehavior": "END_BEHAVIOR_HANG_UP_SOFT"
    }
  ]
}

Here’s what would happen based on the example above:

  1. Call starts.
  2. After 30 seconds of no user interaction, agent says “Are you still there?“.
  3. If user interacts, call continues. If no user interaction occurs for another 15 seconds, agent says “If there’s nothing else, may I end the call?“.
  4. If no user interaction occurs for another 10 seconds, agent says the provided message and the call ends unless the agent is interrupted during this final message.

initialMessages

When creating a new call or a new call stage, you can provide messages to the agent via initialMessages. By default, new calls don’t have initial messages and call stages inherit the prior stage’s messages. New calls will inherit messages if priorCallId is set.

These messages can serve the purpose of giving the agent call history or to give examples for few-shotting (e.g. if you want the agent to learn how to respond in a specific way to user input).

Message Format

initialMessages must be an array of message objects where each message contains a role and text. See “Response” under List Call Messages above for more details.

Here’s an example:

[
  {
    "role": "MESSAGE_ROLE_USER",
    "text": "My name is Steve"
  },
  {
    "role": "MESSAGE_ROLE_AGENT",
    "text": "Great to meet you, Steve! How can I help?"
  },
]

Using Mistral

When using fixie-ai/ultravox-mistral-nemo-12B:

  1. Empty System Prompt → Set systemPrompt to an empty string ("").
  2. Prompt in Initial Messages → Add system prompt instructions as the first user message in initialMessages.
  3. Proper Turns → Maintain strict user > agent > user message alternation.

Here’s an example of what the request body for creating the call might look like:

{
  "systemPrompt": "",
  "model": "fixie-ai/ultravox-mistral-nemo-12B",
  "initialMessages": [
    {
      "role": "MESSAGE_ROLE_USER",
      "text": "You are a helpful assistant."
    }
  ],
  "temperature": 0.4
}