Voice widget - Lovi AI Documentation

The voice widget is a floating control on your site. Visitors start a spoken call in the browser: Lovi’s iframe asks for the microphone and the AI Agent replies with audio. Do not confuse it with:

The web chat widget (text bubble; same script without mode="voice").
Phone calls to a Twilio or Ringover number.
Voice campaigns (POST /functions/v1/notify/voice).

Production embed is https://widget.lovi.ai/iawidget.js with mode="voice". The GitHub repo voice-widget-lovi is an older prototype (no Lovi iframe, keys in the page). Do not copy that.

How to embed it

Paste this before </body>. mode="voice" is what loads voice instead of text chat:

<script
  customer="YOUR_ACCESS_KEY"
  widget="YOUR_WIDGET_ID"
  mode="voice"
  src="https://widget.lovi.ai/iawidget.js"
  defer
></script>

Attribute	Required	What it is
`src`	Yes	`https://widget.lovi.ai/iawidget.js`
`customer`	Yes	Company access key (the script sends it as `access_key`). Not the widget UUID.
`widget`	Yes	Widget UUID.
`mode`	Yes	Must be `voice`. Without it, the same script loads text chat.
`language-lovi`	No	Language (`es`, `en`, …). If omitted, `navigator.language` (two letters). Do not use `language="en"`.

Loader order: mode="voice" first, then WhatsApp full, then chat. If both mode="voice" and WhatsApp full are set, voice loads. There is no dom embed for voice: the iframe is position:fixed; bottom:0; left or right. Chat dom / config WhatsApp-on-mobile do not apply to this iframe. No public npm package and no window.startVoice. The visitor taps the control.

What the visitor sees

The voice control appears (fixed to the corner).
On a real click, the browser asks for the microphone (getUserMedia inside Lovi’s iframe, including voiceIsolation where supported).
They hear the agent and can hang up.
After hang-up they can leave 👍/👎 feedback.

Test on HTTPS or localhost. The mic does not work on plain HTTP. If your page wraps the widget in a cross-origin iframe, that host iframe needs allow="microphone" and, where you use Permissions-Policy, allow microphone toward https://widget.lovi.ai. Lovi’s own iframe already sets allow="microphone; autoplay".

Appearance

Colours, position, and animation come from GET /functions/v1/voice-widget (Voice-config). They are not set in your HTML except language-lovi.

Audio and handoff (what the iframe does)

You do not call these from the host page. The iframe does:

GET …/functions/v1/voice-widget — appearance (Voice-config) only. Not the live audio session.
GET …/functions/v1/voice-widget/signed-url — ElevenLabs ConvAI session (signed URL + SDK; WebSocket and/or WebRTC).
Also used internally: POST …/voice-widget/search, feedback, POST …/voice-widget/handoff, POST …/voice-widget/handoff/end, GET …/voice-widget/chat-by-conversation.

There is a transfer-to-human path in the voice iframe (states such as transferring / waiting_agent / with_human, LiveKit). That is not a public API for your site’s JavaScript.

Technical requirements (host page)

The host must reach at least:

https://widget.lovi.ai
https://cloud.lovi.ai
https://api.elevenlabs.io and wss://api.elevenlabs.io
wss://livekit.rtc.elevenlabs.io
https://cloud-api.livekit.io
https://cdn.jsdelivr.net (AudioWorklet)

Neither iawidget.js nor widget.lovi.ai send a Content-Security-Policy header. This list is for your CSP / firewall / tag manager.

Troubleshooting

Problem	What to check
Nothing appears	Network: `iawidget.js` 200. Ad blockers.
Console: `LOVI ERROR (voz): customer/widget no definidos`	Empty `customer` or `widget`. `customer` is the access key.
Chat bubble instead of voice	`mode="voice"` missing.
Microphone does not start	HTTPS/`localhost`, real click, mic permission, `allow="microphone"` on your wrapping iframe, Permissions-Policy to `widget.lovi.ai`.
Script / audio / WebRTC blocked	Allowlist the hosts above, including `wss:` LiveKit and ElevenLabs.

Web Widget Configuration — text chat (omit mode).
Phone numbers and voice AI — calls to your company number.
Voice widget API — endpoints the iframe uses.
Voice notifications API — outbound phone campaigns.

​How to embed it

​What the visitor sees

​Appearance

​Audio and handoff (what the iframe does)

​Technical requirements (host page)

​Troubleshooting

​Related