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

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

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

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;