Live chat

Installing the chat widget

One script tag, three ways to identify a signed-in visitor, and everything else configured from Settings rather than in code.

The Leodesk chat widget is a single script tag. It is plain JavaScript with no bundler, no framework and no module imports, it renders inside its own isolated root so it cannot inherit or leak your page's styles, and it talks only to the origin it was served from.

The script tag

Add this immediately before the closing </body> tag on every page where you want the bubble to appear, replacing the subdomain and workspace with your own:

html

<script src="https://acme.leodesk.io/widget.js"
        data-workspace="acme"
        defer></script>

data-workspace is required — without it the widget logs a warning and does nothing. Keep defer so the script never blocks rendering; the widget mounts after your page is interactive. The API origin is derived from the script's own src, so there is no second URL to configure and nothing to change if you move between environments.

Put the tag in your site's shared layout, template or tag manager rather than on individual pages. If it ends up included twice, the widget detects the duplicate mount for that workspace and skips it, so a double-include is untidy rather than fatal.

Confirming it loaded

Hard-refresh the page and open the browser console. The widget prints a boot line naming the build it is running. If you do not see it, your browser is serving a cached copy of the script — reload with the cache disabled. The script is served with revalidation, so a new release lands on the next page view rather than needing a version bump on your side.

Identifying signed-in users

By default a visitor is anonymous and shows as "Visitor" in the agent inbox. If they are logged into your product you already know who they are, and passing that through is the difference between an agent guessing and an agent answering. There are three ways to do it, in order of precedence.

1. The imperative call. Best when your own user object loads asynchronously — call it any time after the script tag:

window.leodesk.identify({
  name:  'Dana Ruiz',
  email: '[email protected]',
  customData: { plan: 'Pro', signup: '2024-11-02', seats: '12' },
});

2. The declarative global. Set it before the script tag when the values are already rendered into the page:

html

<script>
  window.leodesk = { user: { name: 'Dana Ruiz', email: '[email protected]' } };
</script>
<script src="https://acme.leodesk.io/widget.js" data-workspace="acme" defer></script>

3. Attributes on the script tag. The simplest option for server-rendered pages. Use data-name, data-email and data-id, and pass anything else with a data-cd- prefix — data-cd-plan="Pro" becomes a plan field on the visitor's custom data.

html

<script src="https://acme.leodesk.io/widget.js"
        data-workspace="acme"
        data-name="Dana Ruiz"
        data-email="[email protected]"
        data-id="usr_8812"
        data-cd-plan="Pro"
        defer></script>

An identified visitor shows their real name in the chat list and sidebar, and their custom data appears on the conversation panel beside the thread, so an agent can see the plan or account id without leaving the reply box. Identity also lets the widget skip the pre-chat form — there is no point asking for an email address you have already supplied.

Escape any values you interpolate into attributes, and treat custom data as something the visitor can read: it is passed from the browser, so it belongs to them. Send the account id, not the internal note about the account.

Theming and behaviour

Almost everything visual is configured in Settings rather than in code, so changing it needs no deploy on your side:

Accent colour — defaults to your workspace brand colour, so a widget usually looks right before you touch it.
Bubble position — bottom-right, bottom-left or top-right.
Welcome message and greeting line — the first thing a visitor reads, and the expectation-setting line beneath it.
Pre-chat form — on or off. Off means fewer drop-offs; on means you always get a reply address.
Common questions — quick-reply prompts a visitor can tap to seed their first message.
Offline message — shown above the leave-a-message form when a visitor opens the widget outside your business hours.

Business hours are what drive that availability display, and an online/away presence pill reflects whether agents are actually around. If you would rather not advertise that nobody is at the desk, the presence pill can be turned off.

Feature toggles

Seven behaviours can each be switched off independently, and all are on by default: link previews, drag-and-drop file uploads, transcript download, a satisfaction rating at the end of a chat, message reactions, letting visitors edit or delete their own messages, and the agent presence pill. Turning one off hides it in the widget and stops the agent side rendering the resulting data.

Chat attachments sent by agents are a paid-plan feature and are blocked on Free.

What visitors experience

An open conversation is stored in the browser's local storage, scoped to your workspace, so refreshing or navigating to another page keeps the thread alive instead of restarting it. A returning visitor identified the same way picks up their existing conversation rather than opening a duplicate. Chats land in the same queue as email, so there is no second inbox for your team to watch.

Once the widget is live, the thing worth setting up next is what happens to the tickets it creates — see automation rules and SLA policies.

Next →Automation rules & SLA policies