Build and Configure a Voice Agent
The Quick start gets you to a working agent in five minutes. This page is what to reach for after that: the full list of fields on an agent, grouped by how much they matter, in the order you should fill them in.
Three tiers plus a publish step. Skim the tier headings and stop wherever the payoff drops off for your use case.
- Required: the five fields an agent needs to hold a real conversation.
- Recommended: the common capabilities to enable next. Greet on pickup, take a phone number, ground in a knowledge base.
- Advanced: audio quality, turn-taking, timeouts, voicemail. Reach for these when you’re tuning a live agent.
- Publish and activate: the two-step gate that promotes your changes to live traffic.
Everything below is written for the dashboard flow, which is the fastest path. Every field maps to a JSON attribute on the underlying agent config, so the same guide works if you’re driving through the API. See the Agents API reference and the Versioning lifecycle for the exact endpoints and field names.
Required
The five things that separate a blank agent from one that can hold a real conversation.
Name
New agents are named Untitled Agent (then Untitled Agent (2), and so on). To rename one, open the ⋮ menu at the top right of the editor and choose Rename agent. This is the label you’ll see in the dashboard, logs, and analytics; callers never hear it.
Prompt
The prompt is the single largest driver of agent quality. On the Prompt tab, write instructions in Agent prompt covering four things:
- Role & objective. Who is this agent, what is its goal.
- Conversational flow. The sequence of steps or questions the agent walks through.
- Dos, don’ts, fallbacks. How to behave on off-topic questions, silence, or angry callers.
- End conditions. When the call should wrap up.
Templates (Create from template on the Agents page) ship with a working prompt for common use cases; start there and edit, rather than writing from scratch.
Voice
Pick a voice from the library (Voice, on the Prompt tab). Preview it before you save; every voice has its own energy and a bad match burns caller trust fast.
A few things to check when previewing:
- The voice supports every language you add under Languages (below). If it doesn’t, the Languages card shows an Incompatible voice warning, and Test agent and Publish are blocked until you change the voice or remove the language.
- The voice can carry the emotional register of your use case. A collections agent needs a different voice than a wellness one.
Language
On the Prompt tab, the Languages card lists every language the agent can speak. The one marked Primary is the language it starts in; pick the one you expect on most calls. Use Add a language to add the others it may switch to mid-call. To change the primary language, open another language’s menu and choose Set as primary.
Which languages you can use depends on the agent’s STT model, model, and voice. See Supported languages.
A language you don’t list here will not be handled, even if the caller speaks it. Add every language you actually expect to encounter.
On the API these are language.default (the primary language) and language.supported. Both take language codes like en, hi, and es. There are no regional variants such as en-IN; use en.
Model
Pick the LLM (Model, on the Prompt tab). This is the brain behind the prompt.
- Electron (default). Smallest AI’s in-house model. Lowest latency for voice, competitive quality on prompt following. Good default; switch away only if you have a specific reason.
- GPT-4o, GPT 4.1, GPT Realtime, and GPT Realtime Mini. External models. Pick these when you need a specific frontier-model capability.
At this point the agent can be tested: click Test agent in the top-right, pick Telephony, Webcall, or Chat, and try a real turn. Fix anything obviously broken in the prompt before moving on to the next tier.
Recommended
Every agent that goes live in production has these three. They’re not strictly required but the caller experience is materially worse without them.
First message
The exact words the agent speaks the moment the call connects, before the caller has said anything. Without this, the agent waits for the caller to speak first, which feels broken on outbound and awkward on inbound.
Keep it short. Two sentences maximum. Introduce the agent, state the reason for the call, invite a response.
On the API, this is firstMessage on the draft config. Max 500 characters.
Phone number
Connect telephony on the agent’s Phone numbers tab. Inbound and outbound are separate: attach a number under Answers on so callers reach the agent, and attach a caller ID under Dials from (or pass fromNumber per call) so it can dial out. Buy numbers from Deploy → Phone Numbers or bring your own via SIP trunks.
Skipping this only makes sense for web-call-only agents (embedded widget, browser SDK). Everyone else needs a number.
Knowledge base
A knowledge base grounds the agent in your actual policies, product catalog, or FAQ. Without one, the agent will confabulate specifics (“our return policy is 30 days”) that may or may not match reality.
Ingest source material (PDFs, URLs, plain text) once under Knowledge Base in the dashboard sidebar. Then, on the agent’s Tools tab, turn on Knowledge base under System tools and pick your knowledge base. On the API, this is globalKnowledgeBaseId. Every retrieval query the agent runs at call-time is scoped to what you ingested.
Advanced
Tuning knobs. Every default here works for the majority of agents; only touch these when you have a specific problem to fix, and only change one at a time so you can measure the effect.
Voice detection (VAD)
Controls when the platform decides the caller has started or stopped speaking. Tighter thresholds pick up soft speech but also pick up background noise; looser thresholds miss soft speech but ignore noise.
Fields on the API: voiceDetectionConfig.confidence, .minVolume, .triggerTimeInSecs, .releaseTimeInSecs. Change one at a time and A/B on real calls.
Denoising
Server-side noise suppression on the caller audio before it hits the ASR. On by default when the model supports it. Turn off (denoisingConfig.isEnabled: false) only if you’re seeing over-suppression artifacts on your specific caller distribution.
Voicemail detection
Detects when an outbound call is answered by voicemail and lets you decide what to do: hang up, leave a specific message, or fall through. voiceMailDetectionConfig.enabled toggles it; .endText is what to leave on the machine before hanging up.
Essential for outbound at scale. Without it, every voicemail eats the full prompt.
Idle and session timeouts
llmIdleTimeoutConfig.chatTimeoutTimeInSecs. How long to wait for the LLM to reply before treating it as stuck.sessionTimeoutConfig.timeoutTimeInSecs. Hard cap on the whole call (default 1800s / 30 min).
Raise the session cap for use cases with expected long conversations (support triage, longform surveys). Lower it as a safety net for outbound campaigns where anything past N minutes indicates a stuck call.
Turn-taking and interruptions
smartTurnConfig. Enables end-of-utterance detection tuned for conversational back-and-forth rather than fixed silence timers.allowInterruptions. Whether the caller can talk over the agent to cut it off.interruptionBackoffTimer. How long after being interrupted the agent waits before speaking again.muteUserUntilFirstBotResponse. Mutes the caller until the first-message finishes. Useful for outbound to prevent caller “hello?” from stepping on the agent’s opener.waitForUserToSpeakFirst. Inverts the flow: the agent waits for the caller to talk. Only sensible for inbound where the caller is expected to state their intent.
Pronunciation dictionary
pronunciationDicts is an array of {word, pronunciation} pairs. Use it when the agent mispronounces a domain-specific word (product name, drug name, proper noun) consistently. Cheaper than switching voices.
Publish and activate
Every change you make in the editor lives on a draft. What happens when you publish depends on the branch: on the live branch (marked Active), publishing ships straight to callers; on any other branch, the change reaches callers only once you make that branch live.
Publish the draft
Click Publish in the editor. This snapshots your current draft as an immutable revision on the current branch. Give it a short label so you can identify it later (“prompt v2”, “voice A/B”).
On the live branch, the Review changes dialog warns you that publishing ships to production immediately. On any other branch, nothing changes for callers yet.
Publishing runs a security scan. If your agent has an API tool with no authentication configured, the scan raises an authentication finding and the publish is withheld (the draft stays unpublished). To publish anyway, acknowledge the risk: confirm the risk prompt in the dashboard, or set acceptAuthenticationRisk: true on the publish call when driving through the API.
Make the branch live (other branches only)
If you published on a branch that isn’t live, open Branches in the agent’s sidebar, click the three-dot menu on that branch, and choose Set as active. Confirm with Make live in the Make this branch live? dialog. This is the moment your changes reach real callers.
Each agent has exactly one live branch at a time, and its newest revision serves traffic. To roll back, open Version history and use Revert to this version on an older revision.
Publishing on a branch that isn’t live leaves the change invisible to callers. If you edit an agent and callers say “nothing changed,” check which branch you published on: the live one shows the Active badge on the Branches page.
What’s next
FAQ
What do I configure first on a voice agent?
Start with the required settings in this guide, then recommended, then advanced. Finish by publishing and activating the agent.
Can a voice agent call tools mid-conversation?
Yes. Attach built-in or custom tools so the agent can take actions while the call is live. See the voice agent tools overview.
How do I give a voice agent documents to cite?
Upload or scrape sources into a knowledge base and attach it to the agent. See knowledge base for voice agents.