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 versioned editor, switched by a pill 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
Zyan creates a v1 draft for you and opens the Agent configuration panel. Nothing is live yet.
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".
Identity, model and voice
The first collapsible section. This is who the agent says it is.
| Setting | What it changes | Default |
|---|---|---|
| Realtime model | GPT Realtime 2.1, 2.1 Mini (faster and cheaper), or the previous generation. | GPT Realtime 2.1 (recommended) |
| Voice | The spoken voice — Marin, Cedar, Alloy, Ash, Ballad, Coral, Echo, Sage, Shimmer or Verse. | Marin (recommended) |
| Reasoning effort | Turn speed against thinking. Minimal, Low, Medium or High — Minimal is fastest, High is noticeably slow on a phone line. | Low (recommended) |
| Primary language | The call's default language code, such as en-US. | en-US (placeholder) |
| Spoken name | The name the agent gives on the call. | — |
| Role | The role it states — scheduling coordinator, account manager. | — |
| Organization name used on calls | The business it says it is calling from. Set this per client, not per agency. | — |
| Identity and demeanor | Free-text persona. Capped at 2,000 characters. | — |
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.
Behaviour and turn-taking
This section is why an agent sounds human or sounds like a robot. The sliders all run 1–5.
| Setting | What it changes | Default |
|---|---|---|
| Opening line | The first thing the agent says. | — |
| AI disclosure | Upfront in the greeting, or only when asked. | — |
| Honest disclosure wording | The exact disclosure sentence. Preflight blocks the campaign while it is empty. | — |
| Response length | 1 concise → 5 detailed. | 2 |
| Warmth | 1 reserved → 5 notably warm. | 4 |
| Formality | 1 casual → 5 formal. | 2 |
| Energy | 1 calm → 5 enthusiastic. | 3 |
| Speaking pace | 1 slow → 5 fast. | 3 |
| Natural variation | 1 consistent → 5 highly varied. | 3 |
| Interruption sensitivity | 1 finishes its sentence → 5 yields immediately. A value of 1 prevents barge-in entirely. | 4 |
| Acknowledgment style | Direct, brief acknowledgment, or conversational acknowledgment. | — |
| Silence before check-in (ms) | How long it waits before prompting a quiet caller. | 2500 |
| Override workspace turn timing for this agent | Reveals four timing fields — minimum delay after pickup, listen-first window, response delay minimum and response delay maximum. Leave it off unless this agent genuinely needs a different rhythm. | Off |
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 and guardrails
What the agent may do mid-call: which actions it can take, what happens on voicemail, whether it may transfer to a person, and what it must never say.
| Setting | What it changes | Default |
|---|---|---|
| Tools | Eleven checkboxes — read lead details, search approved context, read approved pricing, check calendar availability, book a meeting, update the CRM lead, record an opt-out, request a callback, transfer to a person, move workflow stage, end the call. The section header counts how many are on. | — |
| Voicemail behavior | Hang up, leave an approved message, or schedule a retry. | Hang up |
| Voicemail message | The script left on voicemail. It only appears once the behavior is set to leave an approved message. | — |
| Allow human transfer | Reveals the four transfer fields below. | Off |
| Destination label | How the agent names the transfer target on the call. | — |
| Destination number | Where a transfer goes, in E.164. Leaving it empty with transfer on is what fails preflight. | — |
| Transfer mode | Cold transfer, or warm transfer — which is labelled not yet available and falls back instead of transferring. | Cold transfer |
| If transfer fails | Offer a callback, or end politely. | Offer callback |
| Forbidden claims | Claims the agent must never make, one per line. | — |
| Forbidden topics | Topics it must avoid, one per line. | — |
| Phrases the agent must never say | Literal banned phrases, one per line. | — |
| Maximum call length (seconds) | A hard cap on the call. Range 30 to 3600. | 600 |
Two things that will fail your first campaign
- Warm transfer is selectable but not available. It falls back instead of warm-transferring. Use cold transfer.
- Turning on Allow human transfer without setting a Destination number
makes preflight fail with
transfer_unconfigured.
Advanced runtime controls
A fourth section, collapsed by default. Turn detection decides how the agent knows you stopped talking: Semantic is recommended, and Energy-based (server VAD) adds a speech threshold, prefix padding and a silence window.
The other three rows are override toggles — Override silence handling, Override workspace language behavior and Override bounded memory limits. Each is off, and off means the agent inherits the workspace value documented in Voice & Telephony settings.
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.
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.
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 human transfer is on with no destination | Set a destination number, or turn transfer off |
| Preflight blocks on disclosure | Honest disclosure wording is empty | Write the exact sentence the agent will say |
| The configuration panel refuses to render | The raw JSON behind the panel is malformed | Fix the raw JSON first — the panel and the JSON are the same record |
| The agent talks over people | Interruption sensitivity 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 mode |