Widget Configuration

Customize the LILA chat widget appearance and behavior. This page covers every configuration option available. Change the position, theme, size, and authentication mode to match your application’s design and security requirements.

Basic Configuration

The minimum configuration requires your API key and JWT token:

<script type="module" src="https://embed.getlila.one/loader.js"></script>
<lila-widget
  api-key="your-api-key"
  jwt-token="your-jwt-token">
</lila-widget>

All Configuration Attributes

Complete attribute reference for the LILA widget.

Authentication

Choose either JWT authentication or basic authentication.

JWT Authentication (Production)

Required attributes:

User details (user_id, role, email, name, tenant_id) are extracted from the JWT payload.

Basic Authentication (Development/Testing)

Required attributes:

Optional attributes:

Note: JWT authentication is recommended for production. Basic authentication is suitable for testing and development.

Appearance & Layout

Configuration Examples

Minimal Setup (Testing)

<lila-widget
  api-key="your-api-key"
  user-id="test-user">
</lila-widget>

Basic Authentication with User Details

<lila-widget
  api-key="your-api-key"
  user-id="user_12345"
  user-role="customer"
  user-email="[email protected]"
  user-name="John Doe">
</lila-widget>

JWT Authentication (Production)

<lila-widget
  api-key="your-api-key"
  jwt-token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...">
</lila-widget>

The JWT token should include user information in the payload:

{
  "user_id": "user_12345",
  "user_role": "customer",
  "user_email": "[email protected]",
  "user_name": "John Doe"
}

See JWT Authentication Guide for complete implementation details including token generation examples.

Custom Position & Drawer

<!-- Widget on right, drawer slides from left -->
<lila-widget
  api-key="your-api-key"
  position="right"
  drawer-mode="left">
</lila-widget>

<!-- Widget on left, drawer slides from bottom -->
<lila-widget
  api-key="your-api-key"
  position="left"
  drawer-mode="bottom">
</lila-widget>

Dark Theme

<lila-widget
  api-key="your-api-key"
  theme="dark">
</lila-widget>

Custom Size

<lila-widget
  api-key="your-api-key"
  width="500px"
  height="700px">
</lila-widget>

Full Configuration Example

<lila-widget
  api-key="your-api-key"
  jwt-token="<?php echo $jwtToken; ?>"
  position="right"
  drawer-mode="right"
  theme="light"
  width="450px"
  height="90vh">
</lila-widget>

Understanding Position vs Drawer Mode

Position and drawer-mode control different aspects of the widget:

Position (left or right)

Controls where the widget launcher appears on the page:

• left - Launcher appears in bottom-left corner
• right - Launcher appears in bottom-right corner

Drawer Mode (left, right, or bottom)

Controls where the sessions drawer slides from when opened:

• left - Drawer slides in from the left side
• right - Drawer slides in from the right side
• bottom - Drawer slides up from the bottom

Common Combinations:

<!-- Widget on right, drawer from right (default feel) -->
<lila-widget position="right" drawer-mode="right"></lila-widget>

<!-- Widget on left, drawer from left (mirrored) -->
<lila-widget position="left" drawer-mode="left"></lila-widget>

<!-- Widget on right, drawer from bottom (mobile-like) -->
<lila-widget position="right" drawer-mode="bottom"></lila-widget>

JavaScript API

Dynamic Configuration Updates

Update widget attributes dynamically using standard Web Components API:

const widget = document.querySelector('lila-widget');

// Update theme
widget.setAttribute('theme', 'dark');

// Update JWT token (for session refresh)
widget.setAttribute('jwt-token', newToken);

// Update drawer mode
widget.setAttribute('drawer-mode', 'bottom');

Security Best Practices

API Key Protection

• ✅ API keys can be safely exposed in frontend code
• ✅ Rate limiting and domain restrictions are enforced server-side
• ❌ Never commit API keys to public repositories

Configure allowed domains in your Dashboard → Project Settings → Security.

JWT Authentication

For production environments with user authentication, generate JWT tokens server-side and pass them to the widget:

<lila-widget
  api-key="your-api-key"
  jwt-token="<?php echo $jwtToken; ?>">
</lila-widget>

Complete JWT implementation guides:

• JWT Authentication Overview - Security concepts and best practices
• JWT with JavaScript - Node.js and frontend implementation
• JWT with PHP - PHP and Laravel implementation

These guides cover token generation, payload structure, and security best practices.

Troubleshooting

LILA widget troubleshooting. Check these common issues.

Widget Not Loading

1. Check browser console for errors
2. Verify API key is correct
3. Ensure script tag is loaded:

   <script type="module" src="https://embed.getlila.one/loader.js"></script>

4. Check network tab for blocked requests
5. Verify your domain is whitelisted in Dashboard settings

Authentication Errors

JWT Authentication:

1. Verify JWT token is valid and not expired
2. Check JWT secret matches project settings in Dashboard
3. Ensure token payload includes required fields (user_id)

Basic Authentication:

1. Verify user-id attribute is set correctly
2. Check browser console for connection errors

Sessions Not Persisting

1. Verify user_id is consistent across page loads
2. Check browser console for WebSocket connection errors
3. Ensure cookies/localStorage are enabled

Drawer Not Opening

1. Check that drawer-mode attribute is valid (left, right, or bottom)
2. Verify no JavaScript errors in console
3. Try different drawer-mode values
4. Check for conflicting z-index CSS on your page

Keyboard Shortcuts

The widget supports these keyboard shortcuts:

• ESC - Close settings panel or rename input (if active), then close drawer
• Enter - Send message (in chat input) or save session rename

Responsive Behavior

The widget automatically adapts to mobile screens:

• Desktop: Full width/height as configured
• Mobile: Expands to fit available screen space
• Drawer modes: Bottom drawer recommended for mobile devices

Next Steps

• Quick Start Guide - Get widget running in 2 minutes
• HTML Integration - Advanced JavaScript integration
• WordPress Guide - WooCommerce integration
• Laravel Guide - PHP/Laravel with JWT
• Authentication - Secure JWT implementation