Voice Agents

Objective

Turn an existing AI agent into a phone agent that answers real inbound calls. A voice agent links a base agent to a phone number, a language, a synthetic voice, and call behaviour (analytics, call termination, transfer to a human). Every call is logged with its status, duration, transcript, AI summary, sentiment and recording so you can review what happened.

You bring the phone number one of two ways: a Helios number (bought inside the app, fully managed) or your own Twilio number (Bring Your Own). Either way, the agent starts answering as soon as it is active and the number points at Helios.

Access

Sidebar -> Telephony -> Voice Agents Route: /app/{tenant}/voice-agents

Related routes:

• /app/{tenant}/voice-agents/calls — full call history.
• /app/{tenant}/voice-agents/calls/{callId} — a single call's detail (transcript, summary, recording).
• /app/{tenant}/voice-agents/{id}/edit — edit an existing voice agent.

Roles

• owner, admin, agent — can view the page, create, edit, activate/deactivate and delete voice agents, and open call detail.
• Dismissing a call quality alert is restricted to owner and admin; agents see the alert but not the Dismiss action. This is re-checked server-side.

Prerequisites

• Voice on your plan. Voice is available on plans that include it, or through the Voice add-on. Without it the Create button opens an upgrade prompt instead of the wizard.
• A voice-agent slot. Your plan (plus any Voice Agent add-on) sets a maximum number of active voice agents. Each active voice agent counts toward that limit.
• A verified workspace email. Creating, editing or deleting a voice agent is blocked until your email is verified.
• An eligible base agent. In the Agents module you need an agent that is active, has the Voice channel enabled, and uses a realtime-compatible model. An agent already linked to another voice agent cannot be reused.
• OpenAI connected (in Integrations) — required for the AI engine, transcription and the call analytics (summary, sentiment). OpenAI is always used, even when you pick a different voice provider.
• A phone number — either a Helios number (see Phone Numbers) or your own Twilio account connected with a voice-capable number.
• Deepgram or ElevenLabs — only if you choose one of those as the voice output. Both are Bring-Your-Own-Key add-ons that bill on top of your OpenAI usage.

The Voice Agents dashboard

The main page opens on a set of all-time metrics, your connected numbers, a sentiment summary, and the most recent calls.

Below the metrics, Connected Numbers lists your voice agents as cards. You can search by agent name and sort by Newest, Oldest, Name A-Z, Name Z-A, or Active first. A dashed Add card creates a new voice agent.

The Sentiment panel appears once at least one call has been analysed, breaking calls into positive, neutral and negative. Recent Calls shows the latest calls with a link to the full history.

Create a voice agent

Click Create Voice Agent (or the Add card). The wizard has four steps; the header shows "Step X of 4".

Step 1: Select Base Agent

If the dropdown is empty, you have no eligible agent yet — enable the Voice channel on an active agent with a realtime model in the Agents module first.

Step 2: Voice Configuration

Voice providers

• OpenAI voices include Marin and Cedar (recommended), plus Sage, Ash and Verse.
• Deepgram offers Aura-2 voices across English, Spanish, Portuguese, French, German, Italian, Dutch and Japanese (for example Thalia, Asteria, Celeste, Diana).
• If you pick Deepgram or ElevenLabs and have not connected it yet, the step shows an inline panel to paste the API key (with a link to the provider console and the exact permissions/scopes to grant) before you can choose a voice.

Step 3: Behavior & Analytics

Call Analytics — each toggle is independent:

If a required integration is missing, the step shows an inline panel to connect it (paste your OpenAI key, or your Twilio Account SID and Auth Token) without leaving the wizard.

Timezone — by default the agent inherits your workspace timezone. You can override it per agent by choosing an IANA timezone from the list (used so the agent states the correct local time on calls).

Quality Monitoring (AI-assisted) — when on, Helios reviews each call for off-topic drift or information leaks and raises a quality alert on the call. Turning it off disables that safety check.

Call Termination

Call Transfer — when on, the agent can hand a call to a human:

Numbers are validated as you type; an invalid or half-filled destination blocks Next until fixed.

Step 4: Phone Number

Where you attach the number depends on what you own.

If you own one or more Helios numbers, a mode selector appears:

If you have no Helios number, you go straight to the Twilio path, with a hint to buy a Helios number instead.

Twilio (Bring Your Own)

After connecting Twilio you can pick a number from the dropdown or enter it manually. The step also shows the Voice webhook URL and Status callback URL to copy, with steps to paste them into your Twilio number configuration. Helios also tries to apply these webhooks for you when you save.

Phone Access Control (edit mode only) — once a voice agent exists, you can restrict which callers reach it using an allow list or block list.

Use Back to revise a step, Cancel to close, and Create Voice Agent on the last step to save.

Manage voice agents

Each card in Connected Numbers shows the agent name, the "Voice" type, its phone number and voice provider, plus these controls:

Inactive linked agent — if the underlying base agent has been deactivated, the card shows an amber warning. Activating the voice agent then opens a dialog to reactivate or swap to another eligible agent, so calls never route to an inactive agent.

Renaming, activating, editing and deleting each re-check your plan, email verification and the agent's eligibility on the server.

Calls

Call history (/app/{tenant}/voice-agents/calls) lists your calls with summary stats (Total, Duration, Success Rate, Average Duration). Each row shows:

Call detail

Open any call to see everything captured for it:

• A status pill and a call overview (From, To, Duration, Agent, Started/Ended time, Call ID).
• Quality alerts banner at the top when Quality Monitoring flagged the call. Owners and admins can Dismiss an alert; it stays on the record as history.
• Sentiment analysis, AI summary, and the full transcript (shown as a two-sided conversation) when those analytics are enabled.
• A recording player when Call Recording is on.
• A metadata block with any extra fields captured for the call.

Analytics fill in shortly after the call ends. A call still in progress, or one with analytics turned off, shows a "pending / no data" note instead.

Good practices

• Give the base agent a short, clear prompt — voice conversations reward brevity.
• Set a short Initial Greeting so callers know who they reached.
• Keep End Call on, and add an Inactivity Timeout as a backup so calls never hang open.
• Match the voice's language to the Primary Language (a Deepgram voice whose language differs from the agent is flagged as a likely mistake).
• For your own Twilio number, confirm both webhook URLs are pasted into Twilio; use the Repair button if calls are not connecting.
• Prefer a Helios number when you want recording and webhooks handled for you.

Common notes

• No base agent to pick — the agent is inactive, does not have the Voice channel enabled, uses a non-realtime model, or is already linked to another voice agent.
• Create opens an upgrade prompt — Voice is not on your plan, or you have reached your voice-agent limit; upgrade or add the Voice add-on.
• "Please verify your email…" — verify your workspace email, then retry.
• Analytics not filling in — OpenAI is not connected; connect it in the wizard or in Integrations.
• Recording is empty — Call Recording needs Twilio for your own number, or use a Helios number where it is included.
• "This phone number is already assigned…" — each number can be linked to only one active voice agent at a time.
• "Phone number must be in E.164 format" — enter the number with its country code and no spaces (for example +15551234567).
• Inbound calls not answered — check the agent is Active, the linked base agent is active, and (for your own Twilio number) run Repair to re-apply the webhooks.

Related

• AI Agents
• Phone Numbers
• Twilio Setup (Bring Your Own)
• Integrations