Web widget

Widget modes

The Liya widget supports two modes, which can be configured independently per workspace:

You can run both modes simultaneously: configure AI self-serve for certain intents (e.g. order status) and live chat for others (e.g. billing disputes). Set this in Settings → AI Agent → Intent routing.

Widget configuration

Appearance

Customise the widget look and feel in Settings → AI Agent → Appearance:

• Accent colour — used for buttons, send icons, and active states
• Bot name and avatar — the AI's display name and icon (e.g. "Liya" or your own brand name)
• Launcher button style — icon-only, icon + label, or custom icon
• Widget size — standard (380×600px) or compact (340×520px)
• Position — bottom-right or bottom-left, with configurable offset

Welcome message

Configure the message customers see when they first open the widget. You can set different messages for known users (identified via window.Liya.identify()) and anonymous visitors.

Example: "Hi Jane! How can we help you today?" for identified users, and"Welcome to Acme Support. What can we help you with?" for anonymous visitors.

Pre-chat form

Optionally collect the customer's name and email before they start a conversation. This is useful for anonymous visitors where you want to capture their details for follow-up. If a user is already identified via window.Liya.identify(), the pre-chat form is skipped automatically.

Suggested prompts

Show clickable prompt buttons when the widget opens to guide customers to common topics (e.g. "Track my order", "Return an item", "Speak to a person"). Configure up to 4 prompts in Settings → AI Agent → Quick prompts.

JavaScript API

Control the widget programmatically using the window.Liya API. This is useful for triggering the widget from custom buttons, responding to user actions, or pre-populating conversations.

// Open the widget programmatically
window.Liya.open();

// Close it
window.Liya.close();

// Show/hide the launcher button
window.Liya.hide();
window.Liya.show();

// Pre-populate a new conversation
window.Liya.newConversation({
  initialMessage: "I need help with my order #12345",
});

// Listen for events
window.Liya.on("conversationStarted", (data) => {
  console.log("New conversation:", data.conversationId);
});

window.Liya.on("messageSent", (data) => {
  console.log("Message sent by customer:", data.message);
});

Mobile responsiveness

The widget is fully responsive and works on mobile browsers. On screens narrower than 768px, the widget expands to near full-screen for a better mobile experience.

To hide the widget on mobile entirely (and show a mobile-specific support option instead), set hideOnMobile: true in the window.LiyaSettings configuration.

Availability hours and offline state

When your team is outside business hours, the widget can behave in one of three ways:

• Show as offline — displays an "Our team is offline" message with expected response time
• Collect email — asks for the customer's email and message, creates a ticket in Liya
• AI self-serve only — continues serving the AI without live agent handoff

Configure this in Settings → AI Agent → Out-of-hours behaviour.