Skip to main content
POST
/
v1
/
agents
curl -X POST https://api.teli.ai/v1/agents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "voice",
    "agent_name": "Sales Agent",
    "starting_message": "Hi {{first_name}}, this is Sarah calling about your inquiry.",
    "prompt": "You are a friendly sales agent. Ask about their needs and budget.",
    "organization_id": "1762896364768x389173798861431550",
    "user_id": "1762896366429x599348279945132448",
    "voice_id": "11labs-Adrian",
    "language": "en-US"
  }'

{
  "success": true,
  "agent_id": "1763500416653x437043850941191495",
  "unique_id": "1763500417669x523666197914196602",
  "agent_type": "voice",
  "agent_name": "Sales Agent",
  "voice_agent_id": "agent_86f826bf8f59bacd5c10ae948a",
  "voice_llm_id": "llm_768537625c23c0da51a0c10861e0",
  "voice_id": "11labs-Adrian",
  "organization_id": "1762896364768x389173798861431550",
  "user_id": "1762896366429x599348279945132448",
  "message": "Voice agent created successfully",
  "powered_by": "Teli"
}
Create a Voice agent for AI-powered phone calls. Voice agents support extensive customization for natural conversations.
Voice agents are billed per second of call time. Voicemail detection is enabled by default.

​
Authorizations

​
X-API-Key
string
required
Authentication header containing your API key.

​
Required Fields

​
agent_type
string
required
Must be "voice" for voice agents.
​
agent_name
string
required
Display name for the agent.Example: "Sales Call Agent"
​
starting_message
string
required
First message spoken when call connects. Supports variables: {{first_name}}, {{last_name}}Example: "Hi {{first_name}}, this is Sarah calling about your inquiry. Do you have a moment to chat?"
​
prompt
string
required
AI behavior instructions. Define personality, goals, and conversation flow.Example:
You are a friendly sales agent for Acme Corp.

## Your Goals
- Qualify leads by asking about their needs
- Collect their budget and timeline
- Schedule a follow-up call if interested

## Guidelines
- Be conversational and friendly
- Don't be pushy
- If they're not interested, thank them and end politely
​
organization_id
string
required
Organization unique_id.
​
user_id
string
required
User unique_id (agent creator).
​
voice_id
string
required
Voice ID for text-to-speech. Get available voices from List Voices.Popular options:
  • "11labs-Adrian" - Male, American
  • "11labs-Rachel" - Female, American
  • "openai-Alloy" - Neutral, fast
Example: "11labs-Adrian"

​
Language Settings

​
language
string
default:"en-US"
Language for speech recognition. Options:
CodeLanguage
en-USEnglish (US)
en-GBEnglish (UK)
es-ESSpanish (Spain)
es-419Spanish (Latin America)
fr-FRFrench
de-DEGerman
ja-JPJapanese
zh-CNChinese
multiMultilingual

​
Voice Tuning

Fine-tune how the agent sounds and responds.
​
voice_temperature
number
default:"1"
Voice stability. Range: 0 (stable) to 2 (varied).
  • 0: Very consistent, robotic
  • 1: Balanced (default)
  • 2: More expressive, varied
​
voice_speed
number
default:"1"
Speech rate. Range: 0.5 (slow) to 2 (fast).
  • 0.5: Very slow
  • 1: Normal speed (default)
  • 2: Very fast
​
volume
number
default:"1"
Agent volume. Range: 0 (quiet) to 2 (loud).
​
responsiveness
number
default:"1"
How quickly agent responds. Range: 0 (slower) to 1 (faster).
  • 0: Wait longer before responding
  • 1: Respond immediately when possible
​
interruption_sensitivity
number
default:"1"
How easily user can interrupt. Range: 0 to 1.
  • 0: Agent is hard to interrupt
  • 1: Agent is easy to interrupt

​
Ambient Sound

Add background audio for realism.
​
ambient_sound
string
Background ambience. Options:
ValueDescription
nullNo ambient sound
"coffee-shop"Café atmosphere
"convention-hall"Echo, crowd noise
"summer-outdoor"Cicadas, nature
"mountain-outdoor"Birds, wind
"static-noise"Light static
"call-center"Office background
​
ambient_sound_volume
number
default:"1"
Ambient sound level. Range: 0 to 2.

​
Backchannel

Enable conversational acknowledgments like “yeah”, “uh-huh” during user speech.
​
enable_backchannel
boolean
default:"false"
Enable conversational interjections.
​
backchannel_frequency
number
default:"0.8"
How often to interject. Range: 0 (rarely) to 1 (frequently).
​
backchannel_words
array
Custom words to use. Comma-separated.Default: ["yeah", "uh-huh"]Example: ["right", "I see", "got it"]

​
Voicemail Detection

​
enable_voicemail_detection
boolean
default:"true"
Automatically detect voicemail. Enabled by default for outbound campaigns.
​
voicemail_detection_timeout_ms
number
default:"30000"
Time to wait for detection (milliseconds). Default: 30 seconds.Range: 5000 (5s) to 180000 (3 min)
​
voicemail_message
string
Message to leave on voicemail. If empty, call hangs up when voicemail is detected.Example: "Hi {{first_name}}, this is Sarah from Acme Corp. Please call us back at 555-1234."

​
Reminder Settings

What happens when user goes silent.
​
reminder_trigger_ms
number
default:"10000"
Time (ms) to wait before reminding silent user. Default: 10 seconds.
​
reminder_max_count
number
default:"1"
Max reminders before ending call. Set to 0 to disable.
​
end_call_after_silence_ms
number
default:"90000"
End call after this much silence (ms). Default: 90 seconds (1.5 min).Minimum: 10000 (10s)

​
Call Settings

​
max_call_duration_ms
number
default:"3600000"
Maximum call length (ms). Default: 1 hour.Range: 60000 (1 min) to 7200000 (2 hours)
​
begin_message_delay_ms
number
default:"0"
Delay before speaking (ms). Gives user time to say “hello”.Range: 0 to 5000
​
ring_duration_ms
number
default:"30000"
Ring timeout for outbound calls (ms). Default: 30 seconds.

​
Speech Recognition

​
stt_mode
string
default:"fast"
Speech-to-text mode:
  • "fast": Lower latency, good accuracy
  • "accurate": Higher accuracy, more latency
​
vocab_specialization
string
default:"general"
Vocabulary focus:
  • "general": General conversations
  • "medical": Medical terminology
​
boosted_keywords
array
Words to boost recognition for (brand names, product names).Example: ["Acme", "TurboWidget", "ProPlan"]
​
normalize_for_speech
boolean
default:"false"
Convert numbers/dates to spoken form. E.g., “2024” → “twenty twenty-four”

​
Advanced Settings

​
allow_user_dtmf
boolean
default:"true"
Allow keypad input (press 1, press 2, etc.)
​
denoising_mode
string
default:"noise-cancellation"
Audio cleanup:
  • "noise-cancellation": Filter background noise
  • "noise-and-background-speech-cancellation": Also filter other voices
​
data_storage_setting
string
default:"everything"
What to store:
  • "everything": Full transcripts, recordings, logs
  • "everything_except_pii": Scrub PII before storing
  • "basic_attributes_only": No transcripts/recordings

​
Knowledge Base Integration

​
knowledge_base_ids
array
Link knowledge bases for RAG retrieval during calls.Example: ["kb_7a0682ce5fc02413"]
​
kb_config
object
Knowledge base settings:
{
  "top_k": 3,           // Chunks to retrieve (1-10)
  "filter_score": 0.6   // Similarity threshold (0-1)
}

​
Tools / Function Calling

​
general_tools
array
Tools for function calling during calls. See Update Agent Tools.Types: end_call, transfer_call, custom (webhook)
curl -X POST https://api.teli.ai/v1/agents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "voice",
    "agent_name": "Sales Agent",
    "starting_message": "Hi {{first_name}}, this is Sarah calling about your inquiry.",
    "prompt": "You are a friendly sales agent. Ask about their needs and budget.",
    "organization_id": "1762896364768x389173798861431550",
    "user_id": "1762896366429x599348279945132448",
    "voice_id": "11labs-Adrian",
    "language": "en-US"
  }'

{
  "success": true,
  "agent_id": "1763500416653x437043850941191495",
  "unique_id": "1763500417669x523666197914196602",
  "agent_type": "voice",
  "agent_name": "Sales Agent",
  "voice_agent_id": "agent_86f826bf8f59bacd5c10ae948a",
  "voice_llm_id": "llm_768537625c23c0da51a0c10861e0",
  "voice_id": "11labs-Adrian",
  "organization_id": "1762896364768x389173798861431550",
  "user_id": "1762896366429x599348279945132448",
  "message": "Voice agent created successfully",
  "powered_by": "Teli"
}

​
Response Fields

​
agent_id
string
Agent identifier. Use this when creating voice campaigns.
​
voice_agent_id
string
Internal voice agent ID.
​
voice_llm_id
string
Internal LLM configuration ID.
​
voice_id
string
Configured voice ID.

​
Cold Calling / Sales

{
  "voice_speed": 1,
  "voice_temperature": 1,
  "responsiveness": 0.8,
  "interruption_sensitivity": 0.7,
  "enable_backchannel": true,
  "voicemail_message": "Hi, this is [Name] from [Company]. Please call us back."
}

​
Customer Support

{
  "voice_speed": 0.9,
  "voice_temperature": 0.8,
  "responsiveness": 0.6,
  "interruption_sensitivity": 0.9,
  "enable_backchannel": true,
  "backchannel_frequency": 0.7,
  "ambient_sound": "call-center",
  "reminder_max_count": 3
}

​
Appointment Reminders

{
  "voice_speed": 1.1,
  "voice_temperature": 0.5,
  "responsiveness": 1,
  "max_call_duration_ms": 300000,
  "voicemail_message": "Hi {{first_name}}, this is a reminder about your appointment."
}

​
Next Steps

  1. List Voices - Browse available voices
  2. Create Knowledge Base - Add RAG support
  3. Create Voice Campaign - Launch calls