Embed widget

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.

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.

When to use it

Use the widget when

The conversation itself is the product. For example: support, sales, onboarding help, or a guided walkthrough of your screen.

Use the library when

You need the conversation inside your own UI. Or you need transcripts and tool calls in your app.

Install

Copy the snippet

In the dashboard, open your agent. Go to Deploy → Web Widget → Embed Code. The snippet already has your agent ID.

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

Paste it into your page

Put it anywhere in <head> or <body>. Keep defer.

Serve the page over HTTPS

Browsers only allow the microphone, camera and screen capture on secure pages. http://localhost also works for testing.

Here is a complete page:

index.html

<!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>

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.

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:

<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.

Two agents on one page

The automatic setup only runs once per page. To show two agents, add both elements yourself:

<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.

What the visitor sees

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.

A choice of mode

Voice, and Chat if text chat is on. Below them, Webcam and Share Screen if those are on.

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.

The conversation

The header shows Connecting… and then a green Active dot. The agent speaks first. The visitor can interrupt it at any time.

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.

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.

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.

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:

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. 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 lets you set them.

Common problems

The widget never connects: require_auth is on

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.

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 resamples and does not have this problem.

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.

The widget shows "Service Unavailable"

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.

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

curl -s https://app.eclatira.com/api/agent/YOUR_AGENT_ID

{
  "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:

require_auth is false.
subscription_blocked is false.
required_variables is empty, or each one has a default in variable_placeholders.
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 to get the transcript when the session ends, or use the client library.
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.

Need more control?

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.

Get started

Web sessions

Phone calls

Help

When to use it

Use the widget when

Use the library when

Install

Place the element yourself

What the visitor sees

Configuration

Features

Panel

Launcher button

How the widget handles video

Common problems

See what the widget sees

Limits

Need more control?

​When to use it

Use the widget when

Use the library when

​Install

​Place the element yourself

​What the visitor sees

​Configuration

​Features

​Panel

​Launcher button

​Turn camera or screen share on or off

​How the widget handles video

​Common problems

​See what the widget sees

​Limits

Need more control?

When to use it

Install

Place the element yourself

What the visitor sees

Configuration

Features

Panel

Launcher button

Turn camera or screen share on or off

How the widget handles video

Common problems

See what the widget sees

Limits