Configuration

Complete reference for all Lingu widget configuration options.

Configuration Object

Set the configuration before loading the widget script:

<script>
  window.linguConfig = {
    apiKey: 'your-api-key-here',
    baseURL: 'https://api.uselingu.app/api',
    autoOpen: false
  };
</script>
<script src="https://widget.uselingu.app/widget.js"></script>

Options Reference

Option	Type	Required	Default	Description
apiKey	string	Yes	–	Your unique widget API key from the dashboard
baseURL	string	No	https://api.uselingu.app/api	API endpoint URL
autoOpen	boolean	No	false	Automatically open the chat window on page load

apiKey

Required. Your unique API key that identifies your chatbot and organization.

window.linguConfig = {
  apiKey: 'lingu_abc123def456ghi789jkl'
};

Getting Your API Key

1. Log in to Lingu Dashboard
2. Go to Settings → Widget Integration
3. Copy your Widget API Key

baseURL

Optional. The API endpoint for the widget to connect to. Only change this if you're using a self-hosted Lingu instance or a custom API endpoint.

window.linguConfig = {
  apiKey: 'your-api-key',
  baseURL: 'https://your-custom-api.example.com/api'
};

autoOpen

Optional. When set to true, the chat window opens automatically when the page loads.

window.linguConfig = {
  apiKey: 'your-api-key',
  autoOpen: true  // Opens chat on page load
};

Use cases for autoOpen: true:

• Dedicated support pages
• First-time visitor onboarding
• Promotional campaigns

Dashboard Configuration

Most visual and behavioral settings are configured through your Lingu Dashboard, not in code. This allows you to update settings without redeploying your website.

Settings Available in Dashboard

Category	Settings
Appearance	Primary color, background color, text color
Position	Bottom-right, bottom-left, top-right, top-left
Size	Small, medium, large
Theme	Light, dark, or follow system
Branding	Logo, brand name, welcome message
Behavior	Greeting message, fallback responses
AI Settings	Response style, tone, language

Changes Apply Instantly

When you update settings in the dashboard, they apply to all widgets using that API key immediately. No code changes or redeployment required.

Feature Configuration

These features are automatically enabled and managed by the widget:

Session Management

• Auto-creation: Sessions are created when users first interact
• Heartbeat: Active sessions send periodic heartbeats to stay alive
• Auto-timeout: Sessions end after 15 minutes of inactivity
• Message History: Conversations are preserved during the session

Typing Indicators

Shows "AI is typing..." when the AI is generating a response.

Timestamps

Messages display relative timestamps (e.g., "2 minutes ago").

Unread Indicators

When minimized, the widget shows a badge with unread message count.

TypeScript Interface

For TypeScript projects, here's the complete type definition:

interface LinguConfig {
  /**
   * Your unique widget API key
   * @required
   */
  apiKey: string;

  /**
   * API endpoint URL
   * @default 'https://api.uselingu.app/api'
   */
  baseURL?: string;

  /**
   * Automatically open chat on page load
   * @default false
   */
  autoOpen?: boolean;
}

declare global {
  interface Window {
    linguConfig?: LinguConfig;
  }
}

Example Configurations

Basic Setup

window.linguConfig = {
  apiKey: 'lingu_abc123'
};

Auto-Open Support Page

window.linguConfig = {
  apiKey: 'lingu_abc123',
  autoOpen: true  // Perfect for /support or /help pages
};

Custom API Endpoint

window.linguConfig = {
  apiKey: 'lingu_abc123',
  baseURL: 'https://api.staging.uselingu.app/api'  // Staging environment
};

Validation

The widget validates your configuration on load:

• Missing apiKey → Warning in console, widget won't initialize
• Invalid apiKey → Error from API, chat won't work
• Invalid baseURL → Network errors, API calls will fail