Skip to main content

Try the live demo!

Search

Live Chat

Embed the libredesk chat widget on your website and verify user identity with JWTs

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.

Install the widget

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.

Widget settings

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

  1. Your server signs a JWT with the inbox Secret key (set under Setup → Security).
  2. Your page passes that JWT to the widget via userJWT, or calls Libredesk.setUser(jwt).
  3. 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": "[email protected]",
  "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": "[email protected]",
  "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: '[email protected]',
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":            "[email protected]",
  "first_name":       "John",
  "exp":              time.Now().Add(time.Hour).Unix(),
}
token, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).
  SignedString([]byte(SECRET))

Warning:

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.

Pass the token to the widget

<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.

Help articles in the widget

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:

192.168.1.0/24
10.0.0.1
2001: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).

Was this article helpful?