Create an AI phone agent

curl --request POST \
  --url http://localhost:8080/phone \
  --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
}
'

import requests

url = "http://localhost:8080/phone"

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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  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
  })
};

fetch('http://localhost:8080/phone', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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
  ]),
  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"

	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}")

	req, _ := http.NewRequest("POST", 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.post("http://localhost:8080/phone")
  .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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/phone")

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

request = Net::HTTP::Post.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}"

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

{
  "id": "<string>",
  "org_id": "<string>",
  "phone_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>",
  "first_message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "provider_external_id": "<string>",
  "flow": null,
  "custom_llm": "<string>",
  "use_org_knowledgebase": true,
  "background_noise_preset": "office",
  "recording_enabled": true,
  "stt_keyterms": [
    "<string>"
  ],
  "stt_model": "deepgram/flux-general",
  "tts_speed_pct": 0,
  "failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "transfer_destination_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>"
}

POST

phone

Create an AI phone agent

curl --request POST \
  --url http://localhost:8080/phone \
  --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
}
'

import requests

url = "http://localhost:8080/phone"

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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  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
  })
};

fetch('http://localhost:8080/phone', 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",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  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
  ]),
  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"

	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}")

	req, _ := http.NewRequest("POST", 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.post("http://localhost:8080/phone")
  .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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/phone")

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

request = Net::HTTP::Post.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}"

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

{
  "id": "<string>",
  "org_id": "<string>",
  "phone_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>",
  "first_message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "provider_external_id": "<string>",
  "flow": null,
  "custom_llm": "<string>",
  "use_org_knowledgebase": true,
  "background_noise_preset": "office",
  "recording_enabled": true,
  "stt_keyterms": [
    "<string>"
  ],
  "stt_model": "deepgram/flux-general",
  "tts_speed_pct": 0,
  "failover_transfer_destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "transfer_destination_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

{
  "statusCode": 123,
  "message": "<string>",
  "error": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name

string

required

Agent display name

type

enum<string>

Agent type: "inbound" (receives calls, default) or "outbound" (makes calls)

Available options:

inbound,

outbound

voice_id

string | null

Voice ID from the /phone/voices endpoint. Omit for default voice.

language

string[]

ISO-639-1 language codes the agent should speak. A subset of {en, es, fr, de, hi, ru, pt, ja, it, nl} can be combined freely. Any other code (e.g. "ar", "tr", "zh") must be the only entry; Arabic accepts dialect tags such as "ar-SA".

Minimum array length: 1

first_message

string | null

What the agent says when it picks up (default: "Hello?")

instructions

string[] | null

The call prompt as an array of instruction blocks. Joined in order into the system prompt at call time. Sending this on update replaces the whole array.

actionIds

string[] | null

HTTP actions the agent can call as tools during calls (action IDs from GET /actions). The full set is replaced on every write; send [] to detach all, omit or send null to leave it unchanged. IDs must belong to your organization.

transfer_destination_ids

string<uuid>[]

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.

Pattern:

^([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)$

failover_transfer_destination_id

string<uuid> | null

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.

Pattern:

^([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)$

tts_speed_pct

integer | null

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.

Required range: 1 <= x <= 100

stt_keyterms

string[] | null

Custom vocabulary to boost in speech recognition: brand and product names, jargon, spellings the transcriber typically mishears. The agent name and transfer destination names are merged in automatically.

recording_enabled

boolean

Record calls handled by this agent (default: false).

Response

Default Response

string

required

org_id

string

required

phone_number

string | null

required

name

string | null

required

type

enum<string>

required

Available options:

inbound,

outbound

language

string[]

required

accent

string | null

required

handoff_phone_number

string | null

required

speed

number | null

required

interruptible

boolean

required

actionIds

string[] | null

required

instructions

string[] | null

required

data_collection_fields

string[] | null

required

data_collection_webhook_url

string | null

required

model

enum<string>

required

Available options:

oppie-vox,

oppie-vox-turbo,

oppie-vox-livekit

voice_id

string | null

required

first_message

string | null

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

provider_external_id

string | null

required

flow

unknown

required

custom_llm

string | null

required

use_org_knowledgebase

boolean

required

background_noise_preset

enum<string> | null

required

Available options:

office,

bar,

city-street

recording_enabled

boolean

required

stt_keyterms

string[]

required

stt_model

enum<string> | null

required

Available options:

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,

soniox/stt-rt-v5

tts_speed_pct

integer | null

required

Required range: -9007199254740991 <= x <= 9007199254740991

failover_transfer_destination_id

string<uuid> | null

required

Pattern:

^([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)$

transfer_destination_ids

string<uuid>[]

required

Transfer destinations the agent may transfer to (transfer_call targets).

Pattern:

^([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)$

Overview

Blocklist

Autopilot

Organization

Contacts

Companies

Sessions

Connect

AI Phone Agents

AI Email

AI WhatsApp

AI Actions

AI Outbound Sequencing

Media

AI Training

Resource Usage

Customer Insights

Teams

CSAT

Redaction

Crawl

Tags

Office Hours

Handoff Analytics

SLA Analytics

Secrets

Workflows (Beta)

Salesforce MIAW

Webhooks

Create an AI phone agent

Authorizations

Body

Response