LiveChat widget

One tag on your page mounts the launcher, the panel and a live conversation. No configuration object, no origin repeated anywhere — the widget takes its API origin from the script’s own src:

<script async src="https://chat.your-domain/widget.js" data-widget-key="default"></script>

The widget renders inside a Shadow DOM (isolated from your CSS in both directions), works under a Content-Security-Policy without 'unsafe-inline', and is lazy: nothing is sent and no socket is opened until the visitor actually opens the panel.

Allow your site’s origin — the one required setup step

Allowed origins live on the widget, not in configuration: in the console under Administration → Widgets, add your site’s origin — scheme and host only, no path, no trailing slash:

https://shop.example

An entry that does not match exactly means the widget silently never loads on that page. Onboarding another site is editing the widget, not redeploying.

Handing over your signed-in user

If the visitor is signed in to your site, tell the console who they are. Three channels; all carry the same three fields (externalId, displayName, email) and merge the same way.

Attributes on the embed tag:

<script async src="https://chat.your-domain/widget.js" data-widget-key="default"
        data-user-id="crm-4471" data-user-name="Ayse Yilmaz" data-user-email="ayse@example.com"></script>

Meta tags — for server-rendered pages whose layout emits a <head> tag per signed-in user more easily than it can edit a script tag a CMS plugin owns:

<meta name="flowdesk-user-id" content="crm-4471">
<meta name="flowdesk-user-name" content="Ayse Yilmaz">
<meta name="flowdesk-user-email" content="ayse@example.com">

The JS API — for single-page apps, callable whenever your session state changes:

window.FlowDeskChat?.identify({
  displayName: 'Ayse Yilmaz',
  email: 'ayse@example.com',
  externalId: 'crm-4471',
});

When a user id is declared, the widget also sends it as the X-FlowDesk-User-Id request header on its very first request (the visitor mint), so the visitor’s record is created already labelled. The agent sees the name, the email and the customer id on the conversation’s visitor panel.

Calls merge: a field you leave off is left alone, an explicit '' clears it, and an empty declared attribute counts as not declared — it never wipes a value stored on a previous page view.

Display-only, never identity

Any script on the page can call identify(), so LiveChat never uses these values as a lookup key: they are written onto the visitor’s own record and shown to the agent, nothing more. externalId is a label for your agents to find the customer in your system — not a link between a chat visitor and an account. Do not send anything you would not be comfortable with an arbitrary script on the page setting.

Field limits

Field	Limit
displayName	200 characters
email	320 characters, must be a valid address
externalId	200 characters (an over-long value is dropped, never truncated)

Try it

A live demo of the widget on a pretend customer site: widget-demo.demo.flowdesk.club — the conversation lands in the demo console in real time.

The full integrator reference — hosted chat page mode, CSP details, browser support, troubleshooting — lives in the product repository: docs/WIDGET.md.