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

# Configuration

> Complete reference for SDK configuration options

## Overview

The AI Chat SDK provides extensive configuration options to control features, customize appearance, and integrate with your data sources. All configuration is passed during SDK initialization.

## Initialization signature

```typescript theme={null}
function initializeAiChatSdk(
  apiKey: string,
  options?: Partial<AiChatSdkOptions>,
  listeners?: AiChatSdkEventListener[]
): Sdk
```

## Required parameters

### apiKey

**Type**: `string`

Your API key for authentication with the chat backend.

```typescript theme={null}
import { initializeAiChatSdk } from '@sleek/ai-chat-sdk';

initializeAiChatSdk('your-api-key', {
  // ... options
});
```

<Note>
  Contact [support@onsleek.com](mailto:support@onsleek.com) to receive your API key.
</Note>

## Configuration options

### enableDebug

Enable detailed console logging for debugging.

```typescript theme={null}
enableDebug?: boolean;  // Default: false
```

**Example**:

```typescript theme={null}
enableDebug: true,  // Enable console.log statements from SDK
```

<Note>
  Debug mode should be disabled in production builds to reduce console noise and improve performance.
</Note>

## Chat configuration

Configure the chat panel behavior, styling, and content using `chatConfig`.

```typescript theme={null}
chatConfig?: {
  usePageContext?: boolean;
  messageLimitPerThread?: number;
  isFloating?: boolean;
  content?: ChatContentConfig;
  assistant?: AssistantConfig;
  brand?: BrandConfig;
  styling?: StylingConfig;
  layout?: FixedLayoutConfig;
}
```

### isFloating

Applies floating panel styles (border, border-radius, box shadow) when enabled. Set to `false` for a flat/embedded appearance.

```typescript theme={null}
chatConfig: {
  isFloating: true,  // Default: true
}
```

### usePageContext

When enabled, the AI can reference and respond based on what the user is currently viewing on the page.

```typescript theme={null}
chatConfig: {
  usePageContext: true,  // Default: false
}
```

### messageLimitPerThread

Maximum number of messages per conversation thread.

```typescript theme={null}
chatConfig: {
  messageLimitPerThread: 50,
}
```

### content

Customize text content displayed in the chat interface.

```typescript theme={null}
chatConfig: {
  content: {
    // Header customization (logo and name in chat header)
    // Falls back to brand config if not provided
    header: {
      logo: <YourLogoComponent />,  // React node for custom logo (falls back to brand.logo)
      logoUrl: 'https://example.com/logo.png',  // Or URL for logo image (falls back to brand.logoUrl)
      name: 'Your Brand AI',  // Brand name displayed in header (falls back to brand.name)
    },

    // Default prompt suggestions shown to users
    defaultPrompts: ['Show me deals', 'Compare prices', 'Find discounts'],

    // Disclaimer text shown in the chat
    disclaimerText: 'AI responses may not always be accurate',

    // Hide provider attribution
    excludeProviderAttribution: false,

    // Error message customization
    error: {
      message: 'Unable to connect. Please try again.',
    },

    // Input field customization
    input: {
      placeholder: 'Type your message...',
    },

    // Intro screen customization
    intro: {
      title: 'Welcome!',
      message: 'How can I help you today?',
    },

    // Loading messages (cycles through array)
    loading: {
      messages: ['Thinking...', 'Finding the best options...', 'Almost there...'],
    },

    // Rate limit message
    rateLimit: {
      message: 'Please wait before sending another message.',
    },

    // Reload prompt customization
    reload: {
      message: 'Context has changed.',
      action: 'Reload chat',
    },
  },
}
```

### assistant

Configure the AI assistant's identity.

```typescript theme={null}
chatConfig: {
  assistant: {
    name: 'Shopping Assistant',
    description: 'Your AI shopping helper',
    settingsUrl: 'https://example.com/settings',
  },
}
```

### brand

Configure your brand identity.

```typescript theme={null}
chatConfig: {
  brand: {
    name: 'Your Brand',
    logoUrl: 'https://your-app.com/logo.png',
    // Or use a React component for logo
    // logo: <YourLogoComponent />,
  },
}
```

### styling

Configure colors and fonts. See the [Customization guide](/sdk/customization) for details.

```typescript theme={null}
chatConfig: {
  styling: {
    primaryColor: '#5C59FE',
    primaryColorDarkMode: '#8B87FF',
    colorMode: 'system',  // 'light' | 'dark' | 'system'
  },
}
```

### layout

Configure the chat panel's position and size. See [Layout configuration](#layout-configuration) below.

## Badge configuration

Configure the floating badge entry point using `badgeConfig`.

```typescript theme={null}
badgeConfig?: {
  usePageContext?: boolean;
  allowExpand?: boolean;
  autoCollapse?: boolean;
  restoreBadgeOnChatClose?: boolean;
  content?: BadgeContentConfig;
  assistant?: AssistantConfig;
  brand?: BrandConfig;
  styling?: StylingConfig;
  layout?: FixedLayoutConfig;
}
```

### allowExpand

Whether the badge can expand on hover to show prompts.

```typescript theme={null}
badgeConfig: {
  allowExpand: true,  // Default: true
}
```

### autoCollapse

Whether the badge automatically collapses after a delay.

```typescript theme={null}
badgeConfig: {
  autoCollapse: true,  // Default: true
}
```

### restoreBadgeOnChatClose

Whether to restore the badge after the user closes the chat dialog. When enabled, the badge reappears instantly without requiring a page refresh or additional SDK call. Only applies if the badge was previously shown. If the user explicitly dismisses the badge (via the close button), it will not be restored after chat close.

```typescript theme={null}
badgeConfig: {
  restoreBadgeOnChatClose: true,  // Default: false
}
```

### content

Customize badge text content.

```typescript theme={null}
badgeConfig: {
  content: {
    badge: {
      text: 'Ask AI',
    },
    onboarding: {
      title: 'Need help?',
      description: 'Click here to chat with our AI assistant',
    },
  },
}
```

## Inline configuration

Configure the inline input entry point using `inlineConfig`.

```typescript theme={null}
inlineConfig?: {
  usePageContext?: boolean;
  content?: InlineContentConfig;
  assistant?: AssistantConfig;
  brand?: BrandConfig;
  styling?: StylingConfig;
  layout?: InlineLayoutConfig;
}
```

### layout (inline)

For inline rendering, you must specify a container selector.

```typescript theme={null}
inlineConfig: {
  layout: {
    containerSelector: '#chat-container',
    insertPosition: 'append',  // 'append' | 'prepend'
  },
}
```

### content

Customize inline input text.

```typescript theme={null}
inlineConfig: {
  content: {
    input: {
      placeholder: 'Ask me anything...',
    },
  },
}
```

## Layout configuration

Control positioning and sizing for chat panel and badge.

### Position

```typescript theme={null}
layout: {
  position: {
    top: 'unset',     // Default: 'unset'
    right: '0px',     // Default: '0px'
    bottom: '0px',    // Default: '0px'
    left: 'unset',    // Default: 'unset'
  },
}
```

### Size

```typescript theme={null}
layout: {
  size: {
    minWidth: 'auto',
    width: '400px',
    maxWidth: 'none',
    minHeight: 'auto',
    height: '100vh',
    maxHeight: 'none',
  },
}
```

### Common layout examples

<Tabs>
  <Tab title="Right sidebar">
    ```typescript theme={null}
    layout: {
      position: {
        right: '0px',
        bottom: '0px',
      },
      size: {
        width: '400px',
        height: '100vh',
      },
    }
    ```
  </Tab>

  <Tab title="Floating window">
    ```typescript theme={null}
    layout: {
      position: {
        right: '20px',
        bottom: '20px',
      },
      size: {
        width: '380px',
        height: '600px',
      },
    }
    ```
  </Tab>

  <Tab title="Bottom panel">
    ```typescript theme={null}
    layout: {
      position: {
        left: '0px',
        bottom: '0px',
      },
      size: {
        width: '100vw',
        height: '400px',
      },
    }
    ```
  </Tab>
</Tabs>

## Data providers

Integrate your offer redirect URLs and cashback data into chat conversations. See the [Data Providers guide](/sdk/data-providers) for detailed implementation.

```typescript theme={null}
dataProviders: {
  offerRedirectUrlProvider?: OfferRedirectUrlProvider;
  merchantCashbackProvider?: MerchantCashbackProvider;
}
```

**Type definitions**:

```typescript theme={null}
type OfferRedirectUrlProvider = (
  url: string
) => Promise<string | null | undefined> | string | null | undefined;

type MerchantCashbackProvider = (
  merchantUrls: string[]
) => Promise<Record<string, MerchantCashback>> | Record<string, MerchantCashback>;

interface MerchantCashback {
  text: string;  // e.g., "5% cash back", "Up to $10 back"
}
```

**Example**:

```typescript theme={null}
dataProviders: {
  offerRedirectUrlProvider: async (url) => {
    try {
      const response = await fetch(`https://api.example.com/offer?url=${encodeURIComponent(url)}`);
      const data = await response.json();
      return data.offerUrl || null;
    } catch (error) {
      console.error('Failed to fetch offer URL:', error);
      return null;
    }
  },
  merchantCashbackProvider: async (urls) => {
    try {
      const response = await fetch('https://api.example.com/cashback', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ urls }),
      });
      const data = await response.json();
      return data.cashback || {};
    } catch (error) {
      console.error('Failed to fetch cashback:', error);
      return {};
    }
  },
}
```

<Warning>
  Data providers must handle errors gracefully and return `null` (for offer redirect URLs) or `{}` (for cashback) on failure. Never throw exceptions.
</Warning>

## Complete configuration example

Here's a complete example with all commonly used options:

```typescript theme={null}
import {
  initializeAiChatSdk,
  type AiChatSdkOptions,
} from '@sleek/ai-chat-sdk';

const sdk = initializeAiChatSdk('your-api-key', {
  // Debug mode (development only)
  enableDebug: process.env.NODE_ENV === 'development',

  // Chat panel configuration
  chatConfig: {
    usePageContext: true,
    messageLimitPerThread: 50,
    isFloating: true,

    // Assistant identity
    assistant: {
      name: 'Shopping Assistant',
      description: 'Find the best deals and products',
    },

    // Branding
    brand: {
      name: 'Your Brand',
      logoUrl: 'https://your-app.com/logo.png',
    },

    // Colors and fonts
    styling: {
      primaryColor: '#5C59FE',
      primaryColorDarkMode: '#8B87FF',
      colorMode: 'system',
    },

    // Content customization
    content: {
      header: {
        logoUrl: 'https://your-app.com/header-logo.png',
        name: 'Shopping Assistant',
      },
      defaultPrompts: ['Show me deals', 'Compare prices'],
      disclaimerText: 'AI responses may not always be accurate',
      input: {
        placeholder: 'Ask about products...',
      },
      intro: {
        title: 'Welcome!',
        message: 'How can I help you find what you need?',
      },
    },

    // Layout
    layout: {
      position: {
        right: '0px',
        bottom: '0px',
      },
      size: {
        width: '400px',
        height: '100vh',
      },
    },
  },

  // Badge configuration
  badgeConfig: {
    usePageContext: true,
    allowExpand: true,
    autoCollapse: true,
    restoreBadgeOnChatClose: false,
    content: {
      badge: {
        text: 'Ask AI',
      },
    },
    layout: {
      position: {
        right: '20px',
        bottom: '20px',
      },
    },
  },

  // Inline input configuration
  inlineConfig: {
    usePageContext: true,
    layout: {
      containerSelector: '#chat-input-container',
    },
    content: {
      input: {
        placeholder: 'Type a question...',
      },
    },
  },

  // Data providers
  dataProviders: {
    offerRedirectUrlProvider: async (url) => {
      // Your implementation
      return null;
    },
    merchantCashbackProvider: async (urls) => {
      // Your implementation
      return {};
    },
  },
}, [
  // Event listeners
  (event) => {
    console.log('SDK Event:', event.type, event.data);
  }
]);
```

## Environment-specific configuration

For different environments (development, staging, production), use environment variables:

```typescript theme={null}
const config = {
  enableDebug: process.env.NODE_ENV === 'development',
  chatConfig: {
    messageLimitPerThread: process.env.NODE_ENV === 'production' ? 50 : 100,
    apiBaseUrl: process.env.API_BASE_URL,
  },
  // ... rest of config
};

initializeAiChatSdk(process.env.API_KEY!, config);
```

## Type reference

All configuration types are exported from the SDK:

```typescript theme={null}
import type {
  AiChatSdkOptions,
  AssistantConfig,
  BrandConfig,
  StylingConfig,
  FixedLayoutConfig,
  InlineLayoutConfig,
  LayoutPosition,
  LayoutSize,
  BadgeContent,
  BadgeOnboardingContent,
  ChatErrorContent,
  ChatHeaderContent,
  ChatInputContent,
  ChatIntroContent,
  ChatLoadingContent,
  ChatRateLimitContent,
  ChatReloadContent,
  InlineInputContent,
  ClientDataProviders,
  OfferRedirectUrlProvider,
  MerchantCashbackProvider,
  MerchantCashback,
} from '@sleek/ai-chat-sdk';
```