> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice widget

> Embed a voice call with your AI Agent on your website. Visitors tap the voice control, allow the microphone, and talk in the browser.

The **voice widget** is a floating control on your site. Visitors start a **spoken call** in the browser: the page asks for the microphone and the AI Agent replies with audio.

Do not confuse it with:

* The [web chat widget](./ug_webwidget_en) (text message bubble).
* [Phone calls](./voice-config) to a Twilio or Ringover number.
* [Voice campaigns](/en/api-reference/voice_notifications) (`POST /functions/v1/notify/voice`).

In this flow the visitor talks to the AI on the page. The capsule does not transfer the call to a human agent.

## How to embed it

Paste this before `</body>` on the pages where you want the control (or in your main `index.html` for the whole site). `mode="voice"` is what loads voice instead of text chat:

```html theme={null}
<script
  customer="YOUR_COMPANY_ID"
  widget="YOUR_WIDGET_ID"
  mode="voice"
  src="https://widget.lovi.ai/iawidget.js"
  defer
></script>
```

| Attribute                           | Required | What it is                                                                                               |
| ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `customer`                          | Yes      | Your company ID.                                                                                         |
| `widget`                            | Yes      | The widget ID.                                                                                           |
| `mode`                              | Yes      | Must be `voice`. Without it, the same script loads text chat.                                            |
| `src`                               | Yes      | `https://widget.lovi.ai/iawidget.js`                                                                     |
| `language-lovi`                     | No       | Language code (`es`, `en`, …). If omitted, the browser language is used.                                 |
| `dom`                               | No       | A node selector if you embed the iframe in a page element.                                               |
| `whatsapp_type` / `whatsapp_number` | No       | If `whatsapp_type` is `full` and a number is set, WhatsApp opens and the **voice widget does not load**. |

Copy `customer` and `widget` from the widget settings in Lovi (same values as the chat script). There is no public npm package and no public JavaScript API (`window.startVoice`, and so on): the visitor taps the control.

## What the visitor sees

1. The voice control appears on the page.
2. On tap (it must be a real click: audio does not start on its own), the browser asks for the microphone.
3. During the call they hear the agent and can hang up.
4. After hang-up they can leave 👍/👎 feedback. The control returns to idle.

Test on **HTTPS** or `localhost`. The microphone does not work on plain HTTP.

## Appearance

Colours, position, conversation animation, background image, and extra CSS come from Lovi when the widget loads. They are not set in your HTML, except `language-lovi` and `dom`.

## Technical requirements

* Modern browsers (not Internet Explorer 11).
* Microphone permission.
* Audio starts on the user click (browser autoplay policy).
* The page must be able to call `https://widget.lovi.ai`, `https://cloud.lovi.ai`, and `https://api.elevenlabs.io`.

## Troubleshooting

| Problem                                                   | What to check                                                                                                                                        |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing appears                                           | The script loaded? In DevTools → Network, `iawidget.js` should return 200. Ad blockers and privacy extensions often block it — try a private window. |
| Console: `LOVI ERROR (voz): customer/widget no definidos` | `customer` and `widget` are missing or empty. Copy them from the widget settings in Lovi.                                                            |
| Chat bubble instead of voice                              | `mode="voice"` is missing. Without it, the same script loads text chat.                                                                              |
| Microphone does not start                                 | The page must be **HTTPS** or `localhost`. Allow the mic in the browser (lock icon in the address bar). Audio only starts after a real click.        |
| Widget inside *your* iframe                               | Cross-origin iframes block the mic unless the host iframe has `allow="microphone"`. Lovi’s own iframe already sets `allow="microphone; autoplay"`.   |
| Script or audio blocked                                   | Allowlist `widget.lovi.ai`, `cloud.lovi.ai`, and `api.elevenlabs.io` in CSP, firewall, or tag manager.                                               |

## Related

* [Web Widget Configuration](./ug_webwidget_en) — text chat.
* [Phone numbers and voice AI](./voice-config) — calls to your company number.
* [Voice widget API](/en/api-reference/voice_widget) — how the script loads configuration.
* [Voice notifications API](/en/api-reference/voice_notifications) — outbound phone campaigns.