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

# Embed widget

> Add a voice, camera and screen-share agent to any website with two script tags. No backend and no API key needed.

The embed widget is the fastest way to put an agent on your site. You paste two script tags. A button appears in the corner of the page. Visitors click it and talk to the agent.

The widget handles all the audio and video work for you. Voice, webcam and screen share work with no extra code.

<Note>
  The widget does not use your API key. The agent ID in the snippet is public. Never put an `ek_` key on a web page.
</Note>

## When to use it

<CardGroup cols={2}>
  <Card title="Use the widget when" icon="check">
    The conversation itself is the product. For example: support, sales, onboarding help, or a guided walkthrough of your screen.
  </Card>

  <Card title="Use the library when" icon="arrow-right" href="/realtime/browser-voice">
    You need the conversation inside your own UI. Or you need transcripts and tool calls in your app.
  </Card>
</CardGroup>

## Install

<Steps>
  <Step title="Copy the snippet">
    In the dashboard, open your agent. Go to **Deploy → Web Widget → Embed Code**. The snippet already has your agent ID.

    ```html theme={"system"}
    <script>
      window.eclatiraSettings = {
        widget_id: "YOUR_AGENT_ID",
      };
    </script>
    <script src="https://app.eclatira.com/widget.js" defer></script>
    ```
  </Step>

  <Step title="Paste it into your page">
    Put it anywhere in `<head>` or `<body>`. Keep `defer`.
  </Step>

  <Step title="Serve the page over HTTPS">
    Browsers only allow the microphone, camera and screen capture on secure pages. `http://localhost` also works for testing.
  </Step>
</Steps>

Here is a complete page:

```html index.html theme={"system"}
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Acme Support</title>
  </head>
  <body>
    <h1>Acme Support</h1>
    <p>Click the button in the corner to talk to our agent.</p>

    <script>
      window.eclatiraSettings = {
        widget_id: "YOUR_AGENT_ID",
      };
    </script>
    <script src="https://app.eclatira.com/widget.js" defer></script>
  </body>
</html>
```

<Warning>
  Load `widget.js` with a normal `<script src>` tag. Do not copy its code inline, and do not use `type="module"`. The script finds its own URL when it runs. If it cannot, it stops and no button appears.
</Warning>

### Place the element yourself

The snippet above creates an `<eclatira-widget>` element for you. You can also write the element yourself. Put the agent ID in the `agent-id` attribute:

```html theme={"system"}
<eclatira-widget agent-id="YOUR_AGENT_ID"></eclatira-widget>
<script src="https://app.eclatira.com/widget.js" defer></script>
```

The widget always shows in a fixed corner of the screen. Where you put the tag in the HTML does not change its position.

<Accordion title="Two agents on one page">
  The automatic setup only runs once per page. To show two agents, add both elements yourself:

  ```html theme={"system"}
  <eclatira-widget agent-id="SALES_AGENT_ID"></eclatira-widget>
  <eclatira-widget agent-id="SUPPORT_AGENT_ID"></eclatira-widget>
  <script src="https://app.eclatira.com/widget.js" defer></script>
  ```

  By default, both buttons sit 24 px from the bottom-right corner, on top of each other. Give one of the agents a different `position_bottom` or `position_right`.
</Accordion>

## What the visitor sees

<Steps>
  <Step title="A consent screen">
    The panel first shows a Terms and Data Notice. The visitor must accept it. The browser remembers the choice, so a returning visitor sees it only once. You cannot turn this off.
  </Step>

  <Step title="A choice of mode">
    **Voice**, and **Chat** if text chat is on. Below them, **Webcam** and **Share Screen** if those are on.
  </Step>

  <Step title="The browser's permission prompt">
    The browser asks for the microphone. Webcam also asks for the camera. Share Screen opens the browser's screen picker, then asks for the microphone.
  </Step>

  <Step title="The conversation">
    The header shows **Connecting…** and then a green **Active** dot. The agent speaks first. The visitor can interrupt it at any time.
  </Step>
</Steps>

<Tip>
  If the agent's instructions or first message use a `{{variable}}`, give it a default value. Otherwise the widget shows a form asking the visitor to fill it in before the conversation starts.
</Tip>

## Configuration

All settings live on the **agent**, not on the page. The snippet only carries the agent ID. When you change a setting, every page that embeds the agent updates on the next load.

Change settings in the dashboard under **Deploy → Web Widget**.

### Features

| Setting | Default | What it does |
| - | - | - |
| `enable_webcam` | `true` | Shows **Webcam**. Also allows `camera` sessions through the API. |
| `enable_screen_share` | `true` | Shows **Share Screen**. Also allows `screen` sessions through the API. |
| `enable_text_chat` | `true` | Shows **Chat**. When off, the widget is voice only. |

### Panel

| Setting | Default | What it does |
| - | - | - |
| `theme` | `light` | `light` or `dark`. |
| `primary_color` | `#000000` | Accent color for the avatar, buttons and icons. |
| `header_text` | Agent name | Title in the panel header. Falls back to "Chat Support" if the agent has no name. |
| `hide_footer` | `false` | Hides "Powered By Eclatira". Only works on plans that include it. |
| `panel_width` | `400` | Panel width in px. |
| `panel_height` | `620` | Panel height in px. |

### Launcher button

| Setting | Default | What it does |
| - | - | - |
| `button_color` | `#000000` | Button background color. |
| `button_size` | `56` | Button width and height in px. |
| `widget_icon_url` | Speech bubble | Image shown inside the button. |
| `position_bottom` | `24` | Distance from the bottom of the screen in px. |
| `position_right` | `24` | Distance from the right of the screen in px. |

On screens 480 px wide or less, the widget uses its own sizes. The button moves to 16 px from the corner, and the panel fills most of the screen.

<Note>
  If you change plans and your new plan does not include `hide_footer`, the footer comes back right away. Your saved setting does not change.
</Note>

### Turn camera or screen share on or off

`enable_webcam` and `enable_screen_share` control the widget **and** the API. When one is off, the widget hides the button, and the API refuses that session type. You can change them through the API:

```bash theme={"system"}
curl -X PATCH https://app.eclatira.com/api/v1/agents/YOUR_AGENT_ID \
  -H "Authorization: Bearer ek_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"realtime": {"enable_screen_share": false}}'
```

Only the flags you send change. All other widget settings stay the same.

## How the widget handles video

The widget sends one image every second. Each image is a JPEG at quality 0.8, scaled so its longest side is at most 1024 px. If the connection is slow, the widget skips images so the audio is not held up. The server passes at most one image per second to the agent, and always the newest one.

You cannot change these values in the widget. The [client library](/realtime/browser-voice) lets you set them.

## Common problems

<AccordionGroup>
  <Accordion title="The widget never connects: require_auth is on">
    An agent with `require_auth` on only accepts logged-in dashboard users. Visitors on your site are not logged in, so the connection closes with "Authentication required for this agent". Turn `require_auth` off for any agent you embed.
  </Accordion>

  <Accordion title="Origin not allowed">
    The agent's `allowed_origins` list is checked against the site the widget is embedded in. The widget then shows "This assistant isn't available on this website." Add the site's domain to the list. An entry also covers its subdomains, so `example.com` allows `www.example.com`. An empty list allows every site.

    The list stops other sites from reusing your widget. It is not authentication: a client that does not run in a browser can claim to be any site.
  </Accordion>

  <Accordion title="The agent never replies on some browsers">
    The widget asks the browser for 16 kHz audio and does not resample. Chrome and other Chromium browsers honor this. Some other browsers use the hardware rate instead. The audio then arrives at the wrong speed, and the agent never hears the visitor. No error appears.

    Test the widget on the browsers your visitors use. The [client library](/realtime/browser-voice) resamples and does not have this problem.
  </Accordion>

  <Accordion title="Screen share without a microphone">
    If the visitor shares their screen but blocks the microphone, the session starts with video only. The agent cannot reply to video alone. After about 8 seconds of images, the server sends a `no_audio_received` error, and the widget shows it.
  </Accordion>

  <Accordion title="&#x22;Stop sharing&#x22; does not end the session">
    If the visitor clicks the browser's own **Stop sharing** bar, the images stop, but the session keeps running and keeps using credits. The visitor must click **End session** in the panel or close the tab.
  </Accordion>

  <Accordion title="Minimizing does not end the session">
    **Minimize** only hides the panel. The conversation keeps running and the agent's audio keeps playing. Only **End session** or leaving the page ends it.
  </Accordion>

  <Accordion title="The widget shows &#x22;Service Unavailable&#x22;">
    The workspace's subscription is past due or unpaid. No session can start until billing is fixed.
  </Accordion>

  <Accordion title="The button uses default colors">
    The widget could not load the agent's settings. The usual causes are a wrong agent ID, a deleted agent, or a network error. The button still shows, but the panel will fail to connect.
  </Accordion>
</AccordionGroup>

### See what the widget sees

The widget loads its settings from a public endpoint. Call it yourself to check them:

```bash theme={"system"}
curl -s https://app.eclatira.com/api/agent/YOUR_AGENT_ID
```

```json theme={"system"}
{
  "name": "Acme Support",
  "first_message": "Hi, how can I help?",
  "require_auth": false,
  "widget_config": {
    "enable_webcam": true,
    "enable_screen_share": true,
    "enable_text_chat": true,
    "theme": "light",
    "hide_footer": false
  },
  "subscription_blocked": false,
  "variable_placeholders": {},
  "required_variables": []
}
```

Check four things:

1. `require_auth` is `false`.
2. `subscription_blocked` is `false`.
3. `required_variables` is empty, or each one has a default in `variable_placeholders`.
4. `widget_config` has the features you expect.

## Limits

* **Styling.** You can only change the settings listed above. Your page's CSS cannot reach the widget.
* **No conversation data on your page.** Your page cannot read transcripts or tool calls from the widget. There is no JavaScript API. Use a [webhook](/webhooks) to get the transcript when the session ends, or use the [client library](/realtime/browser-voice).
* **HTTPS only.** The microphone, camera and screen share do not work on plain HTTP pages, except `localhost`.
* **Messages from other frames.** The button accepts color and minimize messages from any frame on your page. Other frames can recolor or collapse it. They cannot start, read or end a session.
* **Consent screen.** The consent text and legal links are Eclatira's and cannot be changed.

<Card title="Need more control?" icon="arrow-right" href="/realtime/browser-voice">
  Move to the client library. It does the same audio and video work, lets you build your own UI, and gives you every transcript and tool call as an event.
</Card>


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