Configuration Reference

Dashboard vs Inline Configuration

All widget settings can be configured directly in the Lua AI admin dashboard — no code changes needed. To use dashboard settings, initialize the widget with no arguments:

window.LuaPop.init();

To override specific settings in code, pass a config object:

window.LuaPop.init({
  sessionId: dynamicSessionId, // runtime value — overrides dashboard
});

Configuration priority: Any option passed to window.LuaPop.init({...}) takes priority over the corresponding dashboard setting. Options not passed in code fall back to dashboard values. Call window.LuaPop.init() with no arguments to use dashboard settings exclusively.

window.LuaPop.init(config)

Initialize the LuaPop widget with the provided configuration.

const widget = window.LuaPop.init({
  agentId: "your-agent-id",
  // ... other options
});

Returns: Widget instance with destroy() method

Required Configuration

string

required

Required. The ID of the AI agent to use for conversations.Get this from your Lua AI dashboard.

agentId: "agent_abc123xyz"

Basic Configuration

string

default:"bottom-right"

Widget position on the page.Options: "bottom-right", "bottom-left", "top-right", "top-left"

position: "bottom-right"

string

default:"Chat with us"

Text displayed on the chat button.

buttonText: "💬 Need Help?"

string

default:"production"

API environment to use.Options: "staging", "production", "custom"

environment: "production"

Authentication & Session

string

Unique session identifier for the user.If not provided, auto-generated. Use for persistent conversations across page loads.

sessionId: "user-12345"

string

Optional authentication token for authenticated users.

authToken: "bearer-token-here"

string

Custom API base URL (only when environment is "custom").

environment: "custom",
customBaseApiUri: "https://your-api.com"

Display Configuration

string

default:"floating"

How the widget is displayed.Options: "floating", "embedded"

displayMode: "floating" // or "embedded"

boolean

default:false

Allow users to drag and drop the floating button (pill) to reposition it. Useful when the button overlaps other elements on your page — users can move it out of the way. Only applies when displayMode is "floating".

displayMode: "floating",
draggable: true

object

Configuration for embedded mode. Required when displayMode is "embedded".

embeddedDisplayConfig: {
  targetContainerId: string;       // ID of the container element to render into
  conversationStarters?: string[]; // Suggested prompts shown before first message
  useContainerHeight?: boolean;    // Always use container height (100%) vs auto-detect
}

targetContainerId (required) — The id of the DOM element the widget will render into.conversationStarters (optional) — An array of suggested prompts displayed to the user before they send their first message. Clicking a starter sends it as a message.useContainerHeight (optional, default false) — When true, the widget always fills its container using height: 100%. Use this for footer or expandable layouts where the container height changes dynamically. When false, the widget auto-detects an explicit container height and falls back to 100dvh if none is set.Example:

displayMode: "embedded",
embeddedDisplayConfig: {
  targetContainerId: "my-chat-container",
  conversationStarters: [
    "What can you help me with?",
    "Show me your latest products",
    "I need support with my order"
  ],
  useContainerHeight: true
}

string | number

default:"500px"

Height of the chat window.

chatWindowHeight: "600px"  // or 600

string | number

default:"350px"

Width of the chat window.

chatWindowWidth: "400px"  // or 400

Visual Customization

string

default:"#007bff"

Background color of the chat button.

buttonColor: "#28a745"

string

default:"💬"

Icon or emoji displayed on the button.

buttonIcon: "🤖"

string

default:"Chat"

Title displayed in the chat header.

chatTitle: "Customer Support"

string

default:"Ask anything, about anything"

Placeholder text for the input field.

chatInputPlaceholder: "How can we help you today?"

string

default:"Hi! How can I help you today?"

Welcome message displayed when the chat is first opened and no conversation history exists.This message appears as the first assistant message, helping to greet users and set the tone for the conversation.

welcomeMessage: "Hello! How can we assist you today?"

Advanced Styling

Custom CSS styles for the chat button.

popupButtonStyles: {
  borderRadius: "50%",
  width: "60px",
  height: "60px",
  fontSize: "24px",
  boxShadow: "0 4px 12px rgba(0,0,0,0.15)"
}

Custom CSS styles for button positioning.

popupButtonPositionalContainerStyles: {
  bottom: "20px",
  right: "20px",
  zIndex: "9999"
}

React.CSSProperties

Custom CSS styles for the chat header.

chatTitleHeaderStyles: {
  background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
  color: "white",
  borderRadius: "10px 10px 0 0"
}

Branding

object

Subtitle configuration for branding.

chatHeaderSubtitle: {
  visible: boolean;
  brandName?: string;
  iconUrl?: string;
  linkUrl?: string;
}

Example:

chatHeaderSubtitle: {
  visible: true,
  brandName: "Your Company",
  iconUrl: "https://yoursite.com/logo.png",
  linkUrl: "https://yoursite.com"
}

Advanced Features

boolean

default:false

Enable voice chat functionality. When true, users can switch to a full voice interaction mode where AI responses are spoken aloud. See the Voice Chat guide for details.

voiceModeEnabled: true

boolean

default:false

Show a microphone button in the chat input bar, allowing users to dictate messages via speech-to-text. Unlike voiceModeEnabled, this keeps the interaction in text mode — the spoken input is transcribed into the text field rather than switching to a full voice experience.

microphoneEnabled: true

boolean

default:false

Allow users to upload and send file attachments (images, documents, etc.) within the chat. When true, a file attachment button appears in the chat input bar.

attachmentsEnabled: true

boolean

default:false

Disable automatic link previews.

disablePreviewOnLinks: true

string

Additional context passed to the AI agent.Useful for providing page context, user roles, etc.

runtimeContext: "page:pricing,user:premium,lang:en"

Event Handlers

function

Handler for navigation events from the chat.

onNavigate: (pathname: string, options: { query: Record<string, string> }) => void

Example:

onNavigate: (pathname, options) => {
  console.log('Navigate to:', pathname);
  console.log('Query params:', options.query);
  
  // Handle navigation in your app
  window.location.href = pathname + '?' + new URLSearchParams(options.query);
}

Complete Example

window.LuaPop.init({
  // Required
  agentId: "customer-support-agent",
  
  // Basic
  position: "bottom-right",
  buttonText: "💬 Need Help?",
  environment: "production",
  
  // Session
  sessionId: "user-12345",
  authToken: "your-auth-token",
  
  // Display
  displayMode: "floating",
  chatWindowHeight: "600px",
  chatWindowWidth: "400px",
  
  // Visual
  buttonColor: "#28a745",
  buttonIcon: "🤖",
  chatTitle: "Customer Support",
  
  // Styling
  popupButtonStyles: {
    borderRadius: "25px",
    padding: "15px 20px",
    fontSize: "16px"
  },
  
  popupButtonPositionalContainerStyles: {
    bottom: "30px",
    right: "30px"
  },
  
  chatTitleHeaderStyles: {
    background: "#28a745",
    color: "white"
  },
  
  // Branding
  chatInputPlaceholder: "How can we help?",
  welcomeMessage: "Hi there! 👋 How can we help you today?",
  chatHeaderSubtitle: {
    visible: true,
    brandName: "Your Company",
    iconUrl: "/logo.png",
    linkUrl: "/"
  },
  
  // Advanced
  voiceModeEnabled: true,
  microphoneEnabled: true,
  attachmentsEnabled: true,
  disablePreviewOnLinks: false,
  runtimeContext: "page:home",
  
  // Events
  onNavigate: (pathname, options) => {
    console.log('Navigate:', pathname);
  }
});

Configuration Tips

Use Staging for Testing

Always test new configurations with staging first:

environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging'

Generate Unique Session IDs

Create unique sessions for better tracking:

sessionId: `user-${userId}-${Date.now()}`

Use Runtime Context

Pass page context to help the AI provide better responses:

runtimeContext: `page:${window.location.pathname},lang:${document.documentElement.lang}`

Responsive Configuration

Adjust for different screen sizes:

const isMobile = window.innerWidth <= 768;

window.LuaPop.init({
  agentId: "your-agent-id",
  chatWindowWidth: isMobile ? "100vw" : "400px",
  chatWindowHeight: isMobile ? "100vh" : "600px"
});

Next Steps

Styling Guide

Customize colors, fonts, and appearance

Events API

Listen to chat events and interactions

Examples

See real-world configurations

Framework Integration

React, Vue, Angular guides

​Dashboard vs Inline Configuration

​window.LuaPop.init(config)

​Required Configuration

​Basic Configuration

​Authentication & Session

​Display Configuration

​Visual Customization

​Advanced Styling

​Branding

​Advanced Features

​Event Handlers

​Complete Example

​Configuration Tips

​Next Steps

Styling Guide

Events API

Examples

Framework Integration

Dashboard vs Inline Configuration

window.LuaPop.init(config)

Required Configuration

Basic Configuration

Authentication & Session

Display Configuration

Visual Customization

Advanced Styling

Branding

Advanced Features

Event Handlers

Complete Example

Configuration Tips

Next Steps