This document summarizes the public endpoints and WebSocket messages used by the Libredesk live chat widget. These APIs are intended for custom widget frontends that talk to an existing Libredesk instance.
Widget HTTP requests identify the live chat inbox with either:
X-Libredesk-Inbox-ID: <inbox_uuid>header?inbox_id=<inbox_uuid>query parameter
Authenticated widget requests also send:
Authorization: Bearer <session_token>
When a verified contact is replacing a previous visitor session, the widget can also send:
X-Libredesk-Visitor-Token: <visitor_session_token>
If Libredesk merges the visitor into the verified contact, the response includes
X-Libredesk-Clear-Visitor: true so the custom frontend can discard the visitor
token.
API responses use Libredesk's standard envelope format. Successful responses put
the endpoint payload in data.
Returns launcher-only settings for the embeddable script before the widget
iframe is opened. The inbox can be passed as ?inbox_id=<inbox_uuid>.
Returns the live chat widget settings, including public configuration and, when enabled, business hours and pre-chat custom attribute metadata.
Exchanges a customer-generated JWT for a widget session token.
Request body:
{
"jwt": "<signed_customer_jwt>"
}The JWT must include external_user_id, email, and first_name. It can also
include last_name and contact_custom_attributes.
Response data includes:
{
"session_token": "<session_token>",
"user": {
"user_id": 123,
"is_visitor": false,
"first_name": "Ada",
"last_name": "Lovelace"
}
}Returns the current widget user's metadata for the bearer session token.
Starts a new live chat conversation. If no bearer token is present, Libredesk creates a visitor and returns a new session token.
Request body:
{
"message": "Hello, I need help",
"form_data": {
"company": "Example Co"
}
}Response data includes the created conversation, messages, optional
business hours fields, and, for a new visitor, session_token plus user.
Returns the conversations visible to the current widget user for the selected inbox.
Returns one conversation with its messages and optional business hours metadata.
Sends a text message to an existing conversation.
Request body:
{
"message": "Here are more details"
}Marks the conversation as seen by the widget user.
Uploads one or more files to an existing conversation. This endpoint requires
multipart/form-data.
Form fields:
conversation_uuid: target conversation UUIDfiles: one or more file parts
File uploads are rejected when the inbox has file upload disabled, the file is empty, the file is larger than the configured limit, or the extension is not allowed.
The widget uses this WebSocket endpoint for realtime conversation events.
After opening the socket, send a join message with the inbox UUID and session
token:
{
"type": "join",
"token": "<session_token>",
"data": {
"inbox_id": "<inbox_uuid>"
}
}The server replies with:
{
"type": "joined",
"data": {
"message": "namaste!"
}
}typing broadcasts the visitor typing state to agents:
{
"type": "typing",
"data": {
"conversation_uuid": "<conversation_uuid>",
"is_typing": true
}
}page_visit stores the visitor's current page and broadcasts recent page visits
to agents:
{
"type": "page_visit",
"data": {
"url": "https://example.com/pricing",
"title": "Pricing"
}
}ping keeps the session active and should be sent periodically:
{
"type": "ping"
}The server replies with pong.
The widget client handles these message types:
joined: the socket joined the live chat inbox.pong: response toping.new_message: a new chat message;datais a chat message payload.typing: agent typing status withconversation_uuidandis_typing.conversation_update: partial conversation update.error: socket-level error payload.