Ultravox Realtime

https://docs.ultravox.ai
Admin
Ultravox Realtime is a fully hosted platform for creating real-time, low-latency voice AI...
Tokens:958,308
Snippets:2,830
Trust Score:7.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Go example for GET /api/accounts/me/usage/calls

Source: https://docs.ultravox.ai/api-reference/accounts/accounts-me-usage-calls-get

Uses net/http to send a GET request with the X-API-Key header and prints the response body.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/accounts/me/usage/calls?timeOfDayEnd=23:59:59.999999&timeOfDayStart=00:00:00"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Go example to get agent details

Source: https://docs.ultravox.ai/api-reference/agents/agents-get

Go example using net/http to GET agent details. Replace {agent_id} and provide your API key.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/agents/{agent_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Ruby example for GET /api/accounts/me/usage/calls

Source: https://docs.ultravox.ai/api-reference/accounts/accounts-me-usage-calls-get

Uses Net::HTTP to send a GET request with the X-API-Key header and prints the response body.

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.ultravox.ai/api/accounts/me/usage/calls?timeOfDayEnd=23:59:59.999999&timeOfDayStart=00:00:00")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Java Unirest example to get agent details

Source: https://docs.ultravox.ai/api-reference/agents/agents-get

Java example using Unirest to GET agent details. Requires the Unirest library.

```java
HttpResponse<String> response = Unirest.get("https://api.ultravox.ai/api/agents/{agent_id}")
  .header("X-API-Key", "<api-key>")
  .asString();
```

--------------------------------

### Go: Create SIP registration with net/http

Source: https://docs.ultravox.ai/api-reference/sip/sip-registrations-create

Go example using net/http to create a SIP registration.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/sip/registrations"

	payload := strings.NewReader("{\n  \"username\": \"<string>\",\n  \"password\": \"<string>\",\n  \"proxy\": \"<string>\",\n  \"outboundProxy\": \"<string>\",\n  \"authUser\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Ruby example to get agent details

Source: https://docs.ultravox.ai/api-reference/agents/agents-get

Ruby example using net/http to GET agent details. Replace {agent_id} and provide your API key.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.ultravox.ai/api/agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Complete HTML file for Ultravox web quickstart

Source: https://docs.ultravox.ai/gettingstarted/quickstart/web-app

Save this code as index.html and open it in a browser. It provides a UI to enter an Ultravox API key and system prompt, with buttons to start and end a call. The script imports UltravoxSession from esm.sh and includes a warning that this is for development only, not production.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Ultravox Web Quickstart</title>
  <script src="https://cdn.tailwindcss.com"></script>
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
</head>
<body class="bg-gray-100 min-h-screen py-8">
  <div class="max-w-4xl mx-auto px-4">
    <div class="bg-white rounded-lg shadow-lg p-6">
      <!-- WARNING: DO NOT USE IN PRODUCTION -->
      <div class="bg-yellow-50 border-l-4 border-yellow-400 p-4 mb-6">
        <div class="flex">
          <div class="flex-shrink-0 fas fa-exclamation-triangle text-yellow-400"></div>
          <div class="ml-3">
            <h3 class="text-sm text-yellow-800">DEVELOPMENT ONLY - DO NOT USE IN PRODUCTION</h3>
            <p class="mt-1 text-sm text-yellow-700">This interface exposes API keys in client-side code and uses unsafe headers to bypass CORS.</p>
            <p class="mt-1 text-sm text-yellow-700">For a robust example, see the <a href="https://github.com/fixie-ai/ultravox-examples/tree/main/web/nextjs-ts">nextjs-ts</a> example.</p>
          </div>
        </div>
      </div>
      <form class="space-y-6">
        <div class="bg-gray-50 rounded-lg p-4">
          <h3 class="text-sm text-gray-900 mb-2">Call Status</h3>
          <div id="callStatus" class="text-sm text-gray-600">Ready</div>
        </div>
        <div>
          <label for="apiKey" class="block text-sm text-gray-700 mb-2">Ultravox API Key:</label>
          <input type="password" id="apiKey" 
            class="w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
            placeholder="Enter your Ultravox API key">
          <p class="mt-1 text-sm text-gray-500">Your API key will be used to create the call. Keep this secure!</p>
        </div>
        <div>
          <label for="systemPrompt" class="block text-sm text-gray-700 mb-2">System Prompt:</label>
          <textarea id="systemPrompt" rows="3" 
            class="w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
            placeholder="Enter system prompt for the AI assistant">You are a helpful assistant.</textarea>
          <p class="mt-1 text-sm text-gray-500">This prompt will define how the AI assistant behaves during the call.</p>
        </div>
        <div class="flex space-x-3">
          <button type="button" id="startCall"
            class="inline-flex items-center px-4 py-2 border border-transparent text-sm rounded-md shadow-sm text-white bg-green-600 hover:bg-green-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-green-500 transition-colors">
            Start Call
          </button>
          <button type="button" id="endCall"
            class="inline-flex items-center px-4 py-2 border border-transparent text-sm rounded-md shadow-sm text-white bg-red-600 hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-red-500 transition-colors">
            End Call
          </button>
        </div>
      </form>
    </div>
  </div>
  <script type="module">
    import { UltravoxSession } from 'https://esm.sh/ultravox-client@0.3.6';
    
    let uvSession = new UltravoxSession();
    
    function appendUpdate(target, message) {
        const updateTarget = document.getElementById(target);
        if(target === 'callTranscript') {
            let transcriptText = '';
            message.map((transcript, index) => (
                transcriptText += '<div class="p-2 bg-gray-50 rounded border-l-4 border-blue-400"><span class="font-semibold text-gray-800">' + transcript.speaker + ':</span> <span class="text-gray-700">' + transcript.text + '</span></div>'
            ));
            updateTarget.innerHTML = transcriptText;
            updateTarget.scrollTop = updateTarget.scrollHeight;
        } else {
            updateTarget.innerHTML = message;
        }
    }
    
    // ⚠️ WARNING: DO NOT USE IN PRODUCTION! ⚠️
    // This function makes API calls directly from the client with API keys exposed
    // API keys should never be handled in client-side code in production
    // In production, API calls should be made from a secure server
  </script>
</body>
</html>
```

--------------------------------

### Go example using net/http

Source: https://docs.ultravox.ai/api-reference/calls/calls-send-data-message-post

Go example using the standard net/http library to POST a data message. Builds a request with the X-API-Key and Content-Type headers, sends it, and prints the response body.

```Go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/calls/{call_id}/send_data_message"

	payload := strings.NewReader("{\n  \"type\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

--------------------------------

### PHP cURL example to get agent details

Source: https://docs.ultravox.ai/api-reference/agents/agents-get

PHP example using cURL to GET agent details. Configure the URL and API key as needed.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ultravox.ai/api/agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Start development server with pnpm run dev

Source: https://docs.ultravox.ai/tutorials/callstages

Starts the local development server, which is required before setting up ngrok.

```bash
pnpm run dev

```

--------------------------------

### JavaScript fetch example to get agent details

Source: https://docs.ultravox.ai/api-reference/agents/agents-get

JavaScript example using fetch to GET agent details. Replace {agent_id} and provide your API key.

```javascript
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.ultravox.ai/api/agents/{agent_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Go example for listing call events

Source: https://docs.ultravox.ai/api-reference/calls/calls-events-list

Uses net/http to send a GET request with an API key header and prints the response body.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/calls/{call_id}/events?minimum_severity=info"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Python requests example to get agent details

Source: https://docs.ultravox.ai/api-reference/agents/agents-get

Python example using the requests library to GET agent details. Requires the requests library and an API key.

```python
import requests

url = "https://api.ultravox.ai/api/agents/{agent_id}"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### JavaScript: Create SIP registration with fetch

Source: https://docs.ultravox.ai/api-reference/sip/sip-registrations-create

JavaScript example using `fetch` to create a SIP registration.

```javascript
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    username: '<string>',
    password: '<string>',
    proxy: '<string>',
    outboundProxy: '<string>',
    authUser: '<string>'
  })
};

fetch('https://api.ultravox.ai/api/sip/registrations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Get Scheduled Batch Response Example

Source: https://docs.ultravox.ai/telephony/outbound-call-scheduler

Example JSON response from the Get Scheduled Batch endpoint, showing batch status fields such as batchId, totalCount, completedCount, windowStart, windowEnd, paused, and endedAt.

```json
{
  "batchId": "uuid",
  "totalCount": 1000,
  "completedCount": 750,
  "windowStart": "2024-01-15T09:00:00Z",
  "windowEnd": "2024-01-15T17:00:00Z",
  "paused": false,
  "endedAt": null
}
```

--------------------------------

### Go example

Source: https://docs.ultravox.ai/api-reference/corpora/corpora-uploads-post

Uses the net/http package to send a POST request with the JSON payload. Prints the response body.

```Go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/corpora/{corpus_id}/uploads"

	payload := strings.NewReader("{\n  \"mimeType\": \"<string>\",\n  \"fileName\": \"\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Python: Create SIP registration with requests

Source: https://docs.ultravox.ai/api-reference/sip/sip-registrations-create

Python example using the `requests` library to POST to the SIP registrations endpoint.

```python
import requests

url = "https://api.ultravox.ai/api/sip/registrations"

payload = {
    "username": "<string>",
    "password": "<string>",
    "proxy": "<string>",
    "outboundProxy": "<string>",
    "authUser": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

--------------------------------

### Java Unirest example for GET /api/accounts/me/usage/calls

Source: https://docs.ultravox.ai/api-reference/accounts/accounts-me-usage-calls-get

Uses Unirest to send a GET request with the X-API-Key header and returns the response as a string.

```Java
HttpResponse<String> response = Unirest.get("https://api.ultravox.ai/api/accounts/me/usage/calls?timeOfDayEnd=23:59:59.999999&timeOfDayStart=00:00:00")
  .header("X-API-Key", "<api-key>")
  .asString();
```

--------------------------------

### Go: List call tools

Source: https://docs.ultravox.ai/api-reference/calls/calls-tools-list

Use this Go example to list tools for a call. Replace {call_id} and <api-key> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/calls/{call_id}/tools"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### JavaScript fetch example for GET /api/accounts/me/usage/calls

Source: https://docs.ultravox.ai/api-reference/accounts/accounts-me-usage-calls-get

Uses fetch to make a GET request with the X-API-Key header and logs the JSON response.

```JavaScript
const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.ultravox.ai/api/accounts/me/usage/calls?timeOfDayEnd=23:59:59.999999&timeOfDayStart=00:00:00', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Response example for listing tools

Source: https://docs.ultravox.ai/api-reference/tools/tools-list

Example JSON response from the GET /api/tools endpoint, showing the structure of a tool object and pagination fields.

```json
{
  "results": [
    {
      "toolId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "created": "2023-11-07T05:31:56Z",
      "definition": {
        "modelToolName": "<string>",
        "description": "<string>",
        "dynamicParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "schema": {},
            "required": true
          }
        ],
        "staticParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "value": "<unknown>"
          }
        ],
        "automaticParameters": [
          {
            "name": "<string>",
            "location": "PARAMETER_LOCATION_UNSPECIFIED",
            "knownValue": "KNOWN_PARAM_UNSPECIFIED"
          }
        ],
        "requirements": {
          "httpSecurityOptions": {
            "options": [
              {
                "requirements": {},
                "ultravoxCallTokenRequirement": {
                  "scopes": [
                    "<string>"
                  ]
                }
              }
            ]
          },
          "requiredParameterOverrides": [
            "<string>"
          ]
        },
        "timeout": "<string>",
        "precomputable": true,
        "http": {
          "baseUrlPattern": "<string>",
          "httpMethod": "<string>"
        },
        "client": {},
        "dataConnection": {},
        "defaultReaction": "AGENT_REACTION_UNSPECIFIED",
        "staticResponse": {
          "responseText": "<string>"
        }
      },
      "ownership": "public"
    }
  ],
  "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D\"",
  "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  "total": 123
}
```

--------------------------------

### Go example to get call recording

Source: https://docs.ultravox.ai/api-reference/calls/calls-recording-get

Uses the net/http package to fetch the call recording. Requires an API key in the X-API-Key header. The response is an audio file (audio/wav).

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/calls/{call_id}/recording"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Go example for getting a call throttle

Source: https://docs.ultravox.ai/api-reference/call-throttles/call-throttles-get

Uses net/http to GET a call throttle. Requires an X-API-Key header. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ultravox.ai/api/call_throttles/{throttle_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Provide Step-by-Step Instructions

Source: https://docs.ultravox.ai/gettingstarted/prompting

Shows a pattern for giving step-by-step instructions in customer support. The model calls a tool to get steps, then guides the user one step at a time, waiting for confirmation before proceeding.

```text
Example: User asks for help changing their password
- You will call the "searchArticle" tool
- Response from tool: {"content": "1. Click "Forgot Password" on the login screen 2. Enter your email address and click "Submit" 3. Check your email for the reset link 4. Click the link and enter your new password 5. Log in with your new password"}
- You will then use this information and proceed step-by-step with the user like this:
  * agent: "There are a few steps we need to go through."
  * agent: "The first step is Click on Forgot Password on the login screen. Let me know when you're there."
  * user: "OK done."
  * agent: "Great. next you need to enter your email address and click Submit."
  * user: "got it."
  * agent: "Now check your email for the reset link"
  * user: "uh huh."
- Repeat in this manner until you complete the entire process.

```

--------------------------------

### PHP cURL example for GET /api/accounts/me/usage/calls

Source: https://docs.ultravox.ai/api-reference/accounts/accounts-me-usage-calls-get

Uses PHP cURL to send a GET request with the X-API-Key header and outputs the response or error.

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ultravox.ai/api/accounts/me/usage/calls?timeOfDayEnd=23:59:59.999999&timeOfDayStart=00:00:00",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Install JavaScript SDK with npm

Source: https://docs.ultravox.ai/apps/sdks

Install the Ultravox client SDK for JavaScript using npm.

```bash
npm install ultravox-client
```
Tokens:
Raw