Ultravox + Telephony

The Ultravox API allows you to create AI-powered voice applications that can interact with regular phone numbers. This enables Ultravox AI agents to make outgoing calls and receive incoming calls from traditional phone networks.

Twilio Support

We currently integrate with Twilio. Please let us know if there’s another integration you’d like to see.

This guide will walk you through the process of setting up and using the Ultravox API with Twilio for both outgoing and incoming phone calls.

Creating a Phone Call with Twilio

Prerequisites

Make sure you have:

1. An active Twilio account
2. A phone number purchased from Twilio

Creating an Ultravox call that works with Twilio is just like creating a WebRTC call, but there are two parameters to the Create Call command worth special attention:

medium	object	Tells Ultravox which protocol to use. For Twilio, must be set to {"twilio": {}} and sets the call to use Twilio Media Streams. Defaults to {"webRtc": {}} which sets the protocol to WebRTC.
initiator	string	Tells Ultravox who started the call. For outgoing calls, typically set to "INITIATOR_AGENT". Default is "INITIATOR_USER".

Adding these to the request body when creating the call would look like this:

{
  "systemPrompt": "You are a helpful assistant...",
  ...
  "medium": {
    "twilio": {}
  },
  "initiator": "INITIATOR_AGENT"
}

Ultravox will return a joinUrl that can then be used with Twilio for outgoing or incoming calls.

Outgoing Calls

It only takes two steps to make an outgoing call to regular phone numbers through Twilio:

1. Create an Ultravox Call → Create a new call (see above), and get a joinUrl.

2. Initiate Twilio Phone call → Use the joinUrl with a Twilio <Stream>.

   // Example using the twilio node library
   const call = await client.calls.create({
       twiml: `<Response>
                   <Connect>
                       <Stream url="${joinUrl}"/>
                   </Connect>
               </Response>`,
       to: phoneNumber, // the number you are calling
       from: twilioPhoneNumber // your twilio number
   });

See the twilio-outgoing-call example for more.

This example shows one of the many options Twilio provides for making outgoing calls. Consult the Twilio docs for more details.

Incoming Calls

Incoming calls require essentially the same two steps as outgoing calls:

1. Create an Ultravox Call → Create a new call (see above), and get a joinUrl. Note: for incoming calls you will want to keep initiator set to the default (“user”).

2. Receive Inbound Twilio Phone call → Use the joinUrl with a Twilio <Stream>.

   <!-- Example using a TwiML Bin -->
   <?xml version="1.0" encoding="UTF-8"?>
   <Response>
       <Connect>
           <Stream url="your_ultravox_join_url" />
       </Connect>
   </Response>

The above shows how to create a TwiML Bin and use that for handling the inbound call. Consult the Twilio docs for more on all the options Twilio provides for handling phone calls.

Conclusion

By integrating the Ultravox API with Twilio, you can create powerful AI-driven voice applications that interact with regular phone networks. This opens up a wide range of possibilities for customer service, automated outreach, and other voice-based AI applications.

For more information on Twilio, refer to the Twilio documentation.