---
title: Widget Embed
sidebar_position: 2
---

# Widget Embed

The quickest way to add Elaras Chat to any website — one script tag, no build step, no configuration in your code.

## Installation

Add this snippet to your HTML before `</body>`:

```html
<script
  src="https://cdn.elaras.ai/widget.js"
  data-chatbot-key="cbt_your_key_here"
></script>
```

Find your chatbot key in the **Integrations** tab of your chatbot in the Elaras dashboard.

## How it works

The widget:

1. Renders inside a **Shadow DOM** so it never conflicts with your site's CSS or JavaScript.
2. Loads the chatbot config from the API (name, colours, greeting, position).
3. Opens a **WebSocket connection** for real-time streaming responses.
4. Persists the session in `localStorage` so the user's conversation history survives page reloads and navigation.

## Appearance and behaviour

All appearance and behaviour settings are configured in the Elaras dashboard — no code changes needed:

- **Name and avatar** — shown in the widget header
- **Primary colour** — button and bubble accent colour
- **Position** — bottom-right or bottom-left
- **Greeting message** — shown when the widget is first opened
- **Placeholder text** — in the message input
- **Powered by Elaras badge** — toggle on/off (Agency plan)
- **Triage questions** — optional pre-chat questions (name, email, or custom) shown before the first message

## Domain security

In your chatbot settings under **Security**, add every domain that is allowed to use the chatbot key. Requests from unlisted origins are rejected with a 401.

```
https://yoursite.com
https://app.yoursite.com
https://staging.yoursite.com
```

Use the wildcard `*` to allow all origins during local development only — never in production.

## Session persistence

Sessions are stored in `localStorage` keyed by your chatbot key:

```
elaras_session_cbt_abc123 → "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

The same key is used across page reloads, so the user always sees their full conversation history until they clear their browser storage or you call `window.ElarasChat.clearSession()`.

## JavaScript API

The widget exposes a small JavaScript API on `window.ElarasChat`:

```js
// Open the widget
window.ElarasChat.open();

// Close the widget
window.ElarasChat.close();

// Toggle open/closed
window.ElarasChat.toggle();

// Clear the current session (starts a fresh conversation)
window.ElarasChat.clearSession();

// Send a message programmatically
window.ElarasChat.send('Hello, I need help with my order.');

// Listen for events
window.ElarasChat.on('message', (msg) => {
  console.log('New message:', msg);
});

window.ElarasChat.on('lead', (lead) => {
  console.log('Lead captured:', lead.email);
});
```

## Events

| Event | Payload | Description |
|---|---|---|
| `open` | — | Widget opened |
| `close` | — | Widget closed |
| `message` | `{ role, content }` | New message (user or AI) |
| `lead` | `{ email, name }` | Lead email captured |
| `ready` | — | Widget fully loaded and connected |

## Content Security Policy

If you use a CSP, add these directives:

```
script-src 'self' https://cdn.elaras.ai;
connect-src 'self' https://api.elaras.ai wss://ws.elaras.ai;
```