curl --request PATCH \
--url http://localhost:8080/phone/{phone_agent_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"voice_id": "<string>",
"language": [
"<string>"
],
"first_message": "<string>",
"instructions": [
"<string>"
],
"actionIds": [
"<string>"
],
"transfer_destination_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tts_speed_pct": 50,
"stt_keyterms": [
"<string>"
],
"recording_enabled": true,
"background_volume_pct": 100,
"typing_sound_enabled": true
}
'import requests
url = "http://localhost:8080/phone/{phone_agent_id}"
payload = {
"name": "<string>",
"voice_id": "<string>",
"language": ["<string>"],
"first_message": "<string>",
"instructions": ["<string>"],
"actionIds": ["<string>"],
"transfer_destination_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tts_speed_pct": 50,
"stt_keyterms": ["<string>"],
"recording_enabled": True,
"background_volume_pct": 100,
"typing_sound_enabled": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
voice_id: '<string>',
language: ['<string>'],
first_message: '<string>',
instructions: ['<string>'],
actionIds: ['<string>'],
transfer_destination_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
failover_transfer_destination_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
tts_speed_pct: 50,
stt_keyterms: ['<string>'],
recording_enabled: true,
background_volume_pct: 100,
typing_sound_enabled: true
})
};
fetch('http://localhost:8080/phone/{phone_agent_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/phone/{phone_agent_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'voice_id' => '<string>',
'language' => [
'<string>'
],
'first_message' => '<string>',
'instructions' => [
'<string>'
],
'actionIds' => [
'<string>'
],
'transfer_destination_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'failover_transfer_destination_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'tts_speed_pct' => 50,
'stt_keyterms' => [
'<string>'
],
'recording_enabled' => true,
'background_volume_pct' => 100,
'typing_sound_enabled' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:8080/phone/{phone_agent_id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"language\": [\n \"<string>\"\n ],\n \"first_message\": \"<string>\",\n \"instructions\": [\n \"<string>\"\n ],\n \"actionIds\": [\n \"<string>\"\n ],\n \"transfer_destination_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"failover_transfer_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"tts_speed_pct\": 50,\n \"stt_keyterms\": [\n \"<string>\"\n ],\n \"recording_enabled\": true,\n \"background_volume_pct\": 100,\n \"typing_sound_enabled\": true\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.patch("http://localhost:8080/phone/{phone_agent_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"language\": [\n \"<string>\"\n ],\n \"first_message\": \"<string>\",\n \"instructions\": [\n \"<string>\"\n ],\n \"actionIds\": [\n \"<string>\"\n ],\n \"transfer_destination_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"failover_transfer_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"tts_speed_pct\": 50,\n \"stt_keyterms\": [\n \"<string>\"\n ],\n \"recording_enabled\": true,\n \"background_volume_pct\": 100,\n \"typing_sound_enabled\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/phone/{phone_agent_id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"language\": [\n \"<string>\"\n ],\n \"first_message\": \"<string>\",\n \"instructions\": [\n \"<string>\"\n ],\n \"actionIds\": [\n \"<string>\"\n ],\n \"transfer_destination_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"failover_transfer_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"tts_speed_pct\": 50,\n \"stt_keyterms\": [\n \"<string>\"\n ],\n \"recording_enabled\": true,\n \"background_volume_pct\": 100,\n \"typing_sound_enabled\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"org_id": "<string>",
"phone_number": "<string>",
"outbound_caller_number": "<string>",
"name": "<string>",
"type": "inbound",
"language": [
"<string>"
],
"accent": "<string>",
"handoff_phone_number": "<string>",
"speed": 123,
"interruptible": true,
"actionIds": [
"<string>"
],
"instructions": [
"<string>"
],
"data_collection_fields": [
"<string>"
],
"data_collection_webhook_url": "<string>",
"model": "oppie-vox",
"voice_id": "<string>",
"voice_mode": "modular",
"first_message": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"provider_external_id": "<string>",
"use_org_knowledgebase": true,
"background_noise_preset": "office",
"background_volume_pct": 0,
"typing_sound_enabled": true,
"recording_enabled": true,
"search_enabled": true,
"stt_keyterms": [
"<string>"
],
"stt_model": "deepgram/flux-general",
"tts_speed_pct": 0,
"tts_provider": "elevenlabs",
"failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"transfer_destination_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"published": true,
"has_unpublished_changes": true,
"flow": null
}{
"statusCode": 123,
"message": "<string>",
"error": "<string>"
}Update an AI phone agent
Update an existing AI phone agent. Use when managing AI phone agents and their voices, knowledge and workflows from code.
curl --request PATCH \
--url http://localhost:8080/phone/{phone_agent_id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"voice_id": "<string>",
"language": [
"<string>"
],
"first_message": "<string>",
"instructions": [
"<string>"
],
"actionIds": [
"<string>"
],
"transfer_destination_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tts_speed_pct": 50,
"stt_keyterms": [
"<string>"
],
"recording_enabled": true,
"background_volume_pct": 100,
"typing_sound_enabled": true
}
'import requests
url = "http://localhost:8080/phone/{phone_agent_id}"
payload = {
"name": "<string>",
"voice_id": "<string>",
"language": ["<string>"],
"first_message": "<string>",
"instructions": ["<string>"],
"actionIds": ["<string>"],
"transfer_destination_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
"failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"tts_speed_pct": 50,
"stt_keyterms": ["<string>"],
"recording_enabled": True,
"background_volume_pct": 100,
"typing_sound_enabled": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
voice_id: '<string>',
language: ['<string>'],
first_message: '<string>',
instructions: ['<string>'],
actionIds: ['<string>'],
transfer_destination_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
failover_transfer_destination_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
tts_speed_pct: 50,
stt_keyterms: ['<string>'],
recording_enabled: true,
background_volume_pct: 100,
typing_sound_enabled: true
})
};
fetch('http://localhost:8080/phone/{phone_agent_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_PORT => "8080",
CURLOPT_URL => "http://localhost:8080/phone/{phone_agent_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'voice_id' => '<string>',
'language' => [
'<string>'
],
'first_message' => '<string>',
'instructions' => [
'<string>'
],
'actionIds' => [
'<string>'
],
'transfer_destination_ids' => [
'3c90c3cc-0d44-4b50-8888-8dd25736052a'
],
'failover_transfer_destination_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'tts_speed_pct' => 50,
'stt_keyterms' => [
'<string>'
],
'recording_enabled' => true,
'background_volume_pct' => 100,
'typing_sound_enabled' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://localhost:8080/phone/{phone_agent_id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"language\": [\n \"<string>\"\n ],\n \"first_message\": \"<string>\",\n \"instructions\": [\n \"<string>\"\n ],\n \"actionIds\": [\n \"<string>\"\n ],\n \"transfer_destination_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"failover_transfer_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"tts_speed_pct\": 50,\n \"stt_keyterms\": [\n \"<string>\"\n ],\n \"recording_enabled\": true,\n \"background_volume_pct\": 100,\n \"typing_sound_enabled\": true\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.patch("http://localhost:8080/phone/{phone_agent_id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"language\": [\n \"<string>\"\n ],\n \"first_message\": \"<string>\",\n \"instructions\": [\n \"<string>\"\n ],\n \"actionIds\": [\n \"<string>\"\n ],\n \"transfer_destination_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"failover_transfer_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"tts_speed_pct\": 50,\n \"stt_keyterms\": [\n \"<string>\"\n ],\n \"recording_enabled\": true,\n \"background_volume_pct\": 100,\n \"typing_sound_enabled\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://localhost:8080/phone/{phone_agent_id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"voice_id\": \"<string>\",\n \"language\": [\n \"<string>\"\n ],\n \"first_message\": \"<string>\",\n \"instructions\": [\n \"<string>\"\n ],\n \"actionIds\": [\n \"<string>\"\n ],\n \"transfer_destination_ids\": [\n \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n ],\n \"failover_transfer_destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"tts_speed_pct\": 50,\n \"stt_keyterms\": [\n \"<string>\"\n ],\n \"recording_enabled\": true,\n \"background_volume_pct\": 100,\n \"typing_sound_enabled\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"org_id": "<string>",
"phone_number": "<string>",
"outbound_caller_number": "<string>",
"name": "<string>",
"type": "inbound",
"language": [
"<string>"
],
"accent": "<string>",
"handoff_phone_number": "<string>",
"speed": 123,
"interruptible": true,
"actionIds": [
"<string>"
],
"instructions": [
"<string>"
],
"data_collection_fields": [
"<string>"
],
"data_collection_webhook_url": "<string>",
"model": "oppie-vox",
"voice_id": "<string>",
"voice_mode": "modular",
"first_message": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"provider_external_id": "<string>",
"use_org_knowledgebase": true,
"background_noise_preset": "office",
"background_volume_pct": 0,
"typing_sound_enabled": true,
"recording_enabled": true,
"search_enabled": true,
"stt_keyterms": [
"<string>"
],
"stt_model": "deepgram/flux-general",
"tts_speed_pct": 0,
"tts_provider": "elevenlabs",
"failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"transfer_destination_ids": [
"3c90c3cc-0d44-4b50-8888-8dd25736052a"
],
"published": true,
"has_unpublished_changes": true,
"flow": null
}{
"statusCode": 123,
"message": "<string>",
"error": "<string>"
}Authorizations
Body
Transfer destinations the agent may transfer calls to (IDs from GET /phone/transfer-destinations). The full set is replaced on every write; send [] to detach all. Destinations themselves are managed in the dashboard.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Destination the call is transferred to if the voice pipeline fails mid-call. Any destination of your organization; null falls back to the first allowed destination, then to a graceful hangup.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Speaking speed on a 1-100 scale (null = the voice default). Lower is slower; natural-sounding voices in some languages (e.g. Dutch) run best around 80-85. On voices whose id starts with "hamsa:" the same field sets expressiveness instead: the value divided by 50 (null or 50 = 1, the default; 100 = 2, the most expressive). Omitted on create, it starts at the voice's default.
1 <= x <= 100Response
Default Response
deepgram/flux-general, deepgram/nova-3, deepgram/nova-3-medical, cartesia/ink-whisper, elevenlabs/scribe_v2_realtime, xai/stt-1, assemblyai/universal-3-5-pro, speechmatics/enhanced, google/gemini-3.5-transcribe-live, soniox/stt-rt-v6, openai/gpt-live-transcribe Was this page helpful?