Widget Customization Guide

The HelloAivy chat widget offers extensive customization options to ensure it seamlessly integrates with your website's design and branding.

Appearance Customization

Primary Color

Customize the widget's primary color to match your brand:

CDN:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-primary-color="#10b981"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

WordPress: Set in Settings → HelloAivy Chat → Theme Color

Examples:

• Blue: #3b82f6
• Green: #10b981
• Purple: #8b5cf6
• Red: #ef4444
• Orange: #f97316

Color Theme

Choose between light and dark themes:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-theme="dark"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

Options:

• light (default) - Light background with dark text
• dark - Dark background with light text

The theme will automatically adapt to user preferences if they have dark mode enabled in their browser.

Position Customization

Button Position

Control where the chat button appears:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-position="bottom-left"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

Options:

• bottom-right (default) - Bottom right corner
• bottom-left - Bottom left corner

Custom Positioning with CSS

For more control, use CSS custom properties:

<style>
  helloaivy-chat-widget {
    --button-bottom: 20px;
    --button-right: 20px;
    --button-left: auto;
  }
</style>

You can adjust spacing from edges:

helloaivy-chat-widget {
  --button-bottom: 40px; /* Distance from bottom */
  --button-right: 40px;  /* Distance from right */
}

Display Modes

Floating Mode

The default floating mode displays a button in the corner:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-mode="floating"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

Use Cases:

• General website support
• Multi-page websites
• E-commerce product pages
• Blog posts and articles

Embedded Mode

Embed the chat interface directly in a container:

<div id="helloaivy-chat" style="height: 600px;"></div>
<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-mode="embedded"
  data-target="helloaivy-chat"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

WordPress Shortcode:

[helloaivy_chat_widget height="600px"]

Use Cases:

• Dedicated support pages
• Contact pages
• Customer service sections
• Knowledge base pages

Hybrid Approach

You can use both modes on different pages:

• Floating mode on most pages for accessibility
• Embedded mode on dedicated support/contact pages

Size Customization

Chat Window Size (Floating Mode)

Customize the chat window dimensions:

helloaivy-chat-widget {
  --chat-window-width: 400px;
  --chat-window-height: 600px;
  --chat-window-max-height: 80vh;
}

Embedded Container Size

For embedded mode, control the container size:

<div id="helloaivy-chat" style="
  height: 700px;
  max-width: 800px;
  margin: 0 auto;
"></div>

Responsive Design:

#helloaivy-chat {
  height: 600px;
  width: 100%;
  max-width: 1200px;
  margin: 0 auto;
}

@media (max-width: 768px) {
  #helloaivy-chat {
    height: 500px;
  }
}

Advanced Styling

CSS Custom Properties

The widget exposes CSS custom properties for advanced customization:

helloaivy-chat-widget {
  /* Colors */
  --primary-color: #10b981;
  --secondary-color: #f3f4f6;
  --text-color: #1f2937;
  --background-color: #ffffff;

  /* Button */
  --button-size: 60px;
  --button-border-radius: 50%;
  --button-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);

  /* Chat Window */
  --chat-window-border-radius: 12px;
  --chat-window-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);

  /* Spacing */
  --button-bottom: 20px;
  --button-right: 20px;

  /* Typography */
  --font-family: system-ui, -apple-system, sans-serif;
  --font-size-base: 14px;
}

Dark Mode Support

Automatically adapt to user's dark mode preference:

@media (prefers-color-scheme: dark) {
  helloaivy-chat-widget {
    --background-color: #1f2937;
    --text-color: #f3f4f6;
    --secondary-color: #374151;
  }
}

Brand-Specific Examples

E-commerce (Shopify/WooCommerce):

helloaivy-chat-widget {
  --primary-color: #f59e0b; /* Warm orange */
  --button-size: 70px;
  --button-bottom: 80px; /* Above cart button */
}

SaaS Product:

helloaivy-chat-widget {
  --primary-color: #3b82f6; /* Professional blue */
  --chat-window-width: 420px;
  --chat-window-border-radius: 16px;
  --font-family: 'Inter', sans-serif;
}

Corporate Website:

helloaivy-chat-widget {
  --primary-color: #1e40af; /* Corporate blue */
  --button-border-radius: 8px; /* Square corners */
  --chat-window-shadow: 0 0 40px rgba(0, 0, 0, 0.1);
}

Programmatic Configuration

JavaScript Configuration Object

For maximum control, use the JavaScript configuration API:

<script>
window.ChatWidgetConfig = {
  // Required
  clientKey: 'YOUR_CHATBOT_ID',

  // Display
  mode: 'floating', // or 'embedded'
  position: 'bottom-right',
  theme: 'light',

  // Styling
  primaryColor: '#10b981',
  buttonSize: 60,

  // Behavior
  autoOpen: false,
  openDelay: 5000, // Auto-open after 5 seconds
  greeting: 'Hi! How can I help you today?',

  // Advanced
  apiEndpoint: 'YOUR_API_ENDPOINT',
  language: 'en',
};
</script>
<script async src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>

Dynamic Configuration

Update widget configuration dynamically:

// Open widget programmatically
window.HelloAivyChat?.open();

// Close widget
window.HelloAivyChat?.close();

// Toggle widget
window.HelloAivyChat?.toggle();

// Update theme dynamically
window.HelloAivyChat?.setTheme('dark');

// Send a message programmatically
window.HelloAivyChat?.sendMessage('Hello!');

Event Listeners

Listen to widget events:

// Widget loaded
window.addEventListener('helloaivy:loaded', () => {
  console.log('Chat widget loaded');
});

// Widget opened
window.addEventListener('helloaivy:opened', () => {
  console.log('Chat opened');
  // Track in analytics
});

// Widget closed
window.addEventListener('helloaivy:closed', () => {
  console.log('Chat closed');
});

// Message sent
window.addEventListener('helloaivy:message-sent', (event) => {
  console.log('Message:', event.detail.message);
});

Mobile Optimization

Responsive Behavior

The widget automatically adapts to mobile devices:

@media (max-width: 768px) {
  helloaivy-chat-widget {
    /* Full-screen chat on mobile */
    --chat-window-width: 100vw;
    --chat-window-height: 100vh;
    --chat-window-border-radius: 0;

    /* Smaller button */
    --button-size: 56px;
    --button-bottom: 16px;
    --button-right: 16px;
  }
}

Mobile-Specific Settings

window.ChatWidgetConfig = {
  clientKey: 'YOUR_CHATBOT_ID',
  mobile: {
    fullScreen: true,
    position: 'bottom-right',
    buttonSize: 56,
  },
  desktop: {
    fullScreen: false,
    position: 'bottom-right',
    buttonSize: 64,
  },
};

Accessibility

Keyboard Navigation

The widget supports full keyboard navigation:

• Tab - Navigate between elements
• Enter/Space - Activate buttons
• Esc - Close chat window

Screen Reader Support

Add ARIA labels for better screen reader support:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-aria-label="Customer Support Chat"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

High Contrast Mode

The widget respects high contrast mode preferences:

@media (prefers-contrast: high) {
  helloaivy-chat-widget {
    --button-border: 2px solid currentColor;
    --chat-window-border: 2px solid currentColor;
  }
}

Multi-Language Support

Setting Widget Language

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-language="es"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

Supported Languages:

• en - English
• es - Spanish
• fr - French
• de - German
• it - Italian
• pt - Portuguese
• nl - Dutch
• pl - Polish

Automatic Language Detection

The widget can automatically detect the page language:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-language="auto"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

Custom Branding

Custom Welcome Message

Set a custom greeting when users open the chat:

window.ChatWidgetConfig = {
  clientKey: 'YOUR_CHATBOT_ID',
  greeting: 'Welcome to our store! How can we help you today?',
  greetingDelay: 1000, // Show after 1 second
};

Custom Avatar

Customize the bot avatar (coming soon):

window.ChatWidgetConfig = {
  clientKey: 'YOUR_CHATBOT_ID',
  avatar: 'https://your-domain.com/bot-avatar.png',
};

Custom Button Icon

Replace the default chat icon (coming soon):

window.ChatWidgetConfig = {
  clientKey: 'YOUR_CHATBOT_ID',
  buttonIcon: 'https://your-domain.com/chat-icon.svg',
};

Performance Optimization

Lazy Loading

Enable lazy loading to improve initial page load:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-lazy-load="true"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

The chat interface will only load when the user clicks the button.

Preloading

For frequently used pages, preload the widget:

<link rel="preload" href="https://helloaivy-widget.vercel.app/chat-widget.js" as="script">

Testing Customizations

Development Mode

Enable development mode to see debugging information:

<script
  async
  data-chatbot='YOUR_CHATBOT_ID'
  data-debug="true"
  src='https://helloaivy-widget.vercel.app/chat-widget.js'>
</script>

This will log widget events and configuration to the browser console.

Preview Changes

Test your customizations before deploying:

1. Use browser DevTools to test CSS changes
2. Add ?helloaivy-preview=true to your URL for preview mode
3. Test on multiple devices and browsers

Best Practices

Design Guidelines

1. Match Your Brand: Use colors from your brand palette
2. Ensure Contrast: Maintain readable text contrast ratios (WCAG AA: 4.5:1)
3. Consider Mobile: Test on mobile devices early
4. Avoid Overlap: Ensure widget doesn't cover important content
5. Stay Accessible: Maintain keyboard navigation and screen reader support

Performance Guidelines

1. Use Async Loading: Always use the async attribute
2. Minimize Custom CSS: Use built-in customization options when possible
3. Lazy Load When Possible: Enable lazy loading for better performance
4. Test Page Speed: Monitor impact on page load times

User Experience Guidelines

1. Clear Positioning: Place button in consistent, expected locations
2. Appropriate Timing: Don't auto-open immediately on page load
3. Respect User Preference: Remember if user closed the chat
4. Mobile Friendly: Ensure button is easily tappable on mobile (min 44x44px)

Examples Gallery

Minimal Setup

<script async data-chatbot='YOUR_ID' src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>

Fully Customized

<style>
  helloaivy-chat-widget {
    --primary-color: #10b981;
    --button-size: 64px;
    --button-bottom: 24px;
    --button-right: 24px;
    --font-family: 'Inter', system-ui, sans-serif;
  }
</style>
<script>
window.ChatWidgetConfig = {
  clientKey: 'YOUR_CHATBOT_ID',
  mode: 'floating',
  position: 'bottom-right',
  theme: 'light',
  greeting: 'Hi! How can we help?',
  openDelay: 10000,
  language: 'auto',
};
</script>
<script async src='https://helloaivy-widget.vercel.app/chat-widget.js'></script>

Troubleshooting

Styles Not Applying

1. Check CSS specificity - widget uses Shadow DOM
2. Use CSS custom properties instead of targeting internal elements
3. Clear browser cache
4. Verify CSS is loaded before widget script

JavaScript Configuration Not Working

1. Ensure ChatWidgetConfig is defined before widget script loads
2. Check browser console for errors
3. Verify configuration object syntax
4. Test with debug mode enabled

Next Steps

• CDN Installation - Learn basic installation
• WordPress Installation - WordPress-specific setup
• Widget Installation Overview - General overview

Support

For customization assistance:

• Check the examples in this guide
• Review the CSS custom properties reference
• Contact support through your HelloAivy dashboard
• Join our community forum for tips and examples