> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Reference

> Complete configuration options for LuaPop

## 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:

```javascript theme={null}
window.LuaPop.init();
```

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

```javascript theme={null}
window.LuaPop.init({
  sessionId: dynamicSessionId, // runtime value — overrides dashboard
});
```

<Info>
  **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.
</Info>

***

## window\.LuaPop.init(config)

Initialize the LuaPop widget with the provided configuration.

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

**Returns:** Widget instance with `destroy()` method

## Required Configuration

<ParamField path="agentId" type="string" required>
  **Required.** The ID of the AI agent to use for conversations.

  Get this from your Lua AI dashboard.

  ```javascript theme={null}
  agentId: "agent_abc123xyz"
  ```
</ParamField>

## Basic Configuration

<ParamField path="position" type="string" default="bottom-right">
  Widget position on the page.

  **Options**: `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"`

  ```javascript theme={null}
  position: "bottom-right"
  ```
</ParamField>

<ParamField path="buttonText" type="string" default="Chat with us">
  Text displayed on the chat button.

  ```javascript theme={null}
  buttonText: "💬 Need Help?"
  ```
</ParamField>

<ParamField path="environment" type="string" default="production">
  API environment to use.

  **Options**: `"staging"`, `"production"`, `"custom"`

  ```javascript theme={null}
  environment: "production"
  ```
</ParamField>

## Authentication & Session

<ParamField path="sessionId" type="string">
  Unique session identifier for the user.

  If not provided, auto-generated. Use for persistent conversations across page loads.

  ```javascript theme={null}
  sessionId: "user-12345"
  ```
</ParamField>

<ParamField path="authToken" type="string">
  Optional authentication token for authenticated users.

  ```javascript theme={null}
  authToken: "bearer-token-here"
  ```
</ParamField>

<ParamField path="customBaseApiUri" type="string">
  Custom API base URL (only when `environment` is `"custom"`).

  ```javascript theme={null}
  environment: "custom",
  customBaseApiUri: "https://your-api.com"
  ```
</ParamField>

## Display Configuration

<ParamField path="displayMode" type="string" default="floating">
  How the widget is displayed.

  **Options**: `"floating"`, `"embedded"`

  ```javascript theme={null}
  displayMode: "floating" // or "embedded"
  ```
</ParamField>

<ParamField path="draggable" type="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"`.

  ```javascript theme={null}
  displayMode: "floating",
  draggable: true
  ```
</ParamField>

<ParamField path="embeddedDisplayConfig" type="object">
  Configuration for embedded mode. Required when `displayMode` is `"embedded"`.

  ```typescript theme={null}
  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:**

  ```javascript theme={null}
  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
  }
  ```
</ParamField>

<ParamField path="chatWindowHeight" type="string | number" default="500px">
  Height of the chat window.

  ```javascript theme={null}
  chatWindowHeight: "600px"  // or 600
  ```
</ParamField>

<ParamField path="chatWindowWidth" type="string | number" default="350px">
  Width of the chat window.

  ```javascript theme={null}
  chatWindowWidth: "400px"  // or 400
  ```
</ParamField>

## Visual Customization

<ParamField path="buttonColor" type="string" default="#007bff">
  Background color of the chat button.

  ```javascript theme={null}
  buttonColor: "#28a745"
  ```
</ParamField>

<ParamField path="buttonIcon" type="string" default="💬">
  Icon or emoji displayed on the button.

  ```javascript theme={null}
  buttonIcon: "🤖"
  ```
</ParamField>

<ParamField path="chatTitle" type="string" default="Chat">
  Title displayed in the chat header.

  ```javascript theme={null}
  chatTitle: "Customer Support"
  ```
</ParamField>

<ParamField path="chatInputPlaceholder" type="string" default="Ask anything, about anything">
  Placeholder text for the input field.

  ```javascript theme={null}
  chatInputPlaceholder: "How can we help you today?"
  ```
</ParamField>

<ParamField path="welcomeMessage" type="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.

  ```javascript theme={null}
  welcomeMessage: "Hello! How can we assist you today?"
  ```
</ParamField>

## Advanced Styling

<ParamField path="popupButtonStyles" type="React.CSSProperties">
  Custom CSS styles for the chat button.

  ```javascript theme={null}
  popupButtonStyles: {
    borderRadius: "50%",
    width: "60px",
    height: "60px",
    fontSize: "24px",
    boxShadow: "0 4px 12px rgba(0,0,0,0.15)"
  }
  ```
</ParamField>

<ParamField path="popupButtonPositionalContainerStyles" type="React.CSSProperties">
  Custom CSS styles for button positioning.

  ```javascript theme={null}
  popupButtonPositionalContainerStyles: {
    bottom: "20px",
    right: "20px",
    zIndex: "9999"
  }
  ```
</ParamField>

<ParamField path="chatTitleHeaderStyles" type="React.CSSProperties">
  Custom CSS styles for the chat header.

  ```javascript theme={null}
  chatTitleHeaderStyles: {
    background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
    color: "white",
    borderRadius: "10px 10px 0 0"
  }
  ```
</ParamField>

## Branding

<ParamField path="chatHeaderSubtitle" type="object">
  Subtitle configuration for branding.

  ```typescript theme={null}
  chatHeaderSubtitle: {
    visible: boolean;
    brandName?: string;
    iconUrl?: string;
    linkUrl?: string;
  }
  ```

  **Example:**

  ```javascript theme={null}
  chatHeaderSubtitle: {
    visible: true,
    brandName: "Your Company",
    iconUrl: "https://yoursite.com/logo.png",
    linkUrl: "https://yoursite.com"
  }
  ```
</ParamField>

## Advanced Features

<ParamField path="voiceModeEnabled" type="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](/chat-widget/voice-chat) for details.

  ```javascript theme={null}
  voiceModeEnabled: true
  ```
</ParamField>

<ParamField path="microphoneEnabled" type="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.

  ```javascript theme={null}
  microphoneEnabled: true
  ```
</ParamField>

<ParamField path="attachmentsEnabled" type="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.

  ```javascript theme={null}
  attachmentsEnabled: true
  ```
</ParamField>

<ParamField path="disablePreviewOnLinks" type="boolean" default={false}>
  Disable automatic link previews.

  ```javascript theme={null}
  disablePreviewOnLinks: true
  ```
</ParamField>

<ParamField path="runtimeContext" type="string">
  Additional context passed to the AI agent.

  Useful for providing page context, user roles, etc.

  ```javascript theme={null}
  runtimeContext: "page:pricing,user:premium,lang:en"
  ```
</ParamField>

## Event Handlers

<ParamField path="onNavigate" type="function">
  Handler for navigation events from the chat.

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

  **Example:**

  ```javascript theme={null}
  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);
  }
  ```
</ParamField>

## Complete Example

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="Use Staging for Testing">
    Always test new configurations with staging first:

    ```javascript theme={null}
    environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging'
    ```
  </Accordion>

  <Accordion title="Generate Unique Session IDs">
    Create unique sessions for better tracking:

    ```javascript theme={null}
    sessionId: `user-${userId}-${Date.now()}`
    ```
  </Accordion>

  <Accordion title="Use Runtime Context">
    Pass page context to help the AI provide better responses:

    ```javascript theme={null}
    runtimeContext: `page:${window.location.pathname},lang:${document.documentElement.lang}`
    ```
  </Accordion>

  <Accordion title="Responsive Configuration">
    Adjust for different screen sizes:

    ```javascript theme={null}
    const isMobile = window.innerWidth <= 768;

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Styling Guide" icon="palette" href="/chat-widget/styling">
    Customize colors, fonts, and appearance
  </Card>

  <Card title="Events API" icon="bolt" href="/chat-widget/events">
    Listen to chat events and interactions
  </Card>

  <Card title="Examples" icon="layer-group" href="/chat-widget/examples">
    See real-world configurations
  </Card>

  <Card title="Framework Integration" icon="code" href="/chat-widget/frameworks">
    React, Vue, Angular guides
  </Card>
</CardGroup>