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
- 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 callsLibredesk.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": "[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).
