Configuration

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

function initializeAiChatSdk(
  apiKey: string,
  options?: Partial<AiChatSdkOptions>,
  listeners?: AiChatSdkEventListener[]
): Sdk

Required parameters

apiKey

Type: string Your API key for authentication with the chat backend.

import { initializeAiChatSdk } from '@sleek/ai-chat-sdk';

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

Contact support@onsleek.com to receive your API key.

Configuration options

enableDebug

Enable detailed console logging for debugging.

enableDebug?: boolean;  // Default: false

Example:

enableDebug: true,  // Enable console.log statements from SDK

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

Chat configuration

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

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.

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.

chatConfig: {
  usePageContext: true,  // Default: false
}

messageLimitPerThread

Maximum number of messages per conversation thread.

chatConfig: {
  messageLimitPerThread: 50,
}

content

Customize text content displayed in the chat interface.

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.

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

brand

Configure your brand identity.

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 for details.

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

layout

Configure the chat panel’s position and size. See Layout configuration below.

Badge configuration

Configure the floating badge entry point using badgeConfig.

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.

badgeConfig: {
  allowExpand: true,  // Default: true
}

autoCollapse

Whether the badge automatically collapses after a delay.

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.

badgeConfig: {
  restoreBadgeOnChatClose: true,  // Default: false
}

content

Customize badge text content.

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.

inlineConfig?: {
  usePageContext?: boolean;
  content?: InlineContentConfig;
  assistant?: AssistantConfig;
  brand?: BrandConfig;
  styling?: StylingConfig;
  layout?: InlineLayoutConfig;
}

layout (inline)

For inline rendering, you must specify a container selector.

inlineConfig: {
  layout: {
    containerSelector: '#chat-container',
    insertPosition: 'append',  // 'append' | 'prepend'
  },
}

content

Customize inline input text.

inlineConfig: {
  content: {
    input: {
      placeholder: 'Ask me anything...',
    },
  },
}

Layout configuration

Control positioning and sizing for chat panel and badge.

Position

layout: {
  position: {
    top: 'unset',     // Default: 'unset'
    right: '0px',     // Default: '0px'
    bottom: '0px',    // Default: '0px'
    left: 'unset',    // Default: 'unset'
  },
}

Size

layout: {
  size: {
    minWidth: 'auto',
    width: '400px',
    maxWidth: 'none',
    minHeight: 'auto',
    height: '100vh',
    maxHeight: 'none',
  },
}

Common layout examples

Right sidebar
Floating window
Bottom panel

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

layout: {
  position: {
    right: '20px',
    bottom: '20px',
  },
  size: {
    width: '380px',
    height: '600px',
  },
}

layout: {
  position: {
    left: '0px',
    bottom: '0px',
  },
  size: {
    width: '100vw',
    height: '400px',
  },
}

Data providers

Integrate your offer redirect URLs and cashback data into chat conversations. See the Data Providers guide for detailed implementation.

dataProviders: {
  offerRedirectUrlProvider?: OfferRedirectUrlProvider;
  merchantCashbackProvider?: MerchantCashbackProvider;
}

Type definitions:

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:

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 {};
    }
  },
}

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

Complete configuration example

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

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:

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:

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';

​Overview

​Initialization signature

​Required parameters

​apiKey

​Configuration options

​enableDebug

​Chat configuration

​isFloating

​usePageContext

​messageLimitPerThread

​content

​assistant

​brand

​styling

​layout

​Badge configuration

​allowExpand

​autoCollapse

​restoreBadgeOnChatClose

​content

​Inline configuration

​layout (inline)

​content

​Layout configuration

​Position

​Size

​Common layout examples

​Data providers

​Complete configuration example

​Environment-specific configuration

​Type reference

Overview

Initialization signature

Required parameters

apiKey

Configuration options

enableDebug

Chat configuration

isFloating

usePageContext

messageLimitPerThread

content

assistant

brand

styling

layout

Badge configuration

allowExpand

autoCollapse

restoreBadgeOnChatClose

content

Inline configuration

layout (inline)

content

Layout configuration

Position

Size

Common layout examples

Data providers

Complete configuration example

Environment-specific configuration

Type reference