Making Calls

Creating Calls with Agents (Recommended)

For all new projects, use agents to create calls. This approach provides consistency, reusability, and easier maintenance.

Basic Agent Call

Start a call using an existing agent and pass in any template variables:

Example: Create a New Agent Call

const startAgentCall = async (agentId) => {
  const response = await fetch(`https://api.ultravox.ai/api/agents/${agentId}/calls`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({
      templateContext: {
        customerName: "Jane Smith",
        accountType: "Premium"
      }
    })
  });
  
  return await response.json();
};

Template Context and Variables

Provide dynamic data to your agent at call creation time:

Example: Template Context Variables

{
  templateContext: {
    customerName: "John Doe",
    accountType: "enterprise",
    lastInteraction: "2025-05-15",
    accountBalance: "$1,250.00"
  }
}

Overriding Agent Settings

When starting a call with an agent, you can override specific settings from the agent’s call template. Here are the parameters you can include in the request body:

Parameter	Description	Type	Example
`templateContext`	Variables for template substitution	Object	`{ customerName: "John" }`
`initialMessages`	Conversation history to start from	Array	Previous chat context
`metadata`	Key-value pairs for tracking	Object	`{ source: "website" }`
`medium`	Communication protocol	Object	`{ twilio: {} }`.
`joinTimeout`	Time limit for user to join	String	`"60s"`
`maxDuration`	Maximum call length	String	`"1800s"`
`recordingEnabled`.	Whether to record audio	Boolean	`true` / `false`
`initialOutputMedium`	Start with voice or text	String	`"voice"` / `"text"`
`mediumRestriction`	Limit the call to voice or text	Object	`{ allowedMediums: ["MESSAGE_MEDIUM_TEXT"] }`
`firstSpeakerSettings`	Initial conversation behavior	Object	`{ agent: { text: "..." } }`
`experimentalSettings`	Experimental settings for the call	Object	Varies

Example of overriding agent settings when creating a call:

Example: Overriding Agent Settings

const response = await fetch(`https://api.ultravox.ai/api/agents/${agentId}/calls`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key'
  },
  body: JSON.stringify({
    // Template context
    templateContext: {
      customerName: "VIP Customer",
      accountType: "enterprise"
    },
    
    // Override agent settings for this specific call
    maxDuration: "900s", // 15 minutes instead of default
    recordingEnabled: false  // Disable call recording
  })
});

Text-Only and Voice-Only Calls

By default, users can speak or type and the agent can reply with voice or text. Set mediumRestriction on an agent’s call template or on an individual call to limit a call to one medium:

Example: A Text-Only Call

body: JSON.stringify({
  mediumRestriction: {
    allowedMediums: ["MESSAGE_MEDIUM_TEXT"]
  }
})

The restriction applies to both user input and agent output:

Text Only → The agent replies in text, and the call ignores any audio the client sends.
Voice Only → The agent replies with voice, and the call ignores UserTextMessages from the client. Text sent through a data connection or the REST API still reaches the agent.

A SetOutputMedium message for a medium the call doesn’t allow is ignored. Ignored messages are recorded as warning call events. The CallStarted message tells the client which mediums the call allows. If you don’t set initialOutputMedium, the call starts with voice when it’s allowed and text otherwise.

Settings That Require Voice

Creating an agent or a call returns a 400 error when the restriction conflicts with other settings:

initialOutputMedium must be one of the allowed mediums.
Telephony calls (Twilio, Telnyx, Plivo, Exotel, and SIP) must allow voice.
Calls that don’t allow voice can’t enable recording, play background audio, or send audio to a data connection.

allowedMediums must not be empty. Leave mediumRestriction unset to allow every medium. When you override an agent’s restriction for a single call, the call’s value replaces the agent’s.

Direct Call Alternative

For legacy integration, testing, or very simple use cases, you can create calls directly without agents:

const startDirectCall = async () => {
  const response = await fetch('https://api.ultravox.ai/api/calls', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({
      systemPrompt: "You are a helpful customer service agent. Be friendly and professional.",
      voice: "Jessica",
      temperature: 0.3,
      model: "ultravox-v0.7",
      joinTimeout: "30s",
      maxDuration: "3600s",
      recordingEnabled: false,
      
      firstSpeakerSettings: {
        agent: {
          text: "Hello! How can I help you today?"
        }
      },
      
      selectedTools: [
        { toolName: 'knowledgebaseLookup' },
        { toolName: 'transferToHuman' }
      ],
      
      metadata: {
        purpose: "customer_support",
        test: "true"
      }
    })
  });
  
  return await response.json();
};

Prior Call Inheritance

You can reuse the same properties (including message history) from a prior call by passing in a query param:

Example: Using Prior Call ID

const continueFromPriorCall = async (priorCallId) => {
  const response = await fetch(`https://api.ultravox.ai/api/calls?priorCallId=${priorCallId}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({
      // Only override what you need to change
      systemPrompt: "Continue the previous conversation with updated context...",
      metadata: {
        continuation: "true",
        originalCall: priorCallId
      }
    })
  });
  
  return await response.json();
};

When using priorCallId, the new call inherits all properties from the prior call unless explicitly overridden. The prior call’s message history becomes the new call’s initialMessages. If the new call sets a mediumRestriction, inherited settings that conflict with it (such as recording) are dropped instead of causing an error, and an inherited telephony medium becomes WebRTC.

Next Steps

Scaling & Concurrency

Learn how call concurrency works and how to manage it.

Webhooks

Learn how to integrate and monitor real-time events.

Test & Debug Your Calls

Learn to monitor, troubleshoot, and optimize your voice conversations

Getting Started

Agents & Calls

Telephony

Web, Apps, Websockets

Tools

Voices

Webhooks

Noise & VAD

Creating Calls with Agents (Recommended)

Basic Agent Call

Template Context and Variables

Overriding Agent Settings

Text-Only and Voice-Only Calls

Settings That Require Voice

Direct Call Alternative

Prior Call Inheritance

Next Steps

Scaling & Concurrency

Webhooks

Test & Debug Your Calls

​Creating Calls with Agents (Recommended)

​Basic Agent Call

​Template Context and Variables

​Overriding Agent Settings

​Text-Only and Voice-Only Calls

​Settings That Require Voice

​Direct Call Alternative

​Prior Call Inheritance

​Next Steps

Scaling & Concurrency

Webhooks

Test & Debug Your Calls

Creating Calls with Agents (Recommended)

Basic Agent Call

Template Context and Variables

Overriding Agent Settings

Text-Only and Voice-Only Calls

Settings That Require Voice

Direct Call Alternative

Prior Call Inheritance

Next Steps