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

# Quick Start

> Get LuaPop running on your website in 2 minutes

## Before You Start: Whitelist Your Website

<Warning>
  **You must whitelist your domain before the widget will load.** In the [Lua AI admin dashboard](https://admin.heylua.ai/), go to **Chat Widget** → **Customization** and add your website URL to the allowed sites list. The widget silently refuses to initialise on any domain not listed here.
</Warning>

<Warning>
  **Testing on localhost?** `localhost` cannot be whitelisted — the dashboard approach will not work. You must pass your configuration inline and set `environment: "production"` explicitly:

  ```html theme={null}
  <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
  <script>
    window.LuaPop.init({
      agentId: "your-agent-id",
      environment: "production"
    });
  </script>
  ```

  This bypasses the domain whitelist check so you can develop and test locally against your real agent.
</Warning>

## Setup Options

There are two ways to get the widget running. The **dashboard approach** is recommended — it requires no code changes when you update settings.

<Tabs>
  <Tab title="Dashboard (Recommended)">
    Configure everything from the Lua AI admin dashboard and embed a single script with no payload.

    <Steps>
      <Step title="Whitelist your site">
        In the admin dashboard, go to **Chat Widget** → **Customization** and add your website URL(s) to the allowed sites list. The widget will only load on whitelisted domains.
      </Step>

      <Step title="Configure in the dashboard">
        Set your agent behavior, appearance, and features directly in the dashboard UI — no code required.
      </Step>

      <Step title="Add the script">
        Copy and paste this code right before the closing `</body>` tag:

        ```html theme={null}
        <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
        <script>
          window.LuaPop.init();
        </script>
        ```
      </Step>

      <Step title="Test">
        Refresh your page — the chat button will appear using your dashboard settings.
      </Step>
    </Steps>

    <Check>
      **That's it!** Update appearance or behavior any time from the dashboard — no code deploys needed. ✨
    </Check>

    <Info>
      **Configuration priority:** If you pass options to `window.LuaPop.init({...})`, those values override the dashboard settings. To use dashboard settings exclusively, call `window.LuaPop.init()` with no arguments.
    </Info>
  </Tab>

  <Tab title="Inline Config">
    Pass configuration directly in the script for full programmatic control, or to override specific dashboard values. **This is also required when testing on localhost.**

    <Steps>
      <Step title="Add the Script">
        Copy and paste this code right before the closing `</body>` tag:

        ```html theme={null}
        <script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
        <script>
          window.LuaPop.init({
            agentId: "your-agent-id",
            environment: "production",
            position: "bottom-right",
            buttonText: "Chat with AI"
          });
        </script>
        ```
      </Step>

      <Step title="Replace Agent ID">
        Get your agent ID from the [Lua AI admin dashboard](https://admin.heylua.ai/) and replace `"your-agent-id"`
      </Step>

      <Step title="Test">
        Refresh your page — you should see a chat button in the bottom-right corner!
      </Step>
    </Steps>

    <Check>
      **That's it!** Your AI chat widget is now live. ✨
    </Check>
  </Tab>
</Tabs>

## Common Setups

### Customer Support

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "support-agent-id",
    chatTitle: "Customer Support",
    buttonText: "💬 Need Help?",
    position: "bottom-right",
    welcomeMessage: "Hi there! 👋 How can we help you today?",
    chatInputPlaceholder: "Describe your issue..."
  });
</script>
```

### Sales Assistant

```html theme={null}
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "sales-agent-id",
    chatTitle: "Sales Assistant",
    buttonText: "💰 Get Quote",
    buttonColor: "#28a745",
    position: "bottom-right"
  });
</script>
```

### Embedded Chat (No Floating Button)

```html theme={null}
<!-- Create a container -->
<div id="chat-container" style="width: 400px; height: 600px;"></div>

<!-- Initialize embedded mode -->
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
<script>
  window.LuaPop.init({
    agentId: "your-agent-id",
    displayMode: "embedded",
    embeddedDisplayConfig: {
      targetContainerId: "chat-container"
    }
  });
</script>
```

## Quick Customizations

### Change Position

<Tabs>
  <Tab title="Bottom Right">
    ```javascript theme={null}
    position: "bottom-right"
    ```
  </Tab>

  <Tab title="Bottom Left">
    ```javascript theme={null}
    position: "bottom-left"
    ```
  </Tab>

  <Tab title="Top Right">
    ```javascript theme={null}
    position: "top-right"
    ```
  </Tab>

  <Tab title="Top Left">
    ```javascript theme={null}
    position: "top-left"
    ```
  </Tab>
</Tabs>

### Custom Colors & Button

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  buttonColor: "#ff6b6b",      // Custom button color
  buttonText: "💬 Chat Now",   // Custom text
  buttonIcon: "🤖",            // Custom icon/emoji
  chatTitle: "AI Assistant"    // Custom title
});
```

## Testing Environments

### Staging (For Testing)

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  environment: "staging", // Uses api.lua.dev
  position: "bottom-right"
});
```

### Production (Live)

```javascript theme={null}
window.LuaPop.init({
  agentId: "your-agent-id",
  environment: "production", // Uses api.heylua.ai
  position: "bottom-right"
});
```

<Warning>
  Always test with `environment: "staging"` before switching to production!
</Warning>

## Framework Integration Quick Start

### React

```tsx theme={null}
import { useEffect } from 'react';

export default function ChatWidget() {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  }, []);

  return null;
}
```

### Vue

```vue theme={null}
<script>
export default {
  mounted() {
    const script = document.createElement('script');
    script.src = 'https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js';
    script.onload = () => {
      window.LuaPop?.init({
        agentId: "your-agent-id",
        position: "bottom-right"
      });
    };
    document.body.appendChild(script);
  }
};
</script>
```

<Card title="More Framework Examples" icon="code" href="/chat-widget/frameworks">
  See integration guides for Angular, Next.js, and more
</Card>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget not appearing?">
    **Check these:**

    1. Open browser console for JavaScript errors
    2. Verify your agent ID is correct
    3. Ensure script is loaded after DOM is ready
    4. Check if another chat widget is conflicting
  </Accordion>

  <Accordion title="Button shows but chat won't open?">
    **Solutions:**

    1. Check your internet connection
    2. Verify agent ID exists in Lua AI dashboard
    3. Try `environment: "staging"` for testing
    4. Check browser console for API errors
  </Accordion>

  <Accordion title="Styling issues?">
    **Solutions:**

    1. Check for CSS conflicts using browser dev tools
    2. Try a different position
    3. Add higher z-index:
       ```javascript theme={null}
       popupButtonStyles: {
         zIndex: "9999"
       }
       ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Full Configuration" icon="cog" href="/chat-widget/configuration">
    Explore all configuration options
  </Card>

  <Card title="Custom Styling" icon="palette" href="/chat-widget/styling">
    Match your brand perfectly
  </Card>

  <Card title="Real Examples" icon="layer-group" href="/chat-widget/examples">
    See production implementations
  </Card>

  <Card title="Track Events" icon="chart-line" href="/chat-widget/analytics">
    Monitor chat interactions
  </Card>
</CardGroup>