Configuring the Design

This guide shows you how to customize the visual appearance and user experience of your ept AI chatbot. After integrating the chatbot, you can configure various design elements to match your brand and optimize user interaction.

Overview

The ept AI chatbot offers extensive customization options for:

• Visual Theme: Colors, fonts, and overall appearance
• Positioning: Where the chatbot appears on your page
• Behavior: How the chatbot interacts with users
• Branding: Logo, messaging, and brand alignment
• Advanced Styling: Custom CSS for complete control

Basic Configuration Options

Theme Configuration

Configure the basic appearance through the eptAIConfig object:

window.eptAIConfig = {
  accessToken: access_token,
  
  // Theme settings
  theme: 'light', // 'light', 'dark', or 'auto'
  primaryColor: '#007bff', // Brand color for buttons and highlights
  accentColor: '#6c757d', // Secondary color for borders and text
  
  // Position settings
  position: 'bottom-right', // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
  margin: '20px', // Distance from edge of screen
  
  // Size settings
  width: '400px', // Chat window width (desktop)
  height: '600px', // Chat window height (desktop)
  mobileWidth: '100%', // Mobile width (usually full screen)
  mobileHeight: '70%', // Mobile height
};

Positioning Options

Choose where your chatbot appears:

Bottom Right (Default)

position: 'bottom-right',
margin: '20px'

• Best for: Most websites, doesn't interfere with main content
• User expectation: Standard position for chat widgets

Bottom Left

position: 'bottom-left',
margin: '20px'

• Best for: Sites with right sidebar content
• Consideration: Less common, may surprise users

Custom Positioning

position: 'custom',
customPosition: {
  bottom: '20px',
  right: '20px',
  zIndex: 1000
}

Advanced Features

Dark Mode Support

The CSS framework automatically supports dark mode based on user preferences:

/* Dark mode honors user preference */
@media (prefers-color-scheme: dark) {
  #eptai-chat-container {
    --ept-bg: #0b0f17; 
    --ept-fg: #e5e7eb; 
    --ept-muted: #9ca3af; 
    --ept-border: #1f2937;
    --ept-bot-bg: #121826; 
    --ept-user-bg: rgba(37, 99, 235, .14);
    --ept-link: #93c5fd;
  }
}

Accessibility Features

Built-in accessibility support for keyboard navigation and reduced motion:

/* Focus styles for keyboard navigation */
#eptai-chat-box :is(button, [role="button"], textarea, input, a):focus-visible {
  outline: 2px solid var(--ept-brand);
  outline-offset: 2px;
}

/* Respect reduced motion preferences */
@media (prefers-reduced-motion: reduce) {
  #eptai-chat-container * { 
    animation-duration: 0.01ms !important; 
    animation-iteration-count: 1 !important; 
    transition-duration: 0.01ms !important; 
  }
  .eptai-typing-animation { 
    animation: none !important; 
  }
}

/* iOS safe-area support */
#eptai-chat-box { 
  padding-bottom: calc(env(safe-area-inset-bottom) + 0px); 
}

Positioning and Layout

Customize the widget position and size:

/* Position options */
#eptai-chat-container { 
  /* Bottom right (default) */
  inset: auto 20px 20px auto; 
  
  /* Bottom left */
  /* inset: auto auto 20px 20px; */
  
  /* Top right */
  /* inset: 20px 20px auto auto; */
  
  /* Top left */
  /* inset: 20px auto auto 20px; */
  
  /* Custom positioning */
  /* position: fixed; */
  /* top: 100px; */
  /* right: 50px; */
}

/* Size customization */
#eptai-chat-box { 
  /* Default size */
  width: min(420px, 92vw); 
  height: min(70vh, 780px);
  
  /* Larger panel */
  /* width: min(500px, 95vw); */
  /* height: min(80vh, 840px); */
  
  /* Smaller panel */
  /* width: min(350px, 90vw); */
  /* height: min(60vh, 600px); */
}

/* Z-index management */
#eptai-chat-container { 
  z-index: 1200; /* Adjust based on your site's stacking context */
}

Responsive Design

The CSS framework includes responsive design by default, but you can customize further:

/* Mobile-specific adjustments */
@media (max-width: 768px) {
  #eptai-chat-container {
    inset: auto 10px 10px auto; /* Smaller margins on mobile */
  }
  
  #eptai-chat-box {
    width: min(95vw, 400px); /* Wider on mobile */
    height: min(80vh, 600px); /* Taller on mobile */
  }
  
  .eptai-default-question {
    font-size: 14px; /* Smaller text on mobile */
    padding: 6px 8px;
  }
}

/* Tablet adjustments */
@media (min-width: 769px) and (max-width: 1024px) {
  #eptai-chat-box {
    width: min(450px, 90vw);
    height: min(75vh, 700px);
  }
}

Advanced Styling

The ept AI chatbot provides extensive CSS customization options. You can style it using either the customStyles property for simple changes or external CSS files for complete control.

CSS Selectors Reference

Before diving into styling, here are the key elements you can target:

Core Container IDs:

• #eptai-chat-container - Main widget container
• #eptai-chat-box - Chat panel/window
• #eptai-chat-messages - Messages area
• #eptai-chat-input - Input field
• #eptai-send-btn - Send button
• #eptai-close-btn - Close button
• #eptai-chat-status - Status indicator

Common Classes:

• .eptai-user-message / .eptai-bot-message - Message containers
• .eptai-default-question - Prompt suggestion chips
• .eptai-typing-animation - Typing indicator
• .eptai-copy-btn / .eptai-copy-code-btn - Copy buttons
• .eptai-feedback-icons - Feedback buttons
• .chat-message-wrap - Message wrapper
• .message-content - Message content area

Quick Customization with customStyles

For simple theme changes, use the customStyles property:

window.eptAIConfig = {
  accessToken: access_token,
  customStyles: `
    /* Chat widget container */
    #eptai-chat-container {
      --ept-brand: #007bff;
      --ept-radius: 12px;
      --ept-shadow: 0 8px 30px rgba(0,0,0,0.12);
    }
    
    /* Message bubbles */
    .eptai-user-message .message-content {
      background: linear-gradient(135deg, #007bff, #0056b3);
      color: white;
      border-radius: 18px 18px 4px 18px;
    }
    
    .eptai-bot-message .message-content {
      background: #f8f9fa;
      color: #212529;
      border-radius: 18px 18px 18px 4px;
      border-left: 3px solid #007bff;
    }
    
    /* Send button */
    #eptai-send-btn {
      background: #007bff;
      border-radius: 50%;
      width: 40px;
      height: 40px;
      transition: all 0.2s ease;
    }
    
    #eptai-send-btn:hover {
      background: #0056b3;
      transform: scale(1.05);
    }
  `
};

Complete CSS Framework

For comprehensive styling control, use this production-ready CSS framework. This approach provides complete control while maintaining accessibility and responsive design:

/* 1) Scope everything to the widget */
#eptai-chat-container, #eptai-chat-container * { 
  box-sizing: border-box; 
  font: inherit; 
}

/* 2) Theme tokens (override these to match your site) */
#eptai-chat-container {
  --ept-font: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial, "Apple Color Emoji", "Segoe UI Emoji";
  --ept-radius: var(--radius-md, 12px);
  --ept-shadow: 0 10px 30px rgba(0,0,0,.12);
  --ept-brand: var(--brand-600, #2b6cb0);
  --ept-brand-contrast: #fff;
  --ept-bg: var(--surface, #ffffff);
  --ept-fg: var(--text, #111827);
  --ept-muted: var(--muted, #6b7280);
  --ept-border: var(--border, #e5e7eb);
  --ept-bot-bg: var(--surface-2, #f8fafc);
  --ept-user-bg: var(--brand-50, #e6f0ff);
  --ept-link: var(--link, #2563eb);
}

/* 3) Container + panel */
#eptai-chat-container { 
  position: fixed; 
  inset: auto 20px 20px auto; 
  z-index: 9999; 
  font-family: var(--ept-font); 
}

#eptai-chat-box {
  background: var(--ept-bg); 
  color: var(--ept-fg);
  width: min(420px, 92vw); 
  height: min(70vh, 780px);
  border: 1px solid var(--ept-border); 
  border-radius: var(--ept-radius); 
  box-shadow: var(--ept-shadow);
  display: flex; 
  flex-direction: column; 
  overflow: hidden;
}

/* 4) Header / Status / Close */
#eptai-chat-status { 
  color: var(--ept-muted); 
  font-size: 12px; 
}

#eptai-close-btn { 
  border: 0; 
  background: transparent; 
  cursor: pointer; 
}

/* 5) Messages */
#eptai-chat-messages { 
  flex: 1 1 auto; 
  overflow: auto; 
  padding: 16px; 
  scroll-behavior: smooth; 
}

.eptai-user-message .message-content {
  background: var(--ept-user-bg); 
  border: 1px solid var(--ept-border);
  border-radius: calc(var(--ept-radius) * .75); 
  padding: 10px 12px;
}

.eptai-bot-message .message-content {
  background: var(--ept-bot-bg); 
  border: 1px solid var(--ept-border);
  border-radius: calc(var(--ept-radius) * .75); 
  padding: 10px 12px;
}

.chat-user-image { 
  width: 28px; 
  height: 28px; 
  border-radius: 50%; 
  overflow: hidden; 
}

/* 6) Links, code, copy buttons */
#eptai-chat-box a { 
  color: var(--ept-link); 
  text-decoration: underline; 
}

.eptai-copy-btn, .eptai-copy-code-btn {
  border: 1px solid var(--ept-border); 
  background: #fff; 
  cursor: pointer; 
  border-radius: 6px; 
  padding: 4px 8px;
}

/* 7) Quick prompts (chips) */
.eptai-default-question {
  display: inline-block; 
  margin: 6px 6px 0 0; 
  padding: 8px 10px;
  border: 1px solid var(--ept-border); 
  border-radius: 999px; 
  background: #fff; 
  color: var(--ept-fg);
  cursor: pointer; 
  transition: transform .06s ease;
}

.eptai-default-question:hover { 
  transform: translateY(-1px); 
}

/* 8) Input row */
#eptai-chat-input {
  resize: none; 
  min-height: 44px; 
  max-height: 160px;
  padding: 12px 14px; 
  border: 1px solid var(--ept-border); 
  border-radius: 10px; 
  background: #fff;
}

#eptai-send-btn {
  background: var(--ept-brand); 
  color: var(--ept-brand-contrast);
  border: 0; 
  border-radius: 10px; 
  padding: 10px 14px; 
  cursor: pointer; 
  font-weight: 600;
}

#eptai-send-btn:disabled { 
  opacity: .5; 
  cursor: not-allowed; 
}

/* 9) Feedback + toasts */
.eptai-feedback-icons { 
  display: inline-flex; 
  gap: 8px; 
}

.eptai-feedback-icon { 
  opacity: .8; 
  cursor: pointer; 
}

.eptai-feedback-icon:hover { 
  opacity: 1; 
}

.eptai-copied-notification, .eptai-copied-notification-2 {
  background: rgba(0,0,0,.8); 
  color: #fff; 
  border-radius: 8px; 
  padding: 6px 10px; 
  font-size: 12px;
}

/* 10) Loader / typing */
#chat-loader-wrap { 
  position: absolute; 
  inset: 0; 
  display: none; 
  align-items: center; 
  justify-content: center; 
  background: rgba(255,255,255,.6); 
}

.eptai-typing-animation { 
  opacity: .7; 
}

/* 11) Focus styles (keyboard a11y) */
#eptai-chat-box :is(button, [role="button"], textarea, input, a):focus-visible {
  outline: 2px solid var(--ept-brand);
  outline-offset: 2px;
}

/* 12) Print */
@media print { 
  #eptai-chat-container { 
    display: none !important; 
  } 
}

Brand Integration

Incorporate your brand elements by overriding the CSS variables:

window.eptAIConfig = {
  accessToken: access_token,
  
  // Branding
  brandName: 'Your Company',
  logo: 'https://yourcompany.com/logo.png',
  
  // Welcome message
  welcomeMessage: 'Hi! I\'m here to help you with any questions about our products.',
  placeholderText: 'Ask me anything...',
  
  // Avatar customization
  botAvatar: 'https://yourcompany.com/bot-avatar.png',
  showBotAvatar: true,
  showUserAvatar: false
};

Then customize the CSS variables to match your brand:

#eptai-chat-container {
  --ept-brand: #your-brand-color;
  --ept-user-bg: color-mix(in srgb, #your-brand-color 12%, white);
  --ept-link: #your-brand-color;
  --ept-font: var(--your-font-family, system-ui);
  --ept-radius: var(--your-border-radius, 12px);
}

Implementation Guide

Quick Start: Brand Matching

To match your site's design system in minutes:

1. Fonts - Use your site's font variables:

#eptai-chat-container { 
  --ept-font: var(--font-sans, system-ui); 
}

2. Colors - Map your brand tokens:

#eptai-chat-container {
  --ept-brand: var(--brand-600);
  --ept-user-bg: color-mix(in srgb, var(--brand-600) 12%, white);
  --ept-link: var(--link-color, var(--brand-600));
}

3. Radius/Shadow - Align to your card styles:

#eptai-chat-container { 
  --ept-radius: var(--radius-md, 12px); 
  --ept-shadow: var(--elevation-3, 0 12px 24px rgba(0,0,0,.14)); 
}

4. Prompts - Match your pill/chip style:

.eptai-default-question { 
  background: var(--chip-bg, #fff); 
  border-color: var(--chip-border, var(--ept-border)); 
}

Page-Specific Theming

For sites with different themes per section:

/* Docs section */
body.docs #eptai-chat-container {
  --ept-brand: var(--docs-accent, #16a34a);
  --ept-user-bg: color-mix(in srgb, var(--docs-accent) 12%, white);
}

/* Pricing section */
body.pricing #eptai-chat-container {
  --ept-brand: var(--pricing-accent, #a855f7);
  --ept-user-bg: color-mix(in srgb, var(--pricing-accent) 12%, white);
}

/* Dashboard section */
body.dashboard #eptai-chat-container {
  --ept-brand: var(--dashboard-accent, #2563eb);
  --ept-user-bg: color-mix(in srgb, var(--dashboard-accent) 12%, white);
}

Loading the CSS

Create a separate CSS file and load it after the chatbot:

<!-- Load the chatbot first -->
<script src="https://assets.ept.ai/chat/v1/ept_chat_loader_bundle.js?v=1.0.0" async></script>

<!-- Then load your custom styles -->
<link rel="stylesheet" href="/css/ept-chat-theme.css">

Or inject it via JavaScript:

// Load custom CSS after chatbot initialization
const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = '/css/ept-chat-theme.css';
document.head.appendChild(link);

User Experience Configuration

Conversation Behavior

Customize how the chatbot behaves:

window.eptAIConfig = {
  accessToken: access_token,
  
  // Interaction settings
  autoOpen: false, // Don't open automatically
  openDelay: 5000, // Wait 5 seconds before showing
  showNotifications: true, // Show notification badges
  
  // Conversation settings
  showTypingIndicator: true,
  typingDelay: 1000, // Simulate typing time
  showTimestamps: true,
  enableFileUpload: true,
  maxFileSize: '10MB',
  
  // Voice settings (if available)
  enableVoice: false,
  voiceLanguage: 'en-US'
};

Animation and Transitions

Control animations and transitions:

window.eptAIConfig = {
  accessToken: access_token,
  
  animations: {
    openAnimation: 'slideUp', // 'slideUp', 'fadeIn', 'scaleIn', 'none'
    messageAnimation: 'fadeIn',
    typingAnimation: true,
    smoothScrolling: true
  },
  
  transitions: {
    duration: 300, // Animation duration in ms
    easing: 'ease-out'
  }
};

Platform-Specific Customization

Mobile Optimization

Optimize for mobile devices:

window.eptAIConfig = {
  accessToken: access_token,
  
  mobile: {
    // Full screen on mobile
    fullScreen: true,
    
    // Larger touch targets
    buttonSize: 'large',
    
    // Simplified interface
    hideHeader: false,
    hideMinimize: true,
    
    // Keyboard handling
    adjustForKeyboard: true,
    minimizeOnKeyboard: false
  }
};

Desktop Enhancements

Enhanced features for desktop users:

window.eptAIConfig = {
  accessToken: access_token,
  
  desktop: {
    // Window controls
    allowResize: true,
    allowDrag: true,
    minimizable: true,
    
    // Keyboard shortcuts
    enableShortcuts: true,
    toggleShortcut: 'ctrl+shift+c',
    
    // Multi-tab support
    persistAcrossPages: true,
    rememberPosition: true
  }
};

Advanced Customization

Custom Components

Replace default components with your own:

window.eptAIConfig = {
  accessToken: access_token,
  
  customComponents: {
    // Custom header component
    header: `
      <div class="custom-header">
        <img src="/your-logo.png" alt="Logo" class="header-logo">
        <h3>Customer Support</h3>
        <span class="online-indicator">● Online</span>
      </div>
    `,
    
    // Custom loading component
    loader: `
      <div class="custom-loader">
        <div class="spinner"></div>
        <p>Connecting to support...</p>
      </div>
    `,
    
    // Custom footer
    footer: `
      <div class="custom-footer">
        <small>Powered by Your Company AI</small>
      </div>
    `
  }
};

Integration with Design Systems

Integrate with popular design frameworks:

Bootstrap Integration

window.eptAIConfig = {
  accessToken: access_token,
  
  // Use Bootstrap classes
  cssFramework: 'bootstrap',
  customClasses: {
    widget: 'card shadow-lg',
    header: 'card-header bg-primary text-white',
    body: 'card-body p-0',
    input: 'form-control',
    button: 'btn btn-primary'
  }
};

Tailwind CSS Integration

window.eptAIConfig = {
  accessToken: access_token,
  
  cssFramework: 'tailwind',
  customClasses: {
    widget: 'rounded-lg shadow-xl bg-white',
    header: 'bg-blue-600 text-white p-4 rounded-t-lg',
    body: 'p-4 max-h-96 overflow-y-auto',
    input: 'w-full p-2 border border-gray-300 rounded-lg',
    button: 'bg-blue-600 hover:bg-blue-700 text-white p-2 rounded-lg'
  }
};

Testing Your Design

Design Validation

Test your customizations across different scenarios:

1. Device Testing: Test on mobile, tablet, and desktop
2. Browser Testing: Verify appearance in different browsers
3. Theme Testing: Test both light and dark themes if supported
4. Accessibility Testing: Ensure sufficient color contrast and keyboard navigation

A/B Testing

Test different design variations:

// Version A - Minimal design
const designA = {
  theme: 'light',
  position: 'bottom-right',
  primaryColor: '#007bff'
};

// Version B - Branded design
const designB = {
  theme: 'custom',
  position: 'bottom-right',
  primaryColor: '#your-brand-color',
  logo: '/logo.png',
  customStyles: '/* your custom CSS */'
};

// Randomly assign users to designs
const useDesignA = Math.random() < 0.5;
window.eptAIConfig = {
  accessToken: access_token,
  ...(useDesignA ? designA : designB)
};

Best Practices

Design Guidelines

• Consistency: Match your website's design language and color scheme
• Accessibility: Ensure sufficient color contrast (WCAG AA: 4.5:1 minimum)
• Performance: Optimize images and minimize custom CSS
• Mobile-First: Design for mobile devices first, then enhance for desktop

Accessibility & UX Guardrails

Essential to maintain:

• Visible focus on all interactive controls (:focus-visible)
• Contrast ratios: AA minimum (4.5:1) for text; avoid ultra-light grays on pale backgrounds
• Live updates: Don't hide message areas used for ARIA live announcements
• Motion: Provide reduced-motion styles; typing dots shouldn't be essential

Recommended practices:

• Font inheritance: Use font: inherit to blend with your site's typography
• System fonts: Fall back to system fonts for better performance
• Z-index hygiene: Understand your site's stacking contexts before setting z-index
• Safe areas: Use env(safe-area-inset-bottom) for iOS compatibility

Brand Alignment

• Color Psychology: Choose colors that reinforce your brand message
• Typography: Use fonts that match your brand guidelines
• Voice and Tone: Ensure the chatbot's personality matches your brand
• Visual Elements: Include brand elements like logos and icons appropriately

Performance Optimization

• CSS Variables: Use CSS custom properties for easy theming and better performance
• Scoped Styles: Always scope styles to #eptai-chat-container to avoid conflicts
• Minimal Overrides: Only override what you need; let the framework handle the rest
• Lazy Loading: Load custom CSS after the chatbot to avoid blocking

Troubleshooting

Common Issues

Styles Not Applying

• Ensure CSS loads after the chatbot script
• Check that selectors are properly scoped to #eptai-chat-container
• Verify CSS specificity isn't being overridden by other styles

Z-Index Conflicts

• Check your site's stacking context hierarchy
• Avoid extremely high z-index values (stick to 1000-2000 range)
• Test with modals, dropdowns, and other floating elements

Mobile Display Issues

• Verify safe-area-inset-bottom is working on iOS
• Test with different viewport sizes
• Check that touch targets are at least 44px

Dark Mode Problems

• Ensure prefers-color-scheme media query is working
• Test color contrast in both light and dark modes
• Verify all elements have appropriate dark mode colors

Debugging Tips

Inspect the Widget

// Check if widget is loaded
console.log('Chat container:', document.getElementById('eptai-chat-container'));

// Verify CSS variables are applied
const container = document.getElementById('eptai-chat-container');
console.log('CSS variables:', getComputedStyle(container).getPropertyValue('--ept-brand'));

Test Responsive Design

// Simulate different screen sizes
// Use browser dev tools to test mobile/tablet breakpoints

Check Accessibility

• Use browser dev tools to test focus navigation
• Verify color contrast ratios
• Test with screen readers

Next Steps

After configuring your chatbot's design:

1. Context-Aware Chat - Make your chatbot intelligent about user context and page content
2. Set up Continuous Improvement - Monitor user interactions and optimize based on feedback
3. Explore Advanced Integrations - Add advanced integrations and functionality
4. Monitor Performance - Track how design changes affect user engagement

Related Documentation

• Integrating the Chatbot - Basic integration setup
• Context-Aware Chat - Add intelligence to your chatbot
• Continuous Improvement - Monitor and optimize performance

Related Documentation

• Integrating the Chatbot - Technical integration guide
• Channels Configuration - Backend channel setup
• User Interface Guide - Understanding the default interface