Widget Setup

Embed the Luran chat widget with one snippet.

You provide two things — your tenant ID and a public API key — and the widget loads on your site, styled with the settings from your dashboard. This guide covers installation, what you can configure, how the widget connects, and how to verify it before going live.

Install

Add the widget to your website

1

Get a public API key

In Settings → API Keys, copy a public key that starts with pk_live_. The widget runs in the browser, so it must use a public key.

2

Copy your install snippet

Open Dashboard → Widget → Install. The snippet already includes your tenant ID; paste your public key where shown.

3

Paste it before the closing body tag

Add the snippet just before </body> on every page where the widget should appear.

<!-- Luran Widget Integration --> <script> window.luranSettings = { tenantId: 'YOUR_TENANT_UUID', apiKey: 'YOUR_PUBLIC_API_KEY' // starts with pk_live_ }; </script> <script src="https://cdn.luranai.com/widget/v1/widget.js" async defer></script> <!-- End Luran Widget -->
Use a public key only. The snippet runs in the browser, so it must use a public key (pk_live_…). Never put a secret key (sk_live_…) in website code — secret keys are for server-to-server calls. If a secret key is ever exposed, rotate it from the API Keys page.
Customize

Configure appearance from the dashboard

The snippet only carries your tenant ID and public key. Everything about how the widget looks and behaves is configured in Dashboard → Widget and fetched when the widget loads — change it there and republish, no code change needed.

  • Colors — primary (default #2563eb) and accent (default #10b981).
  • Logo — shown in the chat header.
  • Greeting — default "Hi! How can we help you today?".
  • Position — bottom-right (default), bottom-left, top-right, or top-left.
  • Unread badge — show or hide the unread-message count.
  • File upload — allow or block uploads in chat.
  • Pre-chat capture — optionally collect a name and/or email before chat starts (from your AI config).
How It Connects

For developers

On load

The widget calls GET /api/v1/widget/public/config/{tenant_id} with the header X-API-Key: <your pk_live_ key> and renders using the returned settings. It starts an anonymous visitor session via POST /api/v1/public/visitor/bootstrap. Conversations appear in your dashboard inbox.

Browser events (optional)

The widget emits postMessage events you can listen for: luran:ready, luran:conversationStarted, luran:conversationEnded, and luran:close.

Public config response fields: tenant_id, company_name, company_description, primary_color, accent_color, logo_url, greeting_message, position, show_unread_badge, allow_file_upload, collect_name_before_chat, collect_email_before_chat
Before Install

What to set up first

1

Upload knowledge

Make sure the knowledge base reflects the actual information the AI should use in customer conversations.

2

Set escalation behavior

Decide how human handoff should work before the widget goes live.

3

Test automation and flows

If the widget depends on actions or flows, validate them first so the live widget is not the first real test.

After Install

What to verify immediately

  • The widget loads on the intended pages.
  • The first message is on-brand and understandable.
  • New chat sessions appear correctly in the dashboard.
  • Escalation routes work.
  • Knowledge answers are grounded.
  • Automation-backed requests behave as expected.
Troubleshooting

Widget not appearing?

  • Confirm the tenantId is your tenant UUID (not the company name).
  • Confirm the key is a public pk_live_ key, and that it belongs to this tenant.
  • The config endpoint returns 401 for a bad or missing key, 403 if the key does not match the tenant, and 404 if the tenant is not found.
  • Appearance not updating? Re-check the Widget settings were saved — the widget reads config at load.
Go Live

A simple launch checklist

  • Knowledge base reviewed
  • AI tone and escalation settings reviewed
  • Public API key in place (pk_live_), secret key never exposed
  • Automation and flows tested where used
  • Widget appearance reviewed on desktop and mobile