Are you an LLM? You can read better optimized documentation at /docs/embedding/voice.md for this page in Markdown format
Voice & Dial-Out
A visitor clicks "Talk to us" and, seconds later, they're mid-conversation with your AI agent — no phone number, no app to install, just their browser. Or they'd rather take the call on their mobile, so the agent rings them. That's what voice chat and dial-out make possible, and this page shows you how they work in your widget.
If you haven't embedded the widget yet, start with the Quickstart first, then come back here.
What gets enabled and when
Both capabilities are opt-in switches on your agent's Web Chat trigger node (Configure tab → Capabilities): Enable voice chat and Enable dial-out (Call Me). When your widget loads, it calls /init and receives a capabilities object:
json
{ "voice_chat": true, "dial_out": false, "file_upload": true, "show_history": false, "allow_new_chat": true, "allow_export": false }If a switch is on but something it needs is missing — say, the agent has no chat model, or no phone number to call from — the capability comes back false and you also receive a capability_warnings list explaining what's incomplete. When a capability is off, the widget hides the matching button automatically, so your visitors never see a broken control.
In-browser voice chat
When voice_chat is true, your visitors can speak to your agent directly in the browser over a real-time audio connection — no phone call needed. Voice runs on Perfox-managed infrastructure; there's nothing to host.
To enable it: turn on Enable voice chat and pick a voice mode:
| Mode | What the visitor sees |
|---|---|
| Nova animation (default) | An audio-reactive animation instead of the live transcript. Choose its Animation style: Cloud, Radial, Circle or Bars. The agent speaks everything. |
| Voice call | Like a phone call — the live transcript, the agent speaks everything, no cards, tables or charts. |
| Copilot (Beta) | Voice plus on-screen visuals — the agent speaks a short answer and shows cards, tables or charts in the chat. |
When the visitor starts a call, the widget first asks for microphone access, then opens the session. The mic stays muted until the agent's greeting finishes, so nobody talks over it. Behind the scenes the widget uses three endpoints:
| Endpoint | What it does |
|---|---|
POST /api/public/widget/voice/start | Opens a session and returns a room token + connection URL, the voice_session_id, and the voice mode to render. |
POST /api/public/widget/voice/inject_text | Pushes a typed text turn ({ voice_session_id, text }) into the live session. The widget uses it when the visitor types or attaches a file mid-call. |
POST /api/public/widget/voice/stop | Ends the session ({ voice_session_id }). |
Each call is recorded as three audio files — caller audio, AI audio, and a combined stereo mix — which you can play back from the conversation in Studio. Spoken turns are also saved to the transcript, so after a reload they replay as ordinary text.
/voice/start can refuse with:
| Status | Code | Cause |
|---|---|---|
| 403 | voice_chat_not_enabled | The switch is off. |
| 503 | voice_chat_prereq_failed | Something voice needs is missing — see remediation in the response. |
| 402 | out_of_credits | Your workspace has no credits left. |
| 429 | concurrent_voice_limit_reached | Too many voice sessions are running at once. |
Worked example
Setup: Acme Diagnostics has a support widget on their patient portal. Asha (their workspace admin) turns on Enable voice chat on the Web Chat trigger with the Voice call mode.
Action: Priya visits the portal and clicks the voice button. She allows her microphone, the widget calls /voice/start and joins the session, and after the greeting Priya asks about her appointment — the agent answers in real time.
Result: When Priya hangs up, the widget calls /voice/stop. The session ends, and the call's transcript and recordings appear on the conversation in Studio.
What just happened: The widget managed the entire session lifecycle — microphone, connect, conversation, disconnect — using the three endpoints above. Asha didn't write a single line of audio handling code.
Outbound dial-out
When dial_out is true, your widget can place an outbound phone call to a number your visitor provides — useful when a visitor prefers to talk over their mobile rather than through the browser.
To enable it: turn on Enable dial-out (Call Me) on your Web Chat trigger, and give the agent its own number to call from: add a Phone trigger to the agent with the Plivo number it should use, on a Plivo account connected on the Credentials page. There is no default calling number — an agent without its own number can't dial out.
The widget sends:
POST /api/public/widget/call
{ "phone_number": "+919876543210", "conversation_id": "…", "customer_id": "…", "user_context": { … } }and gets back { call_id, status: "calling", phone }, where phone is the number actually dialled. Send numbers in international format; a number without a country code is read as an Indian number. The call uses the same agent persona and tools as the chat — so the conversation feels continuous. It is always placed from the agent's own number (the one on its Phone trigger).
To protect you from toll fraud, every dial-out is checked before anything is dialled:
- Destination — the number must be in a country Perfox dials (India by default) and must not be a premium-rate or special-rate number.
- Limits — at most 3 calls an hour from one visitor's network address, 3 an hour to the same number, 10 an hour per site, and 50 a day for your workspace.
- Credits — your workspace must have credits left.
| Status | Code | Cause |
|---|---|---|
| 400 | invalid_phone_number | The number can't be dialled — ask for it with the country code. |
| 402 | out_of_credits | Your workspace has no credits left. |
| 403 | dial_out_not_enabled | The switch is off. |
| 403 | country_not_allowed / premium_rate_destination | The number is outside the countries Perfox dials, or is a premium/special-rate number. |
| 429 | rate_limited | One of the call limits above was reached — try again later. |
| 503 | dial_out_prereq_failed | The agent has no number on its Phone trigger, or that number isn't on a connected Plivo account — see remediation. Your workspace is also notified. |
| 503 | missing_credential | No Plivo configuration was found for the call. |
| 503 | limiter_unavailable | The call limits couldn't be checked, so the call wasn't placed — try again shortly. |
Dictation (speech to text)
Separately from live voice, the message box always offers dictation: the visitor taps the dictate button, speaks, taps again, and what they said is typed into the message box for them to review and send. Nothing is sent automatically, and no switch is needed — the button is hidden only while a live voice call is running. Transcription uses the AI model Perfox includes and manages, and is metered like your other AI usage.
The two voice buttons look different so visitors can tell them apart:
| Button | Icon | What it does |
|---|---|---|
| Dictate | A microphone beside lines of text | Speak, and it's typed for you to review and send. |
| Talk live (when voice chat is on) | A headset | Starts a spoken conversation with the agent; shows a close icon to end it. |
| Call me (when dial-out is on) | A phone handset | Asks the agent to ring the visitor's phone. |
Custom clients send the recording to POST /api/public/widget/transcribe (an audio file, up to 25 MB, at most 30 requests a minute from one network address) and get back { transcript }. Errors: 400 not_audio, 422 empty_transcript (nothing was heard), 503 missing_credential, 500 transcribe_failed.
Adapting your own UI to capabilities
You don't have to use the built-in widget buttons. Read the capabilities from the ready event and show or hide your own controls:
js
Perfox('on', 'ready', (info) => {
if (!info.capabilities.voice_chat) {
// hide your "Talk to me" CTA
}
});This lets you build a fully custom UI that stays in sync with what your agent actually has enabled. To drive voice from your own UI entirely, use the headless library.
What's next
You can now add voice chat and dial-out to your widget without managing audio sessions or phone infrastructure directly. To go further:
- Public Widget API — the full reference for every widget endpoint and init option.
- Events — the complete list of widget events (including
ready), so you can react to capabilities and session state in your own UI code. - File Upload — another opt-in capability that works the same way, good to set up alongside voice if your visitors share documents.