Create your first voice agent
Build, configure and publish an AI calling agent — identity and voice, how it talks, and the settings that decide whether a call sounds human or robotic.
A voice agent is an AI that makes and takes phone calls for you. Setting one up is the part of Zyan people get stuck on most, because an agent is really three things at once: who it claims to be, how it talks, and what it is allowed to do. This page walks all three in order.
Before you start
You need the Voice plan feature and the voice permission (owners have it
automatically). Editing an agent additionally needs voice edit permission.
Create the agent
Agents and Products share one roster, switched by the Agents / Products lens at the top of the tab — make sure you are on Agents before you start.
Open Voice Agents
Go to CRMVoice Agents. The Agents tab is already selected.
Click New agent
Give it a Name. The placeholder is Outbound SDR; use something you will recognise in a campaign picker six months from now.
Pick a use case
General / custom, Existing website rebuild, or New website. This only seeds the starting configuration — you can change everything after.
Click Create
The new agent joins the roster as a v1 draft. Open its row to reach
the record at /admin/voice-agents/agents/<id>; the header reads No
published version until you publish. Eight tabs: Overview · Agent ·
Behavior · Workflow · Knowledge · Tools · Analysis · Advanced.
A new agent cannot be used until you publish it
Campaigns only offer published versions. A draft you saved but never published will not appear anywhere, and this is the single most common reason people think voice agents "aren't working".
The record
Every tab shares the page header and the hero under it. The header carries the three test doors — Prompt preview, Call my phone and Talk to agent. The hero's version bar reads vN · Status with the muted Unsaved word beside it, then Save draft, Publish…, and — on a published version — Edit as new draft, with the kebab that holds the record verbs beside them. An edit survives a tab switch; leaving the record with unsaved changes asks once. A validation error badges the tab its field lives on, so a count on Tools means the problem is on Tools.
Workflow and Knowledge have their own pages — Writing the call workflow and Build a knowledge base for your agents. The four tabs below are the ones that decide whether a call sounds human.
Agent
Who the agent says it is and what it sounds like — four cards.
Identity
| Setting | What it changes | Default |
|---|---|---|
| Name | The roster name. Rename in the header kebab jumps here. | — |
| Use case | General / custom, Existing website rebuild, or New website. Routing uses this field, never the agent name. | — |
| Display name | The name it says on a call. | — |
| Role | The role it states — scheduling coordinator, account manager. Prompt preview only. | — |
| Organization | The business it says it is calling from. Live calls use the workspace name. | — |
| Time zone | Previews only; live calls use the workspace zone. | — |
Prompt
| Setting | What it changes | Default |
|---|---|---|
| Identity and demeanor | Free-text persona. Capped at 2,000 characters. | — |
| First message | Said once, after the caller answers. | — |
| Disclose | Upfront in the greeting, or only when asked. Only when asked never lets the agent claim it is human — confirm the disclosure rules for your audience and jurisdiction. | Upfront in the greeting |
| AI disclosure | The honest wording — the exact sentence the agent says. Preflight blocks the campaign while it is empty. | — |
| Who speaks first | Agent, or Caller — with Caller the agent waits, then folds the disclosure into its first reply. | Agent |
| Goal | Campaigns use their own purpose; this goal drives previews and test calls. | — |
| Approved next steps | The calls-to-action the agent may offer, one per line. | — |
Write the persona as instructions, not a biography
“Warm but brief. Never oversells. If the person sounds busy, offers to call back and ends the call” produces a better call than three paragraphs of backstory the agent has no way to use.
Voice
| Setting | What it changes | Default |
|---|---|---|
| Model | GPT Realtime 2.1, 2.1 Mini (faster, lower cost), or the previous generation. | GPT Realtime 2.1 — recommended |
| Voice | Marin, Cedar, Alloy, Ash, Ballad, Coral, Echo, Sage, Shimmer or Verse. | Marin (recommended) |
| Reasoning | Turn speed against thinking — Minimal (fastest turns), Low, Medium or High (slowest turns). gpt-realtime-2 models only; inert on legacy ids. | Low — recommended for calling |
| Caller transcription | Transcribes the caller only; the agent hears the audio itself. | GPT-4o Mini Transcribe — recommended |
| Speed | 0.80–1.20×. 1.00× is the natural pace. | 1.00× |
| Runtime | Set by the platform. Read-only. | — |
Language
| Setting | What it changes | Default |
|---|---|---|
| Primary language | The call's default language code, such as en-US. | en-US (placeholder) |
| Override workspace language policy | Reveals Policy and Supported languages. Off means the agent inherits the workspace policy from Voice & Telephony settings. | Off |
| Policy | Fixed language, or Detect once near call start. | — |
| Supported languages | The languages the agent may switch to. | — |
Behavior
Why an agent sounds human or sounds like a robot. The sliders all run 1–5.
Speaking style
| Setting | What it changes | Default |
|---|---|---|
| Brevity | 1 concise → 5 detailed. | 2 |
| Enthusiasm | 1 calm → 5 enthusiastic. | 3 |
| Pace | 1 slow → 5 fast. | 3 |
| Warmth | 1 reserved → 5 warm. | 4 |
| Formality | 1 casual → 5 formal. | 2 |
| Variation | 1 consistent → 5 varied. | 3 |
| Acknowledgement | Direct, Brief acknowledgment, or Conversational acknowledgment. | — |
Turn-taking
| Setting | What it changes | Default |
|---|---|---|
| Interruptions | 1 finishes its sentence and never yields — the phone-echo fence; 5 yields instantly. | 4 |
| Detection | How the agent knows you stopped talking: Semantic (recommended), or Energy-based (server VAD). | Semantic (recommended) |
| Eagerness | Semantic only. Auto maps Interruptions 1–2 to low, 3 to medium, 4–5 to high; a pick overrides the slider. | Auto — from the Interruptions slider |
| Speech threshold | Energy-based only. How loud a sound must be to count as speech. | — |
Energy-based detection false-triggers on a phone line
It reacts to echo and background noise as if it were speech. Use it only with noise cancellation armed, and prefer Semantic everywhere else.
Silence, timing, audio and length
| Setting | What it changes | Default |
|---|---|---|
| Silence before check-in | How long a quiet caller waits for a check-in, in milliseconds. Superseded by the silence override below it. | 2500 |
| Override workspace silence policy | Reveals the per-agent silence cadence. Off inherits the workspace policy. | Off |
| Override workspace turn timing | Reveals Minimum delay after pickup, Listen-first window, Response delay minimum and Response delay maximum. Only when one agent needs a different rhythm. | Off |
| Noise cancellation | On only while the workspace toggle and the platform gate are on. | — |
| Maximum call length | A hard cap on the call, in seconds. Tests cap at 300 s; the call closes at the limit. | 600 |
| Closing line | Said as the cap closes the call; about 30 words fit before the 15-second cut. Up to 200 characters. Placeholder: Thanks for your time — we'll follow up by text. | — |
Turn timing has a workspace default
The defaults for turn timing live in SettingsVoice & TelephonyAdvanced voice behavior defaults. Change them there once rather than overriding on every agent.
Tools
What the agent may do mid-call: which tools it can call, whether it may hand the call to a person, what happens on voicemail, and what it must never say.
Tools
Twelve switches in three groups — Read (Read lead details, Search approved context, Read approved pricing, Check calendar availability), Act (Book a meeting, Send a follow-up text, Update the CRM lead, Record an opt-out, Request a callback) and Control (Transfer to a person, Move workflow stage, End the call). The card's footer counts how many are permitted. Send a follow-up text is marked Unavailable and cannot be turned on. Turning off Record an opt-out or End the call raises Opt-out and end-call tools are strongly recommended.
Transfer, voicemail and guardrails
| Setting | What it changes | Default |
|---|---|---|
| Allow transfer | Reveals the four transfer rows below. | Off |
| Number | Where the call goes. Leaving it empty with transfer on is what fails preflight. | — |
| Label | How the agent names the person. | — |
| Mode | Cold hands the call over. Warm always falls back — a version saved with warm reads Warm — not available until you pick Cold. | Cold |
| If it fails | Offer a callback, or End politely. | Offer a callback |
| Behavior | On voicemail: Hang up, Leave a message, or Schedule a retry. Detection is by the model — no answering-machine detection. | Hang up |
| Message | Read out when a machine answers. Only appears for Leave a message. | — |
| Never claim | Claims the agent must never make, one per line. | — |
| Never discuss | Topics it must avoid, one per line. | — |
| Never say | Literal banned phrases, one per line. | — |
The thing that will fail your first campaign
Turning on Allow transfer without a Number makes preflight fail with
transfer_unconfigured.
Advanced
The notice at the top reads Workflow-supervised voice runtime: On or Off — the workspace switch in Voice & Telephony settings. Everything under Runtime features applies on that runtime.
| Setting | What it changes | Default |
|---|---|---|
| Workflow supervisor | Runs the Workflow stages in order. | On |
| Human timing | Pickup gate, listen-first and reply delays. | On |
| Silence policy | The Silence card cadence; off keeps the legacy check-ins. | On |
| Bounded memory | Turns and topics the supervisor puts in the stage prompt. | On |
| Quality metrics | Per-call quality scores. | On |
| Stale-response cancellation | Read-only. Follows Interruptions above 1. | — |
| Answering-machine detection | Read-only. Off. | — |
| Override workspace memory | Reveals the six memory limits. Only when one agent needs different limits. | Off |
Versions lists every version with its status and when it was last updated; the kebab on a row holds Open and Restore as new draft. Under it, Raw JSON (validated on save) is the record itself, folded. Every tab writes into that JSON — if it stops parsing, the other tabs read Fix the raw JSON before using structured settings. and a save stops with Configuration is not valid JSON. until it parses again.
Publish
Save draft
Unsaved changes are saved automatically before publishing or testing, but saving deliberately makes the version history readable later.
Fix any validation errors
Validation errors block publishing and name the field they came from.
Publish
The version becomes available to campaigns. Publishing archives whichever version was published before it.
Published and archived versions are read-only. To change a published agent, use Edit as new draft — it clones the version so the live one keeps running while you work.
Rename, duplicate, archive
The header kebab holds Rename · Restore as new draft · Duplicate · Archive (an archived agent shows Unarchive instead). Archive asks Archive this agent? — it leaves the roster and new campaigns, and you can unarchive it later. The roster's Status lens Archived lists archived records, and an empty roster keeps a View archived door. Duplicate copies the newest version into a new draft and opens the copy.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The agent does not appear when building a campaign | No version has been published | Open the agent, Publish the draft |
Preflight fails with transfer_unconfigured | Allow transfer is on with no Number | Set a number on Tools, or turn transfer off |
| Preflight blocks on disclosure | AI disclosure is empty | Write the exact sentence the agent will say, on Agent |
| A tab reads Fix the raw JSON before using structured settings. | The raw JSON behind the tabs is malformed | Open Raw JSON (validated on save) on Advanced and fix it — the tabs and the JSON are the same record |
| The agent talks over people | Interruptions is too low | Raise it; 4 is the default for a reason |
| Energy-based turn detection keeps false-triggering | Phone-line echo and background noise | Use it only with noise cancellation armed, or switch Detection to Semantic |