BH

Docs

Dashboard

Customization Guide

Learn how to customize the BotHarbor chat widget to match your brand and requirements with themes, styling, and advanced configuration options.

Basic Theme Configuration

BotHarbor comes with built-in themes that you can easily apply to match your application's design.

Available Themes

// Light theme (default)
BotHarbor.init({
  botId: 'your-bot-id',
  theme: 'light'
})

// Dark theme
BotHarbor.init({
  botId: 'your-bot-id',
  theme: 'dark'
})

// Auto theme (follows system preference)
BotHarbor.init({
  botId: 'your-bot-id',
  theme: 'auto'
})

// Custom theme with primary color
BotHarbor.init({
  botId: 'your-bot-id',
  theme: 'light',
  primaryColor: '#3b82f6' // Blue
})

Theme Customization

BotHarbor.init({
  botId: 'your-bot-id',
  theme: {
    // Primary colors
    primaryColor: '#3b82f6',
    primaryColorHover: '#2563eb',
    primaryColorText: '#ffffff',
    
    // Background colors
    backgroundColor: '#ffffff',
    backgroundColorSecondary: '#f8fafc',
    
    // Text colors
    textColor: '#1f2937',
    textColorSecondary: '#6b7280',
    textColorMuted: '#9ca3af',
    
    // Border and divider colors
    borderColor: '#e5e7eb',
    dividerColor: '#f3f4f6',
    
    // Message bubble colors
    userMessageBackground: '#3b82f6',
    userMessageText: '#ffffff',
    botMessageBackground: '#f3f4f6',
    botMessageText: '#1f2937',
    
    // Input field styling
    inputBackground: '#ffffff',
    inputBorder: '#d1d5db',
    inputBorderFocus: '#3b82f6',
    inputText: '#1f2937',
    inputPlaceholder: '#9ca3af'
  }
})

Position and Size Configuration

Control where the chat widget appears on your page and how it behaves on different screen sizes.

Position Options

// Bottom right (default)
BotHarbor.init({
  botId: 'your-bot-id',
  position: 'bottom-right'
})

// Bottom left
BotHarbor.init({
  botId: 'your-bot-id',
  position: 'bottom-left'
})

// Top right
BotHarbor.init({
  botId: 'your-bot-id',
  position: 'top-right'
})

// Top left
BotHarbor.init({
  botId: 'your-bot-id',
  position: 'top-left'
})

// Custom position with offset
BotHarbor.init({
  botId: 'your-bot-id',
  position: 'bottom-right',
  offset: {
    x: 20, // 20px from right edge
    y: 20  // 20px from bottom edge
  }
})

Responsive Configuration

BotHarbor.init({
  botId: 'your-bot-id',
  responsive: {
    // Desktop configuration
    desktop: {
      width: 400,
      height: 600,
      position: 'bottom-right'
    },
    // Tablet configuration
    tablet: {
      width: 350,
      height: 500,
      position: 'bottom-right'
    },
    // Mobile configuration
    mobile: {
      width: '100%',
      height: '100%',
      position: 'fullscreen', // Takes full screen on mobile
      showHeader: true
    }
  },
  // Breakpoints (in pixels)
  breakpoints: {
    mobile: 768,
    tablet: 1024
  }
})

Advanced Styling with CSS

For complete control over the widget's appearance, you can use custom CSS to override default styles.

CSS Custom Properties

/* Override BotHarbor CSS variables */
:root {
  --botharbor-primary-color: #3b82f6;
  --botharbor-primary-hover: #2563eb;
  --botharbor-background: #ffffff;
  --botharbor-text-color: #1f2937;
  --botharbor-border-radius: 12px;
  --botharbor-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
  --botharbor-font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --botharbor-primary-color: #60a5fa;
    --botharbor-background: #1f2937;
    --botharbor-text-color: #f9fafb;
  }
}

Custom CSS Classes

/* Target specific BotHarbor elements */
.botharbor-widget {
  border-radius: 16px !important;
  box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1) !important;
}

.botharbor-header {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
  color: white !important;
}

.botharbor-message-user {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
  border-radius: 18px 18px 4px 18px !important;
}

.botharbor-message-bot {
  background: #f3f4f6 !important;
  border-radius: 18px 18px 18px 4px !important;
  border-left: 3px solid #3b82f6 !important;
}

.botharbor-input {
  border-radius: 25px !important;
  border: 2px solid #e5e7eb !important;
  transition: all 0.2s ease !important;
}

.botharbor-input:focus {
  border-color: #3b82f6 !important;
  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1) !important;
}

.botharbor-send-button {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%) !important;
  border-radius: 50% !important;
  transition: transform 0.2s ease !important;
}

.botharbor-send-button:hover {
  transform: scale(1.05) !important;
}

Animation Customization

/* Custom animations */
@keyframes botharbor-slide-in {
  from {
    transform: translateY(100%);
    opacity: 0;
  }
  to {
    transform: translateY(0);
    opacity: 1;
  }
}

@keyframes botharbor-bounce {
  0%, 20%, 50%, 80%, 100% {
    transform: translateY(0);
  }
  40% {
    transform: translateY(-10px);
  }
  60% {
    transform: translateY(-5px);
  }
}

.botharbor-widget {
  animation: botharbor-slide-in 0.3s ease-out !important;
}

.botharbor-trigger {
  animation: botharbor-bounce 2s infinite !important;
}

.botharbor-message {
  animation: fadeInUp 0.3s ease-out !important;
}

@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

Behavior and Interaction Customization

Configure how the chat widget behaves and interacts with your users.

Auto-Opening and Greetings

BotHarbor.init({
  botId: 'your-bot-id',
  
  // Auto-open configuration
  autoOpen: true,
  autoOpenDelay: 3000, // Wait 3 seconds before opening
  
  // Greeting message
  greeting: "👋 Hi there! How can I help you today?",
  
  // Welcome sequence
  welcomeSequence: [
    {
      message: "Welcome to our website!",
      delay: 1000
    },
    {
      message: "I'm here to help you find what you're looking for.",
      delay: 2000
    },
    {
      message: "What can I assist you with?",
      delay: 3000
    }
  ],
  
  // Trigger conditions
  triggers: {
    // Open after user scrolls 50% of page
    scrollPercentage: 50,
    // Open after 30 seconds of inactivity
    inactivityTime: 30000,
    // Open when user tries to leave (exit intent)
    exitIntent: true
  }
})

File Upload Configuration

BotHarbor.init({
  botId: 'your-bot-id',
  
  fileUpload: {
    enabled: true,
    maxFileSize: 10 * 1024 * 1024, // 10MB
    allowedTypes: [
      'image/jpeg',
      'image/png',
      'image/gif',
      'application/pdf',
      'text/plain',
      'application/msword',
      'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
    ],
    multiple: true,
    maxFiles: 5,
    
    // Custom upload handler
    onUpload: (files) => {
      console.log('Files uploaded:', files)
      // Handle file upload logic
    },
    
    // Upload progress callback
    onProgress: (progress) => {
      console.log('Upload progress:', progress)
    }
  }
})

Business Hours Configuration

BotHarbor.init({
  botId: 'your-bot-id',
  
  businessHours: {
    enabled: true,
    timezone: 'America/New_York',
    schedule: {
      monday: { start: '09:00', end: '17:00' },
      tuesday: { start: '09:00', end: '17:00' },
      wednesday: { start: '09:00', end: '17:00' },
      thursday: { start: '09:00', end: '17:00' },
      friday: { start: '09:00', end: '17:00' },
      saturday: { start: '10:00', end: '14:00' },
      sunday: null // Closed on Sunday
    },
    
    // Messages for different states
    messages: {
      online: "We're online! How can we help?",
      offline: "We're currently offline. Leave us a message and we'll get back to you!",
      outsideHours: "We're outside business hours. We'll respond during: Mon-Fri 9AM-5PM EST"
    },
    
    // Behavior when offline
    offlineBehavior: {
      showWidget: true,
      collectContactInfo: true,
      autoReply: true,
      autoReplyMessage: "Thanks for your message! We'll get back to you within 24 hours."
    }
  }
})

Best Practices

Performance Tips

  • ✓Load the script asynchronously to avoid blocking the main thread
  • ✓Use environment variables for configuration
  • ✓Test your customizations across different devices and browsers
  • ✓Consider accessibility when customizing colors and fonts