Live Chat Widget

Embed a live chat widget on your website so visitors can start real-time conversations with your support team. Messages become helpdesk tickets automatically.

On this page

Installation

Add this single line of code before the closing </body> tag on every page where you want the widget to appear: 

<script
  src="https://api.disqua.com/widget/disqua-widget.js"
  data-workspace="YOUR_WORKSPACE_ID"
  async>
</script>

Where to find your Workspace ID: Go to Workspace Settings → General in your Disqua console. The Workspace ID is shown at the bottom of the page.

The script is lightweight (~8 KB), loads asynchronously, and uses Shadow DOM so it won't interfere with your page's CSS or JavaScript.

Configuration

Customise the widget using data-* attributes on the script tag:

Attribute Required Default Description
data-workspace Yes - Your Disqua Workspace UUID
data-color No #6366f1 Accent color (hex). Applied to the bubble, header, and send button.
data-position No right right or left — which corner the bubble appears in.

Example with all options

<script
  src="https://api.disqua.com/widget/disqua-widget.js"
  data-workspace="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  data-color="#e11d48"
  data-position="left"
  async>
</script>

How it works

  1. 1 A floating chat bubble appears in the bottom corner of your page.
  2. 2 When a visitor clicks the bubble and sends their first message, Disqua creates a helpdesk ticket (channel: live_chat) and a contact record.
  3. 3 The ticket appears in your helpdesk inbox instantly. Agents reply from the ticket view — their replies appear in the visitor's chat window within 3 seconds.
  4. 4 The visitor's session is persisted in localStorage. If they return later, they see their previous conversation and can continue chatting.
  5. 5 If a visitor sends a new message on a resolved/closed ticket, it automatically reopens.

Widget API Reference

These public endpoints are used by the widget script. You can also call them directly for custom integrations.

GET /widget/config/:workspaceId

Returns widget branding (workspace name, greeting message, accent color).

POST /widget/sessions

Creates a new chat session (ticket + contact + first message).

Body: { workspaceId, message, name?, email? } → Returns { sessionId, sessionToken }

POST /widget/sessions/:sessionId/messages

Sends a message from the visitor. Requires X-Widget-Token header.

Body: { message }

GET /widget/sessions/:sessionId/messages?after=DATETIME

Polls for new messages (used every 3 seconds). Requires X-Widget-Token header.

Returns: { messages: [{ id, sender_type, body_text, created_at }] }

Advanced Customisation

The widget can also be configured from your Disqua console:

  • Workspace Settings → Helpdesk → Integrations — copy the embed code with colour picker and position selector.
  • Widget uses Shadow DOM — your page CSS cannot accidentally break the widget UI.
  • Widget is responsive — full-screen on mobile, floating panel on desktop.
  • Script loads async and is ~8 KB — no impact on page performance.