-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #26 from fixie-ai/ben-add-phonecalls
Add phone calls & available models
- Loading branch information
Showing
5 changed files
with
181 additions
and
19 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| --- | ||
| title: "Available Models" | ||
| --- | ||
|
|
||
| The Ultravox API currently provides the following models. | ||
|
|
||
| <table class="w-full"> | ||
| <tr class="w-full"> | ||
| <th class="w-4/12">Model</th> | ||
| <th class="w-8/12">Description</th> | ||
| </tr> | ||
| <tr> | ||
| <td class="font-mono">fixie-ai/ultravox</td> | ||
| <td>This is an alias that points to `ultravox-70B`. The default if no model is specified when creating a call with the API.</td> | ||
| </tr> | ||
| <tr> | ||
| <td class="font-mono">fixie-ai/ultravox-70B</td> | ||
| <td>70B variant of Ultravox. Supports tools.</td> | ||
| </tr> | ||
| <tr> | ||
| <td class="font-mono">fixie-ai/ultravox-8B</td> | ||
| <td>8B variant of Ultravox. Not recommended for most use cases. Tools are unlikely to work.</td> | ||
| </tr> | ||
| </table> | ||
|
|
||
| ## Using Models | ||
| Each model can be used when [creating a call](./api/calls/#create-call) via the API. For example: | ||
|
|
||
| ```javascript | ||
| // Example request body to create an Ultravox call | ||
| { | ||
| "systemPrompt": "You are a helpful assistant...", | ||
| "model": "fixie-ai/ultravox-70B" | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| --- | ||
| title: "Phone Calls" | ||
| description: Use Ultravox API to make and receive calls from regular phones via Twilio. | ||
| --- | ||
|
|
||
| import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; | ||
|
|
||
| ## Overview | ||
|
|
||
| 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. | ||
|
|
||
| :::note[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 | ||
| :::tip[Prerequisites] | ||
| Make sure you have: | ||
| 1. An active Twilio account | ||
| 1. 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](./api/calls/#create-call) command worth special attention: | ||
|
|
||
| <table class="w-full"> | ||
| <tr class="w-full"> | ||
| <th class="w-1/12"></th> | ||
| <th class="w-1/12"></th> | ||
| <th class="w-10/12"></th> | ||
| </tr> | ||
| <tr> | ||
| <td class="font-mono">medium</td> | ||
| <td>object</td> | ||
| <td>Tells Ultravox which protocol to use. <br />For Twilio, must be set to `{"twilio": {}}` and sets the call to use Twilio [Media Streams](https://www.twilio.com/docs/voice/media-streams). Defaults to `{"webRtc": {}}` which sets the protocol to WebRTC.</td> | ||
| </tr> | ||
| <tr> | ||
| <td class="font-mono">initiator</td> | ||
| <td>string</td> | ||
| <td>Tells Ultravox who started the call. For outgoing calls, typically set to `"INITIATOR_AGENT"`. Default is `"INITIATOR_USER"`.</td> | ||
| </tr> | ||
| </table> | ||
|
|
||
| Adding these to the request body when creating the call would look like this: | ||
|
|
||
| ```javascript | ||
| { | ||
| "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: | ||
| <Steps> | ||
| 1. **Create an Ultravox Call** → Create a new call (see [above](#creating-a-phone-call-with-twilio)), and get a `joinUrl`. | ||
|
|
||
| 1. **Initiate Twilio Phone call** → Use the `joinUrl` with a Twilio [`<Stream>`](https://www.twilio.com/docs/voice/twiml/stream). | ||
|
|
||
| ```javascript | ||
| // 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 | ||
| }); | ||
| ``` | ||
| </Steps> | ||
|
|
||
| See the [twilio-outgoing-call](https://github.com/fixie-ai/ultradox/tree/main/examples/twilio-outgoing-call) example for more. | ||
|
|
||
| This example shows one of the many options Twilio provides for making outgoing calls. Consult the [Twilio docs](https://www.twilio.com/docs) for more details. | ||
|
|
||
| ## Incoming Calls | ||
| Incoming calls require essentially the same two steps as outgoing calls: | ||
|
|
||
| <Steps> | ||
| 1. **Create an Ultravox Call** → Create a new call (see [above](#creating-a-phone-call-with-twilio)), and get a `joinUrl`. *Note: for incoming calls you will want to keep `initiator` set to the default ("user").* | ||
|
|
||
| 1. **Receive Inbound Twilio Phone call** → Use the `joinUrl` with a Twilio [`<Stream>`](https://www.twilio.com/docs/voice/twiml/stream). | ||
|
|
||
| ```xml | ||
| <!-- Example using a TwiML Bin --> | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <Response> | ||
| <Connect> | ||
| <Stream url="your_ultravox_join_url" /> | ||
| </Connect> | ||
| </Response> | ||
|
|
||
| ``` | ||
| </Steps> | ||
|
|
||
| The above shows how to create a TwiML Bin and use that for handling the inbound call. Consult the [Twilio docs](https://www.twilio.com/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](https://www.twilio.com/docs). |