AmphiVox Widget — Vanilla JS

Quick start — drop-in

Paste these two tags into your page, just before </body>. Point target at your form, map AmphiVox field ids to your inputs, and let the widget do the rest:

<script src="https://amphivox.com/widget.js" crossorigin></script>
<script>
  VoiceForm.init({
    formId: 'YOUR_FORM_ID',
    widgetKey: 'YOUR_WIDGET_KEY',
    target: '#contact-form',
    autoSubmit: true,
    fieldMap: { full_name: 'name', email_address: 'email' },
  });
</script>

That's the whole setup: the widget injects a floating mic button, the visitor speaks, each answer is written into the matching input in #contact-form, and the form submits itself when the conversation completes.

Your formId, widgetKey, and every field id come from the form's Developers page in the AmphiVox dashboard — open a form and choose Developers (also on the dashboard card menu). It generates a ready-to-paste snippet with your real field ids already filled in. The widget key also controls which domains are allowed to embed it.

Field mapping

Inside target, the widget looks up each field in this order: the id you give in fieldMap, then a matching id attribute, then a matching name attribute.

fieldMap: {
  full_name: 'name',        // AmphiVox field "full_name" → <input id="name">
  email_address: 'email',   // AmphiVox field "email_address" → <input id="email">
}

If your input ids already match the AmphiVox field ids, you can omit fieldMap entirely. The widget handles text inputs, textareas, checkboxes, radios, and single/multi <select> — and it dispatches input/change events so React, Vue, and Angular controlled inputs update correctly.

Phone fields

Every field arrives as a string except phone, which arrives as a triple so you can fill a country selector and a number input separately:

{ e164: '+919876543210', country: 'IN', national: '9876543210' }

• e164 — the canonical, unambiguous form. Use this unless you have a reason not to.
• country — ISO 3166-1 alpha-2 (IN, US), for a country/flag control.
• national — local digits, no country code.

Map it to one input and you get the E.164 string; map it to two controls with an object entry:

fieldMap: {
  // one input → gets '+919876543210'
  phone_number: 'phone',

  // or two controls → country gets 'IN', number gets '9876543210'
  phone_number: { country: 'country_select', number: 'phone_input' },
}

In headless mode, narrow it yourself: typeof value === 'object' ? value.e164 : value.

Address fields

Prefill

If your page already knows the respondent's name, the agent shouldn't ask for it. Hand it over and the session starts with those fields filled in:

VoiceForm.init({
  formId: 'YOUR_FORM_ID',
  widgetKey: 'YOUR_WIDGET_KEY',
  target: '#contact-form',
  // Keys are AmphiVox field ids — the same namespace fieldMap maps FROM,
  // not your input ids.
  prefillData: {
    full_name: 'Asha Rao',
    receive_updates: false,
  },
});

Update it later — after a login resolves, or as the visitor types:

document.querySelector('#name').addEventListener('change', function (e) {
  VoiceForm.setPrefill({ full_name: e.target.value });
});

setPrefill replaces the whole snapshot rather than merging, so send everything you want the agent to know each time. Pass null or {} to clear it.

When it's read. At the start of the next session, whether the respondent taps the dock or you call open(). Calling it mid-session doesn't rewrite the conversation in progress.

What counts as empty. null, '' and [] are dropped; false and 0 are kept, being real answers.

Value shapes match what onField gives you, with one exception: send phone as an E.164 string ('+919876543210'), not the object.

If it's rejected. A malformed or oversized prefill payload is refused before a session is built — the connect fails and onError fires. The server's own reason (initial_state_invalid for a bad shape, initial_state_too_large past 12 KB or 256 keys) is in the failed request's response body in the network tab; the callback itself may only report a generic connect failure, so debug this one from the network panel.

Custom submit (fetch / SPA)

autoSubmit calls the form's native submit(). If you submit with fetch or manage submission in JavaScript, use onComplete instead — it overrides autoSubmit:

VoiceForm.init({
  formId: 'YOUR_FORM_ID',
  widgetKey: 'YOUR_WIDGET_KEY',
  target: '#contact-form',
  onComplete: () => {
    fetch('/api/save', { method: 'POST', body: collectFields() });
  },
});

Headless — own every write

Don't want the widget touching your DOM at all? Omit target and wire callbacks instead — you decide what happens with each answer. The mic button still appears; nothing gets written or submitted unless you do it.

VoiceForm.init({
  formId: 'YOUR_FORM_ID',
  widgetKey: 'YOUR_WIDGET_KEY',
  onReady:      () => {},                    // session is live
  onField:      (field, value) => {},        // each answer collected
  onComplete:   () => {},                    // session finished
  onTimeout:    () => {},                    // idle timeout
  onError:      (error) => {},
  onTranscript: (speaker, text) => {},       // speaker is 'user' or 'bot'
  onThinking:   (active) => {},              // agent processing
  onSpeaking:   (who, active) => {},         // who is 'user' or 'bot'
  onMuteChange: (muted) => {},
});

field in onField is the AmphiVox field id — switch on it to update your own state. value is a string for most fields, an array for multi-select, an object for phone ({ e164, country, national }) and for address (one key per component). Narrow before writing it into an input, or you'll render [object Object].

Bring your own UI

Pass hidden: true to take the built-in dock off the screen and render your own interface. The session keeps running — drive it with the control API and paint it from the callbacks:

VoiceForm.init({
  formId: 'YOUR_FORM_ID',
  widgetKey: 'YOUR_WIDGET_KEY',
  hidden: true,                                   // ← no built-in dock
  onReady:    () => setLive(true),
  onThinking: (active) => setSpinner(active),
  onSpeaking: (who, active) => { if (who === 'bot') pulse(active); },
  onComplete: () => setLive(false),
});

myButton.addEventListener('click', () => VoiceForm.open());

VoiceForm.hide() and VoiceForm.show() toggle it at runtime without disturbing a live session.

Everything you need for a convincing custom UI comes through the callbacks: onReady / onComplete / onTimeout / onError for session state, onSpeaking for who has the floor, onThinking for the processing beat, onMuteChange for mic state, and onTranscript for live captions.

What you still don't get: raw audio. onSpeaking is a boolean, not an amplitude stream, so you can animate that someone is speaking but not a true waveform driven by volume. The microphone permission prompt also comes from the AmphiVox origin, not yours.

Controls

init() returns the VoiceForm object; every control below is also available on window.VoiceForm:

window.VoiceForm is a singleton — one widget per page. Calling init() again replaces the configuration but does not give you a second independent widget; call destroy() before re-initialising. In a single-page app, call destroy() when the view that owns the widget unmounts, or the iframe and its listeners outlive the route.

Options

Callbacks

All are optional. Pass any of them to init().

Session lifecycle and idle timeout

A session has exactly four endings, and each one is a different callback — or, in one case, no callback at all:

How the idle timeout works

The agent watches for silence only when the floor is the respondent's — the clock does not run while the agent is speaking or while it is processing an answer, so a long agent turn can never be mistaken for an idle visitor.

1. ~10 seconds of silence after the agent finishes speaking → the agent nudges: it briefly acknowledges the pause and re-asks the last unanswered question out loud. This is a normal part of the conversation, not an error, and nothing is reported to your page.
2. Another ~10 seconds of silence → the session ends. The widget posts a timeout to your page and onTimeout() fires.

So a respondent who walks away loses the session after roughly 20 seconds of continuous silence, having been prompted once. Those are the current server defaults (a 10-second silence window, one nudge before ending) — treat them as approximate rather than a contract, and never build a UI that depends on the exact number.

Two things that surprise people:

• Muting is not pausing. A muted mic is indistinguishable from a silent respondent, so the idle clock keeps running and a long mute will time the session out.
• There is a hard ceiling too. Any single session is capped at 10 minutes of wall-clock time regardless of activity. That ceiling tears the session down without a timeout notice, so it surfaces as onError('session_ended_unexpectedly') rather than onTimeout().

Separately, the iframe sends a keepalive roughly once a second, and the server closes a session it hasn't heard from for ~18 seconds. This is why the frame must stay rendered — see the note in Bring your own UI.

After it ends

The widget stays on the page in every case. The next open() — or the respondent tapping the dock — starts a fresh session, re-reading whatever prefill, language and voice you last set. Answers already delivered through onField are yours and are unaffected.

Error codes

onError(error) always receives a short, stable string code — never raw provider text and never anything you should show a visitor verbatim. Write your own copy per code; keep an else branch, because the list can grow.

Connect-time — the session never started. Nothing was collected, and retrying is usually reasonable.

Mid-session — the conversation had started. Anything already delivered through onField is still valid and worth keeping.

Design notes worth knowing. Only the first error of a session is reported — a specific failure is never overwritten by the generic disconnect that follows it. Transient hiccups that the pipeline retries successfully are not reported at all, so an onError means the session is over. And a code you don't recognise is possible: treat any unknown string as a generic failure rather than assuming it is one of the above.

Languages

AmphiVox speaks 45 languages across two voice families (full list below — pull the live catalog anytime from GET /api/voice/languages if you'd rather not hardcode it). Pass the code; everything behind it is handled for you.

Worldwide — recognition listens for the selected language plus English fallback, so a visitor can code-switch to English mid-sentence and the voice follows:

Bharat — Indian languages, with automatic language detection:

There are three ways a language gets chosen:

1. Initial — the language option seeds the session: VoiceForm.init({ …, language: 'hi' }). It's bound when the session starts.
2. Programmatic — VoiceForm.setLanguage('hi') sets the language for the next session. It does not retune a call already in progress.
3. In-dock picker — the floating dock includes a language selector listing every supported language, grouped by voice family with a search box, so visitors can pick their own without any code from you.

Voice gender

The agent speaks with a female voice by default, or a male one. It works exactly like language — you seed it, the visitor can still change it:

VoiceForm.init({
  formId: 'YOUR_FORM_ID',
  widgetKey: 'YOUR_WIDGET_KEY',
  voiceGender: 'male',   // 'female' (default) | 'male'
});

VoiceForm.setVoiceGender('female') changes it for the next session, like setLanguage. Anything other than 'female' or 'male' falls back to 'female'.

The visitor can override your choice: the dock header shows a small avatar icon next to the language pill, and clicking it before the session starts swaps the voice. Once a session is live the choice locks — the avatar becomes a non-interactive presence indicator (it glows while the agent talks) instead of a button. There's no callback for their selection.

Content Security Policy

If your page sends a Content-Security-Policy header, two directives are all the widget needs:

Content-Security-Policy:
  frame-src  https://amphivox.com;
  script-src 'self' https://amphivox.com;

frame-src lets the widget's iframe load; script-src lets widget.js execute.

You do not need a connect-src entry for the widget. widget.js opens no connections from your page — it injects an iframe and talks to it over postMessage, nothing more. Every network call the voice session makes happens inside that iframe, which is a separate browsing context governed by AmphiVox's own CSP, not yours. The realtime audio itself runs over WebRTC, which CSP does not govern at all.

You do not need media-src either: the audio element lives inside the iframe.

If you self-host AmphiVox, substitute your own origin in both directives. Nothing else changes.

Troubleshooting