Live Chat

The libredesk live chat widget embeds on any website as a single <script> tag. Visitors can start conversations anonymously, or you can verify their identity with a server-signed JWT so the widget loads with their profile attached.

Create a live chat inbox

Add the inbox

Go to Admin → Inboxes → New inbox → Live Chat. Fill in the name, brand name, and website URL.

Configure appearance and messages

Set the colors, launcher, greeting, and home screen under the Appearance and Content tabs. All changes are live as soon as you save.

Copy the install snippet

Open the Setup tab, expand Installation and copy the <script> snippet shown there. Paste it before the closing </body> tag on every page where the widget should appear.

The anonymous snippet looks like this:

<script>
  window.LibredeskSettings = {
    baseURL: 'https://support.example.com',
    inboxID: 'YOUR_INBOX_UUID'
  };
</script>
<script async src="https://support.example.com/widget.js"></script>

baseURL is the URL of your libredesk instance. inboxID is the inbox UUID, already filled in by the snippet on the Setup tab. Anyone visiting the page can now open the widget and start a conversation. A visitor is remembered in the same browser. To recognize signed-in users across devices, add identity verification. window.LibredeskSettings accepts these keys:

Key	Required	Description
`baseURL`	Yes	URL of your libredesk instance.
`inboxID`	Yes	UUID of the live chat inbox.
`userJWT`	No	Signed JWT for a logged-in user. See Identity verification.
`language`	No	Widget UI language, e.g. `de`. Used when the inbox language is Auto-detect (browser language).
`hideLauncher`	No	`true` hides the launcher button. Open the widget with `Libredesk.show()`.
`cookieDomain`	No	Domain for the session cookie. Defaults to the parent domain, e.g. `.example.com`.

Identity verification

If users are already signed into your product, pass a signed JWT so the widget loads with their existing libredesk contact. Without verification, the widget cannot tell a returning user apart from a new visitor on a new device.

How it works

Your server signs a JWT with the inbox Secret key (set under Setup → Security).
Your page passes that JWT to the widget via userJWT, or calls Libredesk.setUser(jwt).
libredesk verifies the signature, then finds or creates the contact by external_user_id.

The signing algorithm is HS256 (HMAC-SHA256). The secret never leaves your server.

JWT payload

{
  "external_user_id": "your_app_user_123",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "9876543210",
  "phone_number_country_code": "IN",
  "exp": 1735689600,
  "contact_custom_attributes": {
    "plan": "premium",
    "company": "Acme Inc"
  }
}

Field	Required	Description
`external_user_id`	Yes	Stable unique ID from your system. Used to match returning users.
`email`	Yes	User’s email address.
`first_name`	Yes	User’s first name.
`last_name`	No	User’s last name.
`phone_number`	No	User’s phone number.
`phone_number_country_code`	No	ISO 3166-1 alpha-2 country code for the phone number (e.g. `IN`, `US`).
`exp`	Yes	Unix timestamp (seconds) when the token expires.
`contact_custom_attributes`	No	Object of custom attributes written to the contact record on login.

Sign the token on your server

import jwt, time

payload = {
    "external_user_id": "your_app_user_123",
    "email": "user@example.com",
    "first_name": "John",
    "exp": int(time.time()) + 3600,
}
token = jwt.encode(payload, SECRET, algorithm="HS256")

const jwt = require('jsonwebtoken');

const token = jwt.sign({
  external_user_id: 'your_app_user_123',
  email: 'user@example.com',
  first_name: 'John',
  exp: Math.floor(Date.now() / 1000) + 3600,
}, SECRET, { algorithm: 'HS256' });

import (
    "time"
    "github.com/golang-jwt/jwt/v5"
)

claims := jwt.MapClaims{
    "external_user_id": "your_app_user_123",
    "email":            "user@example.com",
    "first_name":       "John",
    "exp":              time.Now().Add(time.Hour).Unix(),
}
token, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).
    SignedString([]byte(SECRET))

Never embed the inbox secret in client-side code. Sign the JWT on your server and inject it into the page at render time, or fetch it from an authenticated endpoint.

<script>
  window.LibredeskSettings = {
    baseURL: 'https://support.example.com',
    inboxID: 'YOUR_INBOX_UUID',
    userJWT: 'YOUR_SIGNED_JWT_TOKEN_HERE'
  };
</script>
<script async src="https://support.example.com/widget.js"></script>

JavaScript API

Once the widget loads, window.Libredesk exposes these methods:

Method	Description
`Libredesk.show()`	Open the widget.
`Libredesk.hide()`	Close the widget.
`Libredesk.toggle()`	Toggle between open and closed.
`Libredesk.isVisible()`	Return `true` when the widget is open.
`Libredesk.setUser(jwt)`	Log a user in after page load with a signed JWT.
`Libredesk.logout()`	Clear the current session and reset to anonymous.
`Libredesk.setLanguage(code)`	Switch the widget UI language.
`Libredesk.trackEvent(name)`	Record an event for proactive message targeting.
`Libredesk.destroy()`	Remove the launcher and widget from the page.
`Libredesk.onShow(fn)`	Register a callback fired when the widget opens.
`Libredesk.onHide(fn)`	Register a callback fired when the widget closes.
`Libredesk.onUnreadCountChange(fn)`	Register a callback fired with the unread message count.

Example:

window.Libredesk.onUnreadCountChange(function (count) {
  document.title = count > 0 ? `(${count}) Inbox` : 'Inbox';
});

Proactive messages

A proactive message pops up next to the launcher on matching pages. A conversation starts when someone replies. Add them under Content → Proactive messages. The first matching message in the list is shown.

Setting	Description
Sender	Agent shown as the sender. Brand bot shows the inbox brand name.
Route replies to team	Team that gets the conversation when someone replies.
Who sees it	All, visitors only, or logged-in users only, with optional conditions on contact custom attributes.
Include pages / Exclude pages	One URL or path per line. `*` matches any characters. An empty include list matches every page.
Optional event name	Show the message only after your site calls `Libredesk.trackEvent()` with this name.
Active time on page (seconds)	Time on the page before the message shows.
Business hours rule	Any time, during business hours, or outside business hours of a chosen schedule.
Device	Desktop, mobile, or both.
Show again	Once per person, once per session, or after a set number of hours.

Minimum time between proactive messages (default 24h) applies across all proactive messages in the inbox. Under Content → Help center, pick one of your help centers to let people search and read its published articles inside the widget.

Show Help tab turns the Help tab on or off, separately for visitors and users.
Featured articles picks the articles shown first. Leave it empty to show popular articles.
To show help on the home screen, add the help articles card under Content → Home screen apps.

Pre-chat form

Under Conversations → Pre-chat form, collect details such as name, email, and custom attributes before a chat starts. Turn on Show only during AI handoff to show the form only when the AI assistant hands the chat to an agent.

Conversation continuity

If a contact leaves the live chat before the conversation is finished, libredesk can email them the agent replies they have not seen. Pick an email inbox under General → Conversation continuity email inbox to turn this on. The contact needs an email address.

Setting	Default	Description
Offline threshold	`10m`	How long the contact must be offline before libredesk sends the email.
Max messages per email	`10`	Maximum number of messages in one email.
Min email interval	`15m`	Minimum time between continuity emails for the same conversation.

Replies to the email thread are added back to the same live chat conversation.

Security

These settings are under Setup → Security.

Trusted domains

List the domains allowed to embed the widget, one per line. *.example.com matches subdomains only, so add the bare domain separately:

example.com
*.example.com
staging.example.com

Leave this empty to allow any domain. Always set it in production.

Blocked IPs

Block specific IPs or CIDR ranges from opening the widget, one per line:

168.1.0/24
0.0.1
db8::/32

Session duration

Authenticated user session duration controls how long a signed-in user’s session lasts without activity. Default is 10h. Format accepts s, m, h (e.g. 30m, 24h).

Introduction

Getting Started

Configuration

Roles

Contributing

Create a live chat inbox

Install the widget

Widget settings

Identity verification

How it works

JWT payload

Sign the token on your server

Pass the token to the widget

JavaScript API

Proactive messages

Help articles in the widget

Pre-chat form

Conversation continuity

Security

Trusted domains

Blocked IPs

Session duration

​Create a live chat inbox

​Install the widget

​Widget settings

​Identity verification

​How it works

​JWT payload

​Sign the token on your server

​Pass the token to the widget

​JavaScript API

​Proactive messages

​Help articles in the widget

​Pre-chat form

​Conversation continuity

​Security

​Trusted domains

​Blocked IPs

​Session duration

Create a live chat inbox

Install the widget

Widget settings

Identity verification

How it works

JWT payload

Sign the token on your server

Pass the token to the widget

JavaScript API

Proactive messages

Help articles in the widget

Pre-chat form

Conversation continuity

Security

Trusted domains

Blocked IPs

Session duration