Widget
The quickest way to embed an agent on 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://ask-api.elaras.ai/widget.js" data-chatbot-key="cbt_your_key_here" async> </script>
Find your agent key in the Embed tab of your agent in the Elaras dashboard — the full snippet with your key is ready to copy from there.
How it works
The widget runs inside a Shadow DOM so it never conflicts with your site's CSS or JavaScript. It loads the agent config from the API, opens a real-time connection for streaming replies, and persists the visitor's session in localStorage so their conversation 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
- Theme — light, dark, or auto (follows the visitor's system preference)
- Greeting message — shown when the widget is first opened
- Bubble text — optional label shown next to the chat bubble
- Powered by Elaras badge — toggle on/off (white-label plan)
- Triage questions — optional pre-chat questions shown before the first message
Domain security
In your agent settings under Security, add every domain that is allowed to use the agent key. Requests from unlisted origins are rejected.
https://yoursite.com https://app.yoursite.com https://staging.yoursite.com
Always set this before going live — without it, anyone who finds your agent key can embed it on their own site and use your credits.
Session persistence
Sessions are stored in localStorage keyed by your agent key. The same key is used across page reloads, so the visitor always sees their full conversation history until they clear browser storage. If you need a fresh conversation programmatically, call the dashboard's Reset button or clear the localStorage entry.
Script tag attributes
All configuration is passed as data-* attributes on the <script> tag.
| Attribute | Type | Description |
|---|---|---|
data-chatbot-key | string | Required. Your agent's public key. |
data-api-url | URL | Override the API base URL (default https://ask-api.elaras.ai). Rarely needed. |
data-primary-color | string | Override the primary colour (hex). |
data-position | bottom-right | bottom-left | Override widget position. |
data-greeting | string | Override greeting message. |
data-auto-open | true | Open the widget immediately on load. |
data-inline | true | Render inline (no bubble). Pair with data-mount-to. |
data-full-page | true | Full-page embed mode. |
data-mount-to | CSS selector | Mount inside a specific element instead of <body>. |
data-external-user-id | string | Tag sessions with your app's user ID. See Identity verification. |
data-identity-token | string | HMAC-SHA256 proof of the user ID. Required for verified mode. |
data-session-id | UUID | Load a specific conversation directly (bypasses localStorage). |
data-preview-token | string | Preview mode token — generated by the Elaras dashboard only. |
Identity verification
When the widget is embedded inside an authenticated app, you can tag each chat session with your own user identity and later query all sessions for a given user via the Developer API.
Basic tagging (unverified)
Pass data-external-user-id with the current user's ID. This tags new sessions so you can list them later — but anyone can set this attribute to any value, so use this mode only when session tagging is enough and the conversation itself isn't sensitive.
<script src="https://ask-api.elaras.ai/widget.js" data-chatbot-key="cbt_..." data-external-user-id="user_123"> </script>
Verified mode (recommended for production)
Generate a signed token on your backend and pass both attributes. The Elaras backend verifies the HMAC before binding the session to the user ID — a spoofed or missing token causes the session to be created anonymously instead.
Step 1 — fetch your identity secret.
Call GET /api/v1/chatbots/{chatbot_id} as an authenticated team admin — the response's data.identity_secret field contains a 64-char hex secret. Store it as a server-side environment variable — never expose it client-side. (A dashboard surface for this is on the way; today it's API-only.)
Step 2 — generate the token on your backend.
// Node.js import crypto from 'crypto'; const token = crypto .createHmac('sha256', process.env.ELARAS_IDENTITY_SECRET) .update(userId) .digest('hex');
// PHP $token = hash_hmac('sha256', $userId, getenv('ELARAS_IDENTITY_SECRET'));
Step 3 — render the widget with both attributes.
<script src="https://ask-api.elaras.ai/widget.js" data-chatbot-key="cbt_..." data-external-user-id="<?= htmlspecialchars($userId) ?>" data-identity-token="<?= htmlspecialchars($token) ?>"> </script>
Loading a specific conversation
When the user picks a past conversation from your own inbox UI, re-render the widget with the session ID to load it directly:
<script src="https://ask-api.elaras.ai/widget.js" data-chatbot-key="cbt_..." data-external-user-id="user_123" data-identity-token="..." data-session-id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"> </script>
data-session-id bypasses localStorage entirely — useful for server-rendered apps that control which session is active.
Rich content
Skills can return structured content blocks (buttons, forms, cards, carousels, slot pickers) alongside the plain-text reply — the widget renders them inline as native UI the visitor can interact with. Blocks and custom renderers are documented in full on the Blocks page.
Fingerprint opt-out
The widget generates a lightweight browser fingerprint used for per-visitor rate limiting. To disable it for GDPR / CCPA compliance, use one of these opt-out mechanisms — the first match wins:
- Meta tag (site-wide):
<meta name="elaras-widget-fingerprint" content="off"> - Window global (set before the widget script loads):
<script>window.ELARAS_WIDGET_DISABLE_FINGERPRINT = true;</script> - localStorage (per-user, set from your own privacy controls):
localStorage.setItem('elaras_fp_optout', '1');
When opted out, the visitor is rate-limited by IP instead.
Content Security Policy
If you use a CSP, allow the Elaras API host for both script loading and runtime fetches / WebSocket:
script-src 'self' https://ask-api.elaras.ai; connect-src 'self' https://ask-api.elaras.ai wss://ws-p.elaras.ai;
The widget streams real-time replies over a separate WebSocket host (ws-p.elaras.ai), so your connect-src must list both. If you override data-api-url, update script-src to match.
