LiyaSupport
Getting started

Web widget installation

Add the Liya live chat and AI widget to your website or web app in under 5 minutes.

4 min read Updated July 2026
The web widget lets customers start a conversation directly from your website or app. All widget conversations route into your Liya inbox alongside email and other channels.

Choose your installation method

Option A: Script tag (any website)

Paste the following snippet before the closing </body> tag on every page where you want the widget to appear. Replace YOUR_WORKSPACE_ID with the ID from Settings → AI Agent → Widget.

html
<script>
  window.LiyaSettings = {
    workspaceId: "YOUR_WORKSPACE_ID",
    // Optional: pre-fill customer details
    // identity: { name: "Jane Doe", email: "[email protected]" }
  };
</script>
<script
  src="https://cdn.liyasupport.com/widget/v2/widget.js"
  async
  defer
></script>
Find your workspaceId in Dashboard → AI Agent → Installation. It looks like ws_a1b2c3d4e5f6.

Option B: React / Next.js package

If you're building with React or Next.js, use our typed npm package for a cleaner integration with full TypeScript support.

tsx
// Install the package
// npm install @liyasupport/widget
// yarn add @liyasupport/widget

// In your app root (e.g. _app.tsx or layout.tsx):
import { LiyaWidget } from "@liyasupport/widget";

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <LiyaWidget
        workspaceId="YOUR_WORKSPACE_ID"
        // Identify logged-in users:
        // identity={{ name: user.name, email: user.email }}
      />
    </>
  );
}

Identifying logged-in users

When a customer is logged in to your app, pass their identity to Liya so agents can see their name, email, and custom attributes directly in the conversation sidebar. This saves customers from having to repeat themselves.

Call window.Liya.identify() after your authentication flow resolves:

javascript
window.Liya.identify({
  userId: "usr_123",
  name: "Jane Doe",
  email: "[email protected]",
  // Custom attributes — any key/value pairs:
  plan: "pro",
  company: "Acme Corp",
  signedUpAt: "2025-01-15",
});
Never pass sensitive information (passwords, payment details, session tokens) as custom attributes. Only pass data that's useful for support context.

Customising the widget appearance

You can configure the widget appearance to match your brand. All options are set in the window.LiyaSettings object before the script loads:

javascript
window.LiyaSettings = {
  workspaceId: "YOUR_WORKSPACE_ID",
  appearance: {
    accentColor: "#FF4F00",      // Button and header colour
    position: "bottom-right",   // "bottom-right" | "bottom-left"
    offsetX: 20,                // Horizontal offset in px
    offsetY: 20,                // Vertical offset in px
    launcherLabel: "Help",      // Text on the launcher button
    hideOnMobile: false,        // Set true to hide on mobile
  },
};

Appearance options

OptionTypeDefaultDescription
accentColorstring#FF4F00Widget button and header colour
positionstringbottom-rightLauncher position: bottom-right or bottom-left
offsetXnumber20Horizontal distance from the page edge (px)
offsetYnumber20Vertical distance from the page edge (px)
launcherLabelstringChat with usText displayed on the collapsed launcher button
hideOnMobilebooleanfalseHide the widget on screens narrower than 768px

Testing the installation

1

Load your website

Open the page where you added the snippet. You should see the Liya launcher button in the bottom-right corner.

2

Send a test message

Click the launcher and type a test message. It should appear in your Liya inbox as a new conversation within a few seconds.

3

Verify AI draft

Open the conversation in your dashboard. If you have knowledge base content set up, you should see an AI draft ready for review.

Troubleshooting

Widget not appearing

  • Check the browser console for JavaScript errors.
  • Confirm workspaceId is set correctly (no extra spaces or quotes).
  • If you have a Content Security Policy, add cdn.liyasupport.com to your script-src allowlist.

Conversations not appearing in inbox

  • Ensure your workspace is on an active plan.
  • Check Settings → AI Agent → Status is set to "Active".
  • Try a hard refresh (Cmd/Ctrl + Shift + R) in the dashboard.

Content Security Policy

Add the following directives to your CSP header to allow the widget to load and communicate:

text
script-src 'self' cdn.liyasupport.com;
connect-src 'self' api.liyasupport.com wss://rt.liyasupport.com;
img-src 'self' data: cdn.liyasupport.com;
frame-src 'self' widget.liyasupport.com;