Agents

Agents are the core unit in TurnCall. An agent defines the personality, voice, and capabilities of your AI assistant.

Create an Agent

curl -X POST http://localhost:8090/v1/agents \
  -H "Authorization: Bearer tc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "receptionist",
    "config": {
      "system_prompt": "You are a dental clinic receptionist...",
      "first_message": "Thank you for calling! How can I help?",
      "stt": {"provider": "deepgram", "model": "nova-3-general", "language": "en"},
      "llm": {"provider": "openai", "model": "gpt-4o-mini"},
      "tts": {"provider": "deepgram", "voice": "aura-2-helena-en"}
    }
  }'

Agent Config

{
  "name": "receptionist",
  "config": {
    "system_prompt": "You are a helpful receptionist...",
    "first_message": "Hello! How can I help?",
    "stt": {"provider": "deepgram", "model": "nova-3-general", "language": "en"},
    "llm": {"provider": "openai", "model": "gpt-4o-mini"},
    "tts": {"provider": "deepgram", "voice": "aura-2-helena-en"},
    "tools": [],
    "mcp_servers": [],
    "silence_timeout_ms": 800,
    "interruption_enabled": true,
    "smart_turn_detection": true,
    "voicemail_detection": {
      "enabled": true,
      "voicemail_message": "Please call us back..."
    },
    "server_url": {
      "url": "https://your-server.com/events",
      "events": ["*"]
    }
  }
}

Agents using the bedrock LLM provider or the aws S2S provider also take a top-level aws block for region and credentials — one per agent, shared by both. See AWS credentials.

Warnings on a Read

GET /v1/agents/{id} returns a warnings list beside the config: things worth telling you about a config that must not be refusals, because refusing them would break working agents.

{
  "id": "...",
  "config": { "...": "..." },
  "warnings": [
    {
      "code": "pronunciations_unreadable",
      "message": "tts.pronunciations: elevenlabs (eleven_flash_v2_5) does not read pronunciation markup on model 'eleven_flash_v2_5', so these words are spoken as written: Metformin",
      "words": ["Metformin"]
    }
  ]
}

Code	Means
`pronunciation_looks_like_spelling`	A pronunciation is the word typed back (`{"Metformin": "metformin"}`). Every character is legal IPA, so validation cannot refuse it — and it reaches the voice as real markup, so the word is now mispronounced differently. Ignore it if that really is the transcription
`pronunciations_unreadable`	The resolved TTS provider and model will not read the markup, so those words are spoken as written
`pronunciations_ignored_on_s2s`	`pipeline_mode: "s2s"` has no TTS stage for the markup to apply to
`knowledge_mode_unsupported`	A knowledge base is linked in `auto` mode to an S2S agent, which skips it: auto retrieval runs before each LLM turn, and a speech-to-speech model has no such point. Carries `modes` and `provider`. Link it in `tool` or `prompt` mode

Warnings are derived on every read, never stored, so an agent whose model moved out from under its pronunciations starts saying so without being edited. An empty list means nothing to report.

Template Variables

Personalize agents per-call using {{variable}} placeholders:

{
  "system_prompt": "You are helping {{customer_name}}. Their account is {{account_id}}.",
  "first_message": "Hello {{customer_name}}!"
}

Variables are rendered at call start via call-init or the API. See Server Events for how to dynamically inject variables.

Pipeline Mode

Mode	Description	Processing	Caller-perceived turnaround
`cascade` (default)	STT → LLM → TTS	~800ms	+ `silence_timeout_ms` (default 800ms)
`s2s`	Speech-to-speech via single model	~300ms	+ `silence_timeout_ms` (default 800ms)

Processing is the sum of each stage’s time-to-first-byte. It is not what the caller waits — the agent must first decide the turn has ended. With smart_turn_detection on (the default) that decision is the model’s, and VAD waits only 0.2s; silence_timeout_ms is the window when Smart Turn is off, and on S2S. See Latency. Set pipeline_mode in the agent config:

{
  "pipeline_mode": "s2s",
  "s2s": {"provider": "openai", "voice": "alloy"}
}

See Speech-to-Speech for details.

Voice Activity Detection

TurnCall uses Silero VAD for barge-in (interruption handling) and Smart Turn V3 (ML-based, local ONNX) for accurate end-of-turn detection.

{
  "interruption_enabled": true,
  "smart_turn_detection": true,
  "silence_timeout_ms": 800
}

Callers Who Go Quiet

A caller who puts the phone down without hanging up holds the line open. After the agent finishes speaking, user_idle_timeout_ms of silence prompts it to check in; a second consecutive silence ends the call with an ended_reason of customer_silent. Speaking resets the count.

{
  "user_idle_timeout_ms": 10000,
  "idle_message": "Are you still there?"
}

Field	Default	Description
`user_idle_timeout_ms`	`10000`	Silence after the agent stops speaking before it nudges. `0` disables the guard entirely
`idle_message`	`"Are you still there?"`	What the agent says on the first timeout

On cascade the line is spoken through TTS verbatim. S2S has no TTS stage, so the model is asked to check in and words it itself — expect a paraphrase rather than your exact string.

Not to be confused with silence_timeout_ms, the pause within a turn that decides you have finished your sentence. That one is measured in hundreds of milliseconds; this one in seconds, and only after the agent has spoken.

A third case is neither timeout: a turn the VAD opened and closed with no transcript — a cough, a door, a word nothing recognized. One that interrupted the agent gets a single LLM run, so the agent asks the caller to repeat instead of stopping dead mid-sentence. One that arrives while the agent was already waiting is left unanswered, because replying to a passing truck is intrusive and the idle guard above already covers a caller who has genuinely gone quiet. On by default, and not configurable.

Voicemail Detection

For outbound calls, detect voicemail and leave a message:

{
  "voicemail_detection": {
    "enabled": true,
    "voicemail_message": "Hi, this is TurnCall. Please call us back at..."
  }
}

Voicemail detection cannot be combined with pipeline_mode: "s2s".

Delete an Agent

curl -X DELETE http://localhost:8090/v1/agents/AGENT_UUID \
  -H "Authorization: Bearer tc_xxx"

Deleting archives the agent (any state): it stops answering calls and disappears from active use, while its call history, transcripts, and analyses remain queryable.

Getting Started

Guides

Create an Agent

Agent Config

Warnings on a Read

Template Variables

Pipeline Mode

Voice Activity Detection

Callers Who Go Quiet

Voicemail Detection

Delete an Agent

​Create an Agent

​Agent Config

​Warnings on a Read

​Template Variables

​Pipeline Mode

​Voice Activity Detection

​Callers Who Go Quiet

​Voicemail Detection

​Delete an Agent

Create an Agent

Agent Config

Warnings on a Read

Template Variables

Pipeline Mode

Voice Activity Detection

Callers Who Go Quiet

Voicemail Detection

Delete an Agent