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://cdn.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 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 (Agency 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.

Rich content blocks

Skills can return structured content blocks alongside the plain-text reply. The widget renders each block as a native UI element — buttons, forms, and cards the visitor can interact with directly.

Available block types:

Type	Renders
`elaras.card`	Content card with title, body, image, and actions
`elaras.carousel`	Horizontal carousel of cards
`elaras.button_group`	Row of buttons that send a preset message when clicked
`elaras.choices`	Single- or multi-choice question
`elaras.form`	Inline form for collecting structured input
`elaras.banner`	Info / warning / success banner
`elaras.rating`	Star or thumbs rating input
`elaras.stat`	Formatted metric display
`elaras.slots`	Time-slot picker for booking flows

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.