/* ":root": {
  "--color-tan": "#fff5e1",
  "--color-gold": "#ffc371",
  "--color-orange": "#ff936f",
  "--color-hotred": "#ff5f6d",
  "--color-deepred": "rgb(221, 69, 88)",
  "--color-deepred-50": "rgba(221, 69, 88, 0.5)",
  "--color-sky": "#005e99",
  "--color-blue": "#009edc",
  "--color-bluer": "#0077be",
  "--color-bluest": "#7cc8ec",
  "--color-white": "#000000",
  "--color-offwhite": "#121212",
  "--color-grey": "#2a2a2a",
  "--color-greyy": "#3a3b3f",
  "--color-greyyy": "#ced7ea",
  "--color-batmanblack": "#fbfbfb",
  "--color-black": "#e3e8ed",
  "--color-bluehighlight-10": "rgba(94, 146, 255, 0.10)",
  "--color-bluehighlight-50": "rgba(94, 146, 255, 0.50)",
},
".dark": {
  "--color-tan": "#fff5e1",
  "--color-gold": "#ffc371",
  "--color-orange": "#ff936f",
  "--color-hotred": "#ff5f6d",
  "--color-deepred": "rgb(221, 69, 88)",
  "--color-deepred-50": "rgba(221, 69, 88, 0.5)",
  "--color-sky": "#7cc8ec",
  "--color-blue": "#009edc",
  "--color-bluer": "#0077be",
  "--color-bluest": "#005e99",
  "--color-white": "#ffffff",
  "--color-offwhite": "#e3e8ed",
  "--color-grey": "#9a9b9d",
  "--color-greyy": "#3a3b3f",
  "--color-greyyy": "#2a2a2a",
  "--color-batmanblack": "#121212",
  "--color-black": "#000000", */



/* Default link styles */
a {
  color: #005e99;  /* SKY */
  text-decoration: none;
  transition: color 0.2s ease-in-out;
}

a:hover {
  color: #7cc8ec;  /* Bluest */
}

dark a {
  color: #7cc8ec;  /* SKY */
}

.dark  a:hover {
  color: #0077be;  /* BLUER */
}

import express from 'express';
import https from 'https';
import twilio from 'twilio';
import 'dotenv/config'

const app = express();
const port = 3000;

// Configuration
const ULTRAVOX_API_KEY = process.env.ULTRAVOX_API_KEY
const ULTRAVOX_API_URL = 'https://api.ultravox.ai/api/calls';

// Ultravox configuration
const SYSTEM_PROMPT = 'Your name is Steve. You are receiving a phone call. Ask them their name and see how they are doing.';

const ULTRAVOX_CALL_CONFIG = {
    systemPrompt: SYSTEM_PROMPT,
    model: 'fixie-ai/ultravox',
    voice: 'Mark',
    temperature: 0.3,
    firstSpeaker: 'FIRST_SPEAKER_AGENT',
    medium: { "twilio": {} }
};

// Create Ultravox call and get join URL
async function createUltravoxCall() {
    const request = https.request(ULTRAVOX_API_URL, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': ULTRAVOX_API_KEY
        }
    });

    return new Promise((resolve, reject) => {
        let data = '';

        request.on('response', (response) => {
            response.on('data', chunk => data += chunk);
            response.on('end', () => resolve(JSON.parse(data)));
        });

        request.on('error', reject);
        request.write(JSON.stringify(ULTRAVOX_CALL_CONFIG));
        request.end();
    });
}

// Handle incoming calls
app.post('/incoming', async (req, res) => {
    try {
        console.log('Incoming call received');
        const response = await createUltravoxCall();
        const twiml = new twilio.twiml.VoiceResponse();
        const connect = twiml.connect();
        connect.stream({
            url: response.joinUrl,
            name: 'ultravox'
        });

        const twimlString = twiml.toString();
        res.type('text/xml');
        res.send(twimlString);

    } catch (error) {
        console.error('Error handling incoming call:', error);
        const twiml = new twilio.twiml.VoiceResponse();
        twiml.say('Sorry, there was an error connecting your call.');
        res.type('text/xml');
        res.send(twiml.toString());
    }
});

// Start server
app.listen(port, () => {
    console.log(`Server running on port ${port}`);
});

import twilio from 'twilio';
import https from 'https';

// Twilio configuration
const TWILIO_ACCOUNT_SID = 'your_twilio_account_sid_here';
const TWILIO_AUTH_TOKEN = 'your_twilio_auth_token_here';
const TWILIO_PHONE_NUMBER = 'your_twilio_phone_number_here';
const DESTINATION_PHONE_NUMBER = 'the_destination_phone_number_here';

// Ultravox configuration
const ULTRAVOX_API_KEY = 'your_ultravox_api_key_here';
const SYSTEM_PROMPT = 'Your name is Steve and you are calling a person on the phone. Ask them their name and see how they are doing.';

const ULTRAVOX_CALL_CONFIG = {
    systemPrompt: SYSTEM_PROMPT,
    model: 'fixie-ai/ultravox',
    voice: 'Mark',
    temperature: 0.3,
    firstSpeaker: 'FIRST_SPEAKER_USER',
    medium: { "twilio": {} }
};

const ULTRAVOX_API_URL = 'https://api.ultravox.ai/api/calls';

async function createUltravoxCall() {
    const request = https.request(ULTRAVOX_API_URL, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': ULTRAVOX_API_KEY
        }
    });

    return new Promise((resolve, reject) => {
        let data = '';

        request.on('response', (response) => {
            response.on('data', chunk => data += chunk);
            response.on('end', () => resolve(JSON.parse(data)));
        });

        request.on('error', reject);
        request.write(JSON.stringify(ULTRAVOX_CALL_CONFIG));
        request.end();
    });
}

async function main() {
    try {
        console.log('Creating Ultravox call...');
        const { joinUrl } = await createUltravoxCall();
        console.log('Got joinUrl:', joinUrl);

        const client = twilio(TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN);
        const call = await client.calls.create({
            twiml: `<Response><Connect><Stream url="${joinUrl}"/></Connect></Response>`,
            to: DESTINATION_PHONE_NUMBER,
            from: TWILIO_PHONE_NUMBER
        });

        console.log('Call initiated:', call.sid);
    } catch (error) {
        console.error('Error:', error.message);
    }
}

main();

import express from 'express';
import 'dotenv/config'

const port = 3000;
const app = express();

app.use(express.json());
app.use(express.urlencoded({ extended: true })); 

// Import our routes and mount them
import { router as twilioRoutes } from './routes/twilio.js';
import { router as makeRoutes } from './routes/make.js';
import { router as calRoutes } from './routes/cal.js';
import { router as ragRoutes } from './routes/rag.js';

app.use('/twilio/', twilioRoutes);
app.use('/make/', makeRoutes);
app.use('/cal/', calRoutes);
app.use('/rag/', ragRoutes);

// Start server
app.listen(port, () => {
    console.log(`Server running on port ${port}`);
});

// Original version courtesy of John George
// https://github.com/askjohngeorge/ai-dialer/blob/13a0c206a69ddafd0a3a4db06a9c483d20b16cc8/src/lib/cal.ts#L4

import express from 'express';
import 'dotenv/config';

const router = express.Router();

// Environment variable validation
if (!process.env.CALCOM_API_KEY) throw new Error('CALCOM_API_KEY is required');
if (!process.env.CALCOM_EVENT_TYPE_ID) throw new Error('CALCOM_EVENT_TYPE_ID is required');

const BASE_URL = 'https://api.cal.com/v2';

const config = {
  apiKey: process.env.CALCOM_API_KEY,
  eventTypeId: parseInt(process.env.CALCOM_EVENT_TYPE_ID, 10),
};

async function getAvailability(days = 5) {
  try {
    const startTime = new Date().toISOString();
    const endTime = new Date(Date.now() + days * 24 * 60 * 60 * 1000).toISOString();
    
    const params = new URLSearchParams({
      startTime,
      endTime,
      eventTypeId: config.eventTypeId.toString(),
    });
    
    const url = `${BASE_URL}/slots/available?${params}`;

    console.log('Fetching availability from:', url);
    
    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${config.apiKey}`,
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) {
      const errorText = await response.text();
      console.error('Failed to fetch availability:', {
        status: response.status,
        statusText: response.statusText,
        error: errorText,
      });
      throw new Error(`Failed to fetch availability: ${response.statusText}`);
    }

    const data = await response.json();
    console.log('Availability response:', JSON.stringify(data, null, 2));
    
    // Basic validation of response structure
    if (data.status !== 'success' || !data.data?.slots) {
      throw new Error('Invalid response format');
    }
    
    // Convert the date-grouped slots into a flat array
    const slots = Object.values(data.data.slots).flat();
    
    return {
      success: true,
      availability: { slots }
    };
  } catch (error) {
    console.error('Failed to fetch availability:', error);
    return {
      success: false,
      error: 'Failed to fetch availability'
    };
  }
}

// Handle requests for looking up spots on the calendar
router.post('/checkAvailability', async (req, res) => {

  console.log('Got a request for checkAvailability');
  const availableSlots = await getAvailability();
  res.json(availableSlots.data)
});

export { router };

import express from 'express';
import 'dotenv/config';
import { getCallTranscript } from '../ultravox-utils.js';

const router = express.Router();

router.post('/webhook', async (req, res) => {
  console.log('Incoming UV Webhook!');

  try {
    const data = req.body;

    // Call ended event...let's get the transcript and send to Make
    if (data.event === "call.ended") {
      // Use CallID and use UV REST API to get transcript
      const transcript = await getCallTranscript(data.call.callId);
      const postBody = {
        "callId": data.call.callId,
        "transcript": transcript
      };

      // Send the transcript to Make.com incoming webhook
      const makeResponse = await fetch(process.env.MAKE_INCOMING_WH, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(postBody)
      });

      console.log(`response: ${makeResponse.status}`);
    }
    
    res.status(200).json({ received: true });
  } catch (error) {
      console.error('Error processing webhook:', error);
      res.status(500).json({ error: 'Failed to process webhook' });
  }
});

export { router };


import express from 'express';
import 'dotenv/config';
import { corpusLookup } from '../ultravox-utils.js';

const router = express.Router();

// Knowledge Base lookup
router.post('/kblookup', async (req, res) => {
  try {
      console.log('KB lookup request received');
      const { ...corpusQueryData } = req.body;

      const results = await corpusLookup(corpusQueryData.query);
      res.status(200).json({ results });

  } catch (error) {
      console.error('Error handling KB lookup:', error);
      res.status(500);
  }
});

export { router };

import express from 'express';
import twilio from 'twilio';
import 'dotenv/config';
import { createUltravoxCall } from '../ultravox-utils.js';
import { ULTRAVOX_CALL_CONFIG } from '../ultravox-config.js';

const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const destinationNumber = process.env.DESTINATION_PHONE_NUMBER;
const router = express.Router();

// Hack: Dictionary to store Twilio CallSid and Ultravox Call ID mapping
// TODO replace this with something more durable
const activeCalls = new Map();

async function transferActiveCall(ultravoxCallId) {
    try {
        const callData = activeCalls.get(ultravoxCallId);
        if (!callData || !callData.twilioCallSid) {
            throw new Error('Call not found or invalid CallSid');
        }

        // First create a new TwiML to handle the transfer
        const twiml = new twilio.twiml.VoiceResponse();
        twiml.dial().number(destinationNumber);

        // Update the active call with the new TwiML
        const updatedCall = await client.calls(callData.twilioCallSid)
            .update({
                twiml: twiml.toString()
            });

        return {
            status: 'success',
            message: 'Call transfer initiated',
            callDetails: updatedCall
        };

    } catch (error) {
        console.error('Error transferring call:', error);
        throw {
            status: 'error',
            message: 'Failed to transfer call',
            error: error.message
        };
    }
}

// Handle incoming calls from Twilio
router.post('/incoming', async (req, res) => {
    try {
        console.log('Incoming call received');
        const twilioCallSid = req.body.CallSid;
        console.log('Twilio CallSid:', twilioCallSid);

        // Create the Ultravox call
        const response = await createUltravoxCall(ULTRAVOX_CALL_CONFIG);

        activeCalls.set(response.callId, {
            twilioCallSid: twilioCallSid
        });

        const twiml = new twilio.twiml.VoiceResponse();
        const connect = twiml.connect();
        connect.stream({
            url: response.joinUrl,
            name: 'ultravox'
        });

        const twimlString = twiml.toString();
        res.type('text/xml');
        res.send(twimlString);

    } catch (error) {
        console.error('Error handling incoming call:', error);
        const twiml = new twilio.twiml.VoiceResponse();
        twiml.say('Sorry, there was an error connecting your call.');
        res.type('text/xml');
        res.send(twiml.toString());
    }
});

// Handle transfer of calls to another number
router.post('/transferCall', async (req, res) => {
    const { callId } = req.body;
    console.log(`Request to transfer call with callId: ${callId}`);

    try {
        const result = await transferActiveCall(callId);
        res.json(result);
    } catch (error) {
        res.status(500).json(error);
    }
});

router.get('/active-calls', (req, res) => {
    const calls = Array.from(activeCalls.entries()).map(([ultravoxCallId, data]) => ({
        ultravoxCallId,
        ...data
    }));
    res.json(calls);
});

export { router };


import 'dotenv/config';
import https from 'node:https';

// Configuration
const ULTRAVOX_API_KEY = process.env.ULTRAVOX_API_KEY;
const ULTRAVOX_API_URL = 'https://api.ultravox.ai/api';
const FIXIE_CORPUS_ID = process.env.FIXIE_CORPUS_ID;
const FIXIE_API_KEY = process.env.FIXIE_API_KEY;

// Create Ultravox call and get join URL
export async function createUltravoxCall(callConfig) {
    const request = https.request(`${ULTRAVOX_API_URL}/calls`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': ULTRAVOX_API_KEY
        }
    });

    return new Promise((resolve, reject) => {
        let data = '';

        request.on('response', (response) => {
            response.on('data', chunk => data += chunk);
            response.on('end', () => resolve(JSON.parse(data)));
        });

        request.on('error', reject);
        request.write(JSON.stringify(callConfig));
        request.end();
    });
}

export async function getCallTranscript(callId) {
  let allMessages = [];
  let nextCursor = null;

  try {
    // Keep fetching until we have all messages
    do {
      const url = `${ULTRAVOX_API_URL}/calls/${callId}/messages${nextCursor ? `?cursor=${nextCursor}` : ''}`;
      
      const response = await fetch(url, {
        headers: {
          'X-API-Key': ULTRAVOX_API_KEY,
          'Accept': 'application/json'
        }
      });

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }

      const data = await response.json();

      // Add the current page of results to our collection
      allMessages = allMessages.concat(data.results);

      // Update the cursor for the next iteration
      nextCursor = data.next ? new URL(data.next).searchParams.get('cursor') : null;

    } while (nextCursor);

    return allMessages;

  } catch (error) {
    console.error('Error fetching Ultravox messages:', error.message);
    throw error;
  }
}

export async function corpusLookup(query) {
  const corpusUrl = `https://api.fixie.ai/api/v1/corpora/${FIXIE_CORPUS_ID}:query`;
  const fixieAPIHeaders = {
    "Authorization": `Bearer ${FIXIE_API_KEY}`,
    "Content-Type": 'application/json'
  };
  const postBody = {
    corpus_id: FIXIE_CORPUS_ID,
    query: query,
    max_chunks: 5 // hardcoding
  }

  const response = await fetch(corpusUrl, {
    method: 'POST',
    headers: fixieAPIHeaders,
    body: JSON.stringify({ ...postBody }),
  });

  console.log('Fixie API response status:', response.status);

  if (!response.ok) {
    const errorText = await response.text();
    console.error('Fixie API error:', errorText);
    throw new Error(`Fixie API error: ${response.status}, ${errorText}`);
  }

  const data = await response.json();
  return data;
}


Debugging & Troubleshooting

X-API-Key

Ultradox

Ultravox Realtime

A guide to prompting for great voice AI experiences

Prompting Quickstart

Build and Deploy an Agent to the Browser in 5 Minutes

Web Quickstart

Creating an API Key

Give your agents additional capabilities while maintaining a natural conversation flow.

Using Tools

Give you agent access to product documents, KBs, and more.

Adding Knowledge (RAG)

Ultravox Client SDK for building user-facing experiences.

SDKs

Use Ultravox to make and receive calls using WebRTC, via Telnyx, Twilio, Plivo, or jambonz.

Telephony

Voice Cloning

Design and deploy reusable agents with pre-configured properties for consistent voice experiences.

Creating Agents

Multilingual Agents

Create incoming & outgoing SIP calls with Ultravox agents.

SIP Guide (PREVIEW)

A guide to steering your agent toward good experiences

Guiding Agents

Create dynamic, multi-stage conversations.

Call Stages

Integrate with your server via direct WebSocket connections.

WebSocket Integration

Protocol documentation for messages exchanged between client and server during Ultravox calls.

Data Messages

Receive real-time notifications from Ultravox.

Webhooks

Ultravox REST API Overview

Returns account details for a single account

Get Account

Returns aggregated and per-day call usage data

Get Call Usage

Allows adding or updating TTS provider API keys to an account, enabling ExternalVoices

Set TTS API keys

Returns the TTS provider API keys associated with the active account

Get Account TTS API Keys

List Agents

Creates a new agent using the specified name and call template

Create Agent

Get Agent

Update Agent

Delete Agent

Lists all calls that were created using the specified agent

List Agent Calls

Creates a new call using the the specified agent

Create Agent Call

Calls Overview

List Calls

Get Call

Creates a new call using the specified system prompt and other properties

Create Call

Delete Call

Returns all messages generated during the given call

List Call Messages

Returns all tools that were available at any point during the call

List Call Tools

Returns a link to the recording of the call

Get Call Recording

Lists all stages that occurred during the specified call

List Call Stages

Retrieves details for a specific stage of a call

Get Call Stage

Returns all messages that were exchanged during a specific stage of a call

List Call Stage Messages

Returns all tools that were available during a specific stage of a call

List Call Stage Tools

Get Call Stage Message Audio

List Deleted Calls

Gets details for the specified deleted call

Get Deleted Call

Understanding Retrieval Augmented Generation in Ultravox

Corpus Service (RAG) Overview

List Corpora

Creates a new corpus using the specified name and description

Create Corpus

Get Corpus

Update Corpus

Delete Corpus

Queries the specified corpus and returns the specified number of results

Query Corpus

Lists all sources that are part of the specified corpus

List Corpus Sources

Creates a new source for the specified corpus

Create Corpus Source

Retrieves details for the specified source

Get Corpus Source

Update Corpus Source

Delete Corpus Source

Returns details for all documents contained in the source

List Corpus Source Documents

Retrieves details for the specified source document

Get Corpus Source Document

Creates a new URL and document ID to use for uploading a static file

Create Corpus File Upload

List Tools

Get Tool

Create Tool

Update Tool

Delete Tool

Gets all calls that have used the specified tool

Get Tool History

List Voices

Get Voice

Create (Clone) Voice

Delete Voice

Retrieves all webhooks configured on an account

List Webhooks

Gets details for the specified webhook configuration

Get Webhook

Creates a new webhook configuration for an account

Create Webhook

Replaces the specified webhook configuration

Replace Webhook

Updates the specified webhook configuration

Update Webhook

Deletes the specified webhook configuration

Delete Webhook

Base Tool Definition

Ultravox Data Message Protocol

Retrieves the list of all available models that can be used for inference

List Models

Gets the OpenAPI schema for the Ultravox REST API

Get OpenAPI Schema

Ultravox Client SDK

Stay informed about Ultravox platform announcements.

News & Updates

Track upcoming breaking changes, migration timelines, and deprecation notices for the Ultravox platform.

Deprecation Guide

API Reference

SDK Reference

Integrations

Changelog

Dashboard

Community

Key concepts to understand before building a voice AI agent.

It's All Prompting

There is no ASR

Tools are Just Functions

The Start Call 2-Step

Ultravox Realtime is Fast and Cheap

Connect outoing Twilio calls to an Ultravox agent in 5 minutes or less.

Outgoing Phone Calls

Connect incoming calls to an AI agent in 6 minutes.

Incoming Phone Calls

Learn how to implement customer service escalation in Ultravox using call stages to handle customer complaints by transferring them to a manager.

Tutorial: Customer Escalation with Call Stages

Learn how to implement client-side tools in Ultravox to create dynamic, interactive user interfaces.

Getting Started

Essentials

Advanced Guides + Tutorials

Debugging & Troubleshooting