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 launcher colour, position, logo, greeting message, and home screen under the Appearance and Messages tabs. All changes are live as soon as you save.

Copy the install snippet

Open the Installation tab 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 UUID shown on the inbox’s Installation tab. Anyone visiting the page can now open the widget and start a conversation. Every session is treated as a new anonymous visitor unless you add identity verification.

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 the Security tab).
Your page passes that JWT to the widget via userJWT.
Libredesk verifies the signature, then upserts 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.setUser(jwt)`	Log a user in after page load with a signed JWT.
`Libredesk.logout()`	Clear the current session and reset to anonymous.
`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';
});

Conversation continuity

Contacts don’t have to stay in the live chat. If they leave before the conversation is finished, Libredesk can automatically email them any unread messages.

Setting	Description
`offline_threshold`	How long agents must be offline before email fallback is triggered (e.g. `10m`).
`max_messages_per_email`	Maximum number of messages per email. Additional messages are sent in a new email.
`min_email_interval`	Minimum time between fallback emails for the same conversation.

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

Security

Trusted domains

Under the Security tab, list the domains allowed to embed the widget. Requests from other origins are rejected. Supports wildcards:

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

Leave this empty to allow all origins. Set it in production.

Blocked IPs

Block specific IPs or CIDR ranges from opening the widget:

168.1.0/24
0.0.1
db8::/32

Session duration

Controls how long a widget session stays authenticated before the JWT must be re-verified. 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

Identity verification

How it works

JWT payload

Sign the token on your server

Pass the token to the widget

JavaScript API

Conversation continuity

Security

Trusted domains

Blocked IPs

Session duration

​Create a live chat inbox

​Install the widget

​Identity verification

​How it works

​JWT payload

​Sign the token on your server

​Pass the token to the widget

​JavaScript API

​Conversation continuity

​Security

​Trusted domains

​Blocked IPs

​Session duration

Create a live chat inbox

Install the widget

Identity verification

How it works

JWT payload

Sign the token on your server

Pass the token to the widget

JavaScript API

Conversation continuity

Security

Trusted domains

Blocked IPs

Session duration