Skip to main content

​
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.
embeddedDisplayConfig: {
  targetContainerId: string; // ID of container element
}
Example:
displayMode: "embedded",
embeddedDisplayConfig: {
  targetContainerId: "my-chat-container"
}
​
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

​
popupButtonStyles
React.CSSProperties
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)"
}
​
popupButtonPositionalContainerStyles
React.CSSProperties
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.
voiceModeEnabled: 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,
  disablePreviewOnLinks: false,
  runtimeContext: "page:home",
  
  // Events
  onNavigate: (pathname, options) => {
    console.log('Navigate:', pathname);
  }
});

​
Configuration Tips

Always test new configurations with staging first:
environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging'
Create unique sessions for better tracking:
sessionId: `user-${userId}-${Date.now()}`
Pass page context to help the AI provide better responses:
runtimeContext: `page:${window.location.pathname},lang:${document.documentElement.lang}`
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