Elaras/

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.

AttributeTypeDescription
data-chatbot-keystringRequired. Your agent's public key.
data-api-urlURLOverride the API base URL (default https://ask-api.elaras.ai). Rarely needed.
data-primary-colorstringOverride the primary colour (hex).
data-positionbottom-right | bottom-leftOverride widget position.
data-greetingstringOverride greeting message.
data-auto-opentrueOpen the widget immediately on load.
data-inlinetrueRender inline (no bubble). Pair with data-mount-to.
data-full-pagetrueFull-page embed mode.
data-mount-toCSS selectorMount inside a specific element instead of <body>.
data-external-user-idstringTag sessions with your app's user ID. See Identity verification.
data-identity-tokenstringHMAC-SHA256 proof of the user ID. Required for verified mode.
data-session-idUUIDLoad a specific conversation directly (bypasses localStorage).
data-preview-tokenstringPreview 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>

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:

  1. Meta tag (site-wide):
    <meta name="elaras-widget-fingerprint" content="off">
  2. Window global (set before the widget script loads):
    <script>window.ELARAS_WIDGET_DISABLE_FINGERPRINT = true;</script>
  3. 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.