Creates a voice agent. An agent combines a response engine (a Retell LLM, a conversation flow or your own custom LLM WebSocket) with voice, speech recognition, call handling, analysis and webhook settings.
Only response_engine is required. Every other field has a default or is optional. The new agent is version 0, an unpublished draft. See Publish agent version for how versions work.
Request#
Engine and identity#
| Field | Type | Required | Description |
|---|---|---|---|
response_engine |
object | Yes | What produces the agent's replies. See response_engine. |
agent_name |
string | No | Display name. Default New agent. |
folder |
string or null | No | Dashboard folder. Default null. |
timezone |
string | No | IANA time zone for time variables. Default Australia/Sydney. |
response_engine#
One of three shapes, chosen by type:
type |
Fields | Description |
|---|---|---|
retell-llm |
llm_id (string, required), version (integer, optional) |
A Retell LLM. Must exist in the workspace. Without version the LLM's latest version is used, and publishing the agent pins it. |
conversation-flow |
conversation_flow_id (string, required), version (integer, optional) |
A conversation flow. Same version rules. |
custom-llm |
llm_websocket_url (string, required) |
Your WebSocket server. The runtime connects to {llm_websocket_url}/{call_id}. See LLM WebSocket. The URL is not checked on save; use Test custom LLM connection. |
Voice#
| Field | Type | Required | Description |
|---|---|---|---|
voice_id |
string | No | Voice from List voices or a cloned voice. Default 11labs-Adrian. |
voice_model |
string | No | TTS model. One of eleven_flash_v2_5, eleven_turbo_v2_5, eleven_v4_turbo, eleven_multilingual_v2, sonic-3, sonic-turbo, gpt-4o-mini-tts, tts-1, aura-2, speech-2.8-turbo, speech-2.8-hd, s2.1-pro, inworld-tts-1.5-max, inworld-tts-2. Default eleven_v4_turbo (the Premium tier). eleven_flash_v2_5 is the Standard tier; see Voice tiers. If the voice's provider does not offer this model, the provider's first model is used. |
voice_temperature |
number | No | 0 to 2. Default 1. |
voice_speed |
number | No | 0.5 to 2. Default 1. |
volume |
number | No | 0 to 2. Default 1. |
fallback_voice_ids |
string[] | No | Voices tried in order when the main voice's TTS fails. Default []. |
enable_dynamic_voice_speed |
boolean | No | Adjust speaking speed during the call. |
enable_expressive_mode |
boolean | No | Emotion and delivery tags ([laughs], [sigh], <emotion>) are performed by voices that support them. |
pronunciation_dictionary |
object[] | No | Entries of { "word", "alphabet", "phoneme" }, with alphabet one of ipa, cmu, pinyin, jyutping. Default []. |
normalize_for_speech |
boolean | No | Normalize reply text for speech before TTS. Default true. |
ambient_sound |
string or null | No | coffee-shop, convention-hall, summer-outdoor, mountain-outdoor, static-noise, call-center or null. Default null. |
ambient_sound_volume |
number | No | 0 to 2. Default 1. |
Language and speech recognition#
| Field | Type | Required | Description |
|---|---|---|---|
language |
string | No | Locale code, for example en-AU, or multi. Default en-AU. |
languages |
string[] | No | Languages callers may speak. More than one switches STT to multi-language mode. |
stt_mode |
string | No | fast, accurate or custom. Default fast. |
custom_stt_config |
object | No | For stt_mode: "custom": provider (deepgram, assemblyai, soniox, azure, openai; default deepgram), model (string), endpointing_ms (silence before the transcript is finalised, 10 to 5000, default 300). |
vocab_specialization |
string | No | general or medical. medical uses Deepgram nova-3-medical. |
boosted_keywords |
string[] | No | Words the recogniser should favour. Default []. |
denoising_mode |
string | No | no-denoise, noise-cancellation or noise-and-background-speech-cancellation. Default noise-cancellation. |
denoising_enhancement_level |
string | No | Extra noise suppression: low, medium or high. |
Turn taking#
| Field | Type | Required | Description |
|---|---|---|---|
responsiveness |
number | No | 0 to 1, mapped to the end-of-turn delay (1 is fastest). Default 1. |
interruption_sensitivity |
number | No | 0 to 1 (1 is most sensitive to the caller talking over the agent). Default 0.9. |
enable_dynamic_responsiveness |
boolean | No | Adapt the end-of-turn delay to how this caller speaks. |
enable_backchannel |
boolean | No | Say short acknowledgements while the caller talks. Default false. |
backchannel_frequency |
number | No | 0 to 1. Default 0.8. |
backchannel_words |
string[] | No | Words to use for backchannels. Default []. |
reminder_trigger_ms |
integer | No | Silence before the agent prompts the caller, at least 1000. Default 10000. |
reminder_max_count |
integer | No | Reminders per silence, 0 or more. Default 1. |
begin_message_delay_ms |
integer | No | Delay before the first message, 0 to 5000. Default 0. |
allow_dtmf_interruption |
boolean | No | Keypad presses interrupt the agent. |
Call handling#
| Field | Type | Required | Description |
|---|---|---|---|
end_call_after_silence_ms |
integer | No | End the call after this much silence, at least 10000. Default 600000. |
max_call_duration_ms |
integer | No | 60000 to 7200000. Default 3600000. |
ring_duration_ms |
integer | No | How long outbound calls ring, 5000 to 300000. Default 30000. |
allow_user_dtmf |
boolean | No | Accept keypad input from the caller. Default true. |
user_dtmf_options |
object | No | digit_limit (1 to 50 or null), termination_key (string or null), timeout_ms (1000 to 15000, default 1000). |
voicemail_option |
object or null | No | What to do when voicemail answers. See voicemail_option. Default { "action": { "type": "hangup" } }. null turns detection off. |
ivr_option |
object or null | No | Hang up when an automated phone menu answers: action ({ "type": "hangup" }, the default) and detection_prompt (string). |
call_screening_option |
object or null | No | Answer carrier and phone call screeners with agent_identity and call_purpose (both strings, required). |
enable_dnc_detection |
boolean | No | Detect callers asking not to be called again. |
is_transfer_agent |
boolean | No | The agent runs transfer legs for agentic warm transfers. |
voicemail_option#
| Field | Type | Description |
|---|---|---|
action |
object | { "type": "hangup" }, { "type": "static_text", "text" } (leave this exact message), { "type": "prompt", "text" } (generate the message from this prompt) or { "type": "bridge_transfer" } (transfer agents: connect the original caller to the voicemail). |
detection_prompt |
string | Extra guidance for the voicemail classifier. |
wait_for_beep |
boolean | Leave the message only after the greeting's beep or trailing silence. Default true. |
Guardrails and handbook#
| Field | Type | Required | Description |
|---|---|---|---|
guardrail_config |
object or null | No | output_topics and input_topics (arrays of harassment, self_harm, violence, sexual, hate, gambling, regulated_advice, jailbreak, scam; default []) and fallback_message (spoken instead of a blocked reply). A detected scam ends the call with scam_detected. |
handbook_config |
object | No | Presets applied to the prompt at runtime. See handbook_config. |
kb_instruction |
string | No | Up to 500 characters that steer knowledge base query rewriting and retrieval. |
handbook_config#
| Field | Type | Description |
|---|---|---|
personality |
string | default, friendly, professional, concise or empathetic. |
filler_words |
boolean | Use natural filler words. |
echo_verification |
boolean | Repeat back details to confirm them. |
nato_phonetic_alphabet |
boolean | Spell with the NATO alphabet. |
speech_normalization |
boolean | Speak numbers and symbols naturally. |
ai_disclosure |
boolean | Disclose that the caller is talking to an AI. |
smart_matching |
boolean | Match what the caller says to known options even when misheard. |
scope_boundaries |
boolean | Stay on the agent's job and decline unrelated requests. |
scope_description |
string | What the agent is for, used by scope_boundaries. Up to 2000 characters. |
high_empathy |
boolean | Acknowledge feelings before solving. |
Post-call analysis#
| Field | Type | Required | Description |
|---|---|---|---|
post_call_analysis_data |
object[] | No | Fields extracted after each call into call_analysis.custom_analysis_data. See Analysis fields. Default []. |
post_call_analysis_model |
string | No | Any model from the LLM model list (see Create Retell LLM). Default gpt-5.6-terra. |
analysis_summary_prompt |
string | No | Custom prompt for call_summary. Up to 2000 characters. |
analysis_successful_prompt |
string | No | Custom prompt for call_successful. Up to 2000 characters. |
analysis_user_sentiment_prompt |
string | No | Custom prompt for user_sentiment. Up to 2000 characters. |
Analysis fields#
Used by post_call_analysis_data, extract tools and nodes, and SMS info collection.
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | string, enum, boolean or number. |
name |
string | Yes | Key in the output. |
description |
string | No | What to extract. Default "". |
choices |
string[] | No | Allowed values for enum. |
examples |
string[] | No | Example values. |
required |
boolean | No | Default false. |
conditional_prompt |
string | No | Only extract this field when the condition holds. |
Webhooks#
| Field | Type | Required | Description |
|---|---|---|---|
webhook_url |
string or null | No | URL for this agent's call events. When null, the workspace webhook URL is used. Default null. |
webhook_events |
string[] | No | Any of call_started, call_ended, call_analyzed, transfer_started, transfer_bridged, transfer_cancelled, transfer_ended, transcript_updated. Default ["call_started", "call_ended", "call_analyzed"]. |
webhook_timeout_ms |
integer | No | 1000 to 60000. Default: the server's webhook timeout. |
Privacy and data#
| Field | Type | Required | Description |
|---|---|---|---|
data_storage_setting |
string | No | everything, everything_except_pii or basic_attributes_only. Default everything. |
data_storage_retention_days |
integer or null | No | Delete call data after 1 to 730 days. Default null (keep). |
pii_config |
object | No | For everything_except_pii: mode (post_call, the only value) and categories (default: all of person_name, address, email, phone_number, ssn, passport, driver_license, credit_card, bank_account, password, pin, medical_id, date_of_birth). |
opt_in_signed_url |
boolean | No | Give this agent's recording URLs the lifetime in signed_url_expiration_ms. |
signed_url_expiration_ms |
integer | No | 60000 to 604800000. Default 24 hours when opt_in_signed_url is on. |
contact_memory_config |
object | No | enable_read (put {{contact_memory}} into the call) and enable_update (update the memory after each call), both default false. Billed per conversation. |
Example request#
curl -X POST "https://api.tried.com.au/create-agent" \
-H "Authorization: Bearer $TRIED_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_name": "Bright Dental receptionist",
"response_engine": {
"type": "retell-llm",
"llm_id": "llm_9c8b7a6f5e4d3c2b1a0f9e8d"
},
"voice_id": "11labs-Lily",
"language": "en-AU",
"responsiveness": 0.9,
"enable_backchannel": true,
"post_call_analysis_data": [
{
"type": "boolean",
"name": "booked",
"description": "Did the caller book an appointment?"
}
],
"webhook_url": "https://example.com/tried/webhook"
}'const res = await fetch("https://api.tried.com.au/create-agent", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"agent_name": "Bright Dental receptionist",
"response_engine": {
"type": "retell-llm",
"llm_id": "llm_9c8b7a6f5e4d3c2b1a0f9e8d"
},
"voice_id": "11labs-Lily",
"language": "en-AU",
"responsiveness": 0.9,
"enable_backchannel": true,
"post_call_analysis_data": [
{
"type": "boolean",
"name": "booked",
"description": "Did the caller book an appointment?"
}
],
"webhook_url": "https://example.com/tried/webhook"
}),
});
const data = await res.json();import os, requests
res = requests.post(
"https://api.tried.com.au/create-agent",
headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
json={
"agent_name": "Bright Dental receptionist",
"response_engine": {
"type": "retell-llm",
"llm_id": "llm_9c8b7a6f5e4d3c2b1a0f9e8d",
},
"voice_id": "11labs-Lily",
"language": "en-AU",
"responsiveness": 0.9,
"enable_backchannel": True,
"post_call_analysis_data": [
{
"type": "boolean",
"name": "booked",
"description": "Did the caller book an appointment?",
},
],
"webhook_url": "https://example.com/tried/webhook",
},
)
data = res.json()Response#
201 Created with the agent. Every field is returned with its default filled in, plus:
| Field | Type | Description |
|---|---|---|
agent_id |
string | agent_ plus 24 hex characters. |
version |
integer | 0 for a new agent. |
is_published |
boolean | false for a new agent. |
last_modification_timestamp |
integer | Epoch ms. |
{
"agent_name": "Bright Dental receptionist",
"response_engine": { "type": "retell-llm", "llm_id": "llm_9c8b7a6f5e4d3c2b1a0f9e8d" },
"voice_id": "11labs-Lily",
"voice_model": "eleven_v4_turbo",
"voice_temperature": 1,
"voice_speed": 1,
"volume": 1,
"fallback_voice_ids": [],
"language": "en-AU",
"responsiveness": 0.9,
"interruption_sensitivity": 0.9,
"enable_backchannel": true,
"backchannel_frequency": 0.8,
"backchannel_words": [],
"reminder_trigger_ms": 10000,
"reminder_max_count": 1,
"ambient_sound": null,
"ambient_sound_volume": 1,
"begin_message_delay_ms": 0,
"end_call_after_silence_ms": 600000,
"max_call_duration_ms": 3600000,
"ring_duration_ms": 30000,
"stt_mode": "fast",
"boosted_keywords": [],
"denoising_mode": "noise-cancellation",
"allow_user_dtmf": true,
"user_dtmf_options": { "digit_limit": null, "termination_key": null, "timeout_ms": 1000 },
"voicemail_option": { "action": { "type": "hangup" } },
"pronunciation_dictionary": [],
"normalize_for_speech": true,
"post_call_analysis_data": [
{ "type": "boolean", "name": "booked", "description": "Did the caller book an appointment?", "required": false }
],
"post_call_analysis_model": "gpt-5.6-terra",
"webhook_url": "https://example.com/tried/webhook",
"webhook_events": ["call_started", "call_ended", "call_analyzed"],
"data_storage_setting": "everything",
"data_storage_retention_days": null,
"timezone": "Australia/Sydney",
"folder": null,
"agent_id": "agent_3f9a1c0b2d4e5f6a7b8c9d0e",
"version": 0,
"is_published": false,
"last_modification_timestamp": 1792310400000
}Errors#
| Status | When |
|---|---|
400 |
Validation failed. The message names each invalid field, for example voice_speed: Number must be less than or equal to 2. |
401 |
Missing or invalid API key. |
403 |
The key's IP allowlist or scopes reject the request. This route needs the agents scope. |
404 |
The llm_id or conversation_flow_id (and version, if given) does not exist. |
429 |
Rate limit exceeded. See Rate limits. |
See Errors for the body format.