The widget JavaScript API

Control the chat from your own code — open it, identify users, track events and embed help.

Published 6/24/2026Updated 9/9/2026

Live Chat Widget

Control the chat from your own code — open it, identify users, track events and embed help.

One global lunadesk(...) functionAvailable once the widget script is on your page

Once the widget script is on your page (see Install the live chat widget), it exposes a global lunadesk(...) function you can call from your own code.

Configuration

Set options before the script loads:

HTMLbefore the widget script

<script>
  window.lunadeskSettings = {
    widgetKey: 'lw_YOUR_KEY',
    launcher: true, // set false to hide the button (help-center-only embeds)
  };
</script>

Core methods

JSboot · open · close · shutdown

lunadesk('boot', { jwt: 'JWT_FROM_YOUR_SERVER' }); // start / identify a visitor
lunadesk('open');      // open the chat panel
lunadesk('close');     // close it
lunadesk('shutdown');  // remove the widget and clear the session (call on logout)

boot also accepts email, name and customAttributes for visitors you don't verify with a token. To identify logged-in users securely, see Identify logged-in visitors.

Track custom events

Send product events from your site so agents see what a visitor did before reaching out:

JStrack

lunadesk('track', 'added_to_cart', { sku: 'ABC-123', value: 49.0 });

JSon

lunadesk('on', 'ready',  (visitor) => { /* booted */ });
lunadesk('on', 'opened', () => {});
lunadesk('on', 'closed', () => {});
lunadesk('on', 'error',  (err) => {});

Contextual help

Open the help center to a specific page or article from any element:

JSopenHelp · openArticle

lunadesk('openHelp', '/');                 // help home
lunadesk('openArticle', 'how-to-return');  // a specific article

Or do it declaratively, with no JavaScript — any element with these attributes works, even ones added after load:

HTMLdata attributes

<button data-lunadesk-help="/shipping">Shipping help</button>
<a data-lunadesk-article="how-to-return">How returns work</a>

Embed the help center inline

Mount your published help center inside a container on your own page:

JShelpCenter

lunadesk('helpCenter', '#help', { urlSync: true });

·Own height — the embed follows its own height.
·Deep links — supported inside the embed.
·urlSync — when on, the embed reports the page back to the host URL.

See Publish your help center: URL or JavaScript embed for the embed key option.

Control the embed from your code

Send every inline embed on the page back to its home view — handy when the visitor closes a modal, switches tabs, or you want a clean starting point:

JSresetHelp

lunadesk('resetHelp'); // all inline embeds → home (/), in place

✓

resetHelp differs from openHelp('/'). It only touches help centers already embedded on the page and never opens a new tab, so it's a safe "go home" for the embed.

For finer control, keep the handle helpCenter(...) returns and drive that one embed directly:

JSembed handle

const help = window.lunadesk.helpCenter('#help');
help.navigate('/articles/how-to-return'); // move it to any page
help.destroy();                           // remove it

One function, full control

Boot, open, track and embed — all through lunadesk(...) from your own code.

Was this article helpful?

The widget JavaScript API

Configuration

Core methods

Track custom events

Listen for widget events

Contextual help

Embed the help center inline

Control the embed from your code