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

# Install a voice orb

> Add a browser voice conversation as a floating orb or inside a page section.

A **Floating orb** lets a website visitor start a voice conversation with an assistant in the browser.

## Before you begin

Have an assistant with a published voice agent and access to edit the website's HTML or custom-code section. Publish the page over HTTPS and allow microphone permission; [browser microphone access requires a secure context](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#privacy_and_security). A phone number is not required solely to start this browser conversation; phone calling and transfer tasks can have their own requirements.

## Create and install the orb

1. Open **Widgets** in the assistant's account.
2. Select **Create widget**.
3. Choose **Floating orb**.
4. Enter a name for the widget.
5. Select **Create widget**.
6. Select the assistant that should answer.
7. Set the orb's appearance, including its color and icon.
8. Select **Save changes**.
9. Select **Get Code**.
10. Copy the generated script into the website's custom-code or HTML area.
11. Publish the website.

Keep the generated script URL, assistant ID, and account ID together. If you change the assistant or settings included in the script, copy the updated code into the website.

## Orb settings

The orb editor offers **AI Model** (the assistant selector), **Icon**, and **Color**. Choose an assistant from the current account, an icon from the icon picker, and a color. The generated snippet includes the assistant and account IDs plus the icon, color, theme, and orb size. Copy fresh code after changing settings; the snippet carries those values to your website.

The default generated orb is 90 pixels across. Placement inside a page section uses the optional `data-container` attribute described below; it does not change the assistant assignment.

## Test on the published website

1. Open the published page in a browser.
2. Select the orb.
3. Allow microphone access when prompted.
4. Speak a short request.
5. Confirm the expected assistant responds with audible speech.
6. End the conversation.

Repeat on the device types your visitors use. A visible orb confirms the embed loaded; hearing and completing a conversation confirms the voice path works.

## Optional: place the orb inside a section

The orb floats over the page by default. To place it inside a section, add this container before your generated script:

```html theme={null}
<div id="voice-orb-slot"
     style="position: relative; min-height: 200px;"></div>
```

Add `data-container="voice-orb-slot"` to the opening script tag in your generated code. Keep its existing URL and account/assistant attributes. The container ID and `data-container` value must match, and the container must exist before the script runs.

Publish the page and confirm the orb stays within that section at both desktop and mobile widths.

## Troubleshooting

| Symptom | Check |
| - | - |
| Orb does not appear | The page is published, the script is present, and the site builder allows it to load. |
| Orb is outside the intended section | Matching container ID, script order, relative positioning, and sufficient container height. |
| Voice cannot start | The page is served over HTTPS, the selected assistant has a published voice agent, and browser microphone access is allowed. If the site embeds the page in an iframe, its permissions must allow microphone access. |
| Wrong assistant answers | The assistant/account IDs in the installed script; copy fresh code from the saved widget. |
| Voice works but a task fails | The assistant's prompt and tool configuration; test that task separately. |

For a widget that combines text and voice, see [Voice-enabled chat widget](/v3/voice-enabled-chat-widget).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.