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

agentId

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

position

string

default:"bottom-right"

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

position: "bottom-right"

buttonText

string

default:"Chat with us"

Text displayed on the chat button.

buttonText: "💬 Need Help?"

environment

string

default:"production"

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

environment: "production"

Authentication & Session

sessionId

string

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

sessionId: "user-12345"

authToken

string

Optional authentication token for authenticated users.

authToken: "bearer-token-here"

customBaseApiUri

string

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

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

Display Configuration

displayMode

string

default:"floating"

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

displayMode: "floating" // or "embedded"

embeddedDisplayConfig

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
}

chatWindowHeight

string | number

default:"500px"

Height of the chat window.

chatWindowHeight: "600px"  // or 600

chatWindowWidth

string | number

default:"350px"

Width of the chat window.

chatWindowWidth: "400px"  // or 400

Visual Customization

buttonColor

string

default:"#007bff"

Background color of the chat button.

buttonColor: "#28a745"

buttonIcon

string

default:"💬"

Icon or emoji displayed on the button.

buttonIcon: "🤖"

chatTitle

string

default:"Chat"

Title displayed in the chat header.

chatTitle: "Customer Support"

chatInputPlaceholder

string

default:"Ask anything, about anything"

Placeholder text for the input field.

chatInputPlaceholder: "How can we help you today?"

welcomeMessage

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"
}

chatTitleHeaderStyles

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

chatHeaderSubtitle

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

voiceModeEnabled

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

microphoneEnabled

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

attachmentsEnabled

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

disablePreviewOnLinks

boolean

default:false

Disable automatic link previews.

disablePreviewOnLinks: true

runtimeContext

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

onNavigate

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

Getting Started

Configuration

Integration

Features

Help

Documentation Index

​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