WordPress Plugin Installation

The HelloAivy WordPress plugin provides a seamless way to integrate the chat widget into your WordPress site with a visual configuration interface and shortcode support.

Requirements

Before installing the plugin, ensure your environment meets these requirements:

• WordPress: 5.0 or higher
• PHP: 7.4 or higher
• Browser: Chrome, Firefox, Safari, or Edge (latest versions)

Installation

Step 1: Download the Plugin

Download the HelloAivy Chat Widget plugin ZIP file from your HelloAivy dashboard or the WordPress plugin repository.

Step 2: Upload and Activate

1. Go to your WordPress admin panel
2. Navigate to Plugins → Add New
3. Click the Upload Plugin button at the top
4. Click Choose File and select the ZIP file you downloaded
5. Click Install Now
6. After installation completes, click Activate Plugin

Configuration

Step 3: Configure Plugin Settings

After activation, configure the plugin:

1. Go to Settings → HelloAivy Chat in your WordPress admin
2. Configure the required settings:

Widget Script URL

Paste the widget script URL from your HelloAivy dashboard:

https://your-widget-cdn.com/chat-widget.js

This URL is provided in your chatbot's Publish tab.

Chatbot ID

Enter your unique chatbot ID:

550e8400-e29b-41d4-a716-446655440000

Note: If left empty, the widget will auto-register based on your domain name.

Widget Appearance

Configure how the widget looks:

• Widget Mode: Choose between "Floating" or "Embedded"
• Theme Color: Select your brand color (hex code)
• Button Position: Choose "Bottom Right" or "Bottom Left"

Display Settings

Choose how the widget appears on your site:

Option A: Global Mode

• Check Enable Globally to show the widget on all pages
• Optionally add excluded page IDs or slugs (comma-separated)

Option B: Per-Page Mode

• Leave Enable Globally unchecked
• Manually enable the widget on specific pages using the page editor

Step 4: Save Settings

Click Save Settings to apply your configuration.

Using Shortcodes

The plugin provides shortcodes for flexible placement of the widget.

Default Shortcode

Add the widget to any page, post, or widget area:

[helloaivy_chat_widget]

Embedded Mode Shortcode

For embedded inline chat on dedicated support pages:

[helloaivy_chat_widget height="600px"]

Shortcode Parameters

Examples

Full-height embedded chat:

[helloaivy_chat_widget height="100vh"]

Different chatbot on specific page:

[helloaivy_chat_widget chatbot_id="different-chatbot-id"]

Page-Level Control

When using per-page mode, you can control the widget on individual pages:

1. Edit any page or post
2. Scroll down to find the HelloAivy Chat Widget meta box
3. Check Enable widget on this page
4. Update/Publish the page

Page Builder Integration

The widget works seamlessly with popular WordPress page builders.

Elementor

1. Add a Shortcode widget to your page
2. Paste the shortcode: [helloaivy_chat_widget]
3. Update and preview your page

Divi Builder

1. Add a Text module to your layout
2. Insert the shortcode in the text editor
3. Save and publish

Beaver Builder

1. Add an HTML module to your page
2. Paste the shortcode
3. Done and publish

WPBakery Page Builder

1. Add a Raw HTML element
2. Insert the shortcode
3. Save changes

Gutenberg (Block Editor)

1. Add a Shortcode block
2. Paste [helloaivy_chat_widget]
3. Publish or update

Theme Template Integration

For developers who want to add the widget programmatically to their theme:

Automatic Rendering

Add to your theme's footer.php or any template file:

<?php
// Automatic rendering if enabled
do_action('helloaivy_chat_render');
?>

Manual Shortcode Rendering

<?php
// Use shortcode programmatically
echo do_shortcode('[helloaivy_chat_widget]');
?>

Conditional Display

<?php
// Only show on specific pages
if (is_page('support')) {
    echo do_shortcode('[helloaivy_chat_widget height="800px"]');
}
?>

Configuration Examples

Example 1: Enable on All Pages

Settings:

• Enable Globally: ✓ Checked
• Exclude Pages: (leave empty)

Result: Widget appears on every page of your site

Example 2: Exclude Specific Pages

Settings:

• Enable Globally: ✓ Checked
• Exclude Pages: contact, about-us, privacy-policy

Result: Widget appears everywhere except the Contact, About Us, and Privacy Policy pages

Example 3: Enable Only on Product Pages

Settings:

• Enable Globally: ☐ Unchecked

Steps:

1. Edit each product page in WooCommerce
2. Find the "HelloAivy Chat Widget" meta box
3. Check "Enable widget on this page"
4. Update/Publish

Result: Widget only appears on selected product pages

Example 4: Embedded Widget on Support Page

Settings:

• Widget Mode: Embedded
• Enable Globally: ☐ Unchecked

Steps:

1. Create a new page (e.g., "Support")
2. Add the shortcode: [helloaivy_chat_widget height="700px"]
3. Publish the page

Result: Full embedded chat interface on your support page

Example 5: Different Colors per Page

You can use custom CSS to override colors on specific pages:

/* In your theme's custom CSS */
.page-id-123 helloaivy-chat-widget {
  --primary-color: #10b981;
}

Multisite Support

The plugin is compatible with WordPress Multisite installations:

1. Network activate the plugin from Network Admin → Plugins
2. Configure settings individually for each site in the network
3. Each site can have its own chatbot ID and configuration

Performance & Security

Performance Optimization

The plugin implements several performance optimizations:

• Deferred Loading: Widget script loads with the defer attribute (non-blocking)
• Conditional Loading: Script only loads on pages where the widget is enabled
• Lazy Initialization: Chat interface initializes only when needed
• Caching Friendly: Compatible with all major WordPress caching plugins

Security Features

• Input Sanitization: All user inputs are sanitized and validated
• WordPress Nonces: Form security using WordPress nonce verification
• Capability Checks: Only administrators can modify plugin settings
• Secure API Communication: All communication is encrypted via HTTPS
• Shadow DOM: Style isolation prevents CSS injection attacks

Troubleshooting

Widget Not Appearing

1. Verify plugin is activated
2. Check that settings are saved correctly
3. If using per-page mode, ensure widget is enabled on the page
4. Clear your WordPress cache and browser cache
5. Check browser console for JavaScript errors

Shortcode Not Working

1. Ensure you're using the correct shortcode format
2. Check that the plugin is activated
3. Verify you have the chatbot ID configured
4. Try disabling other plugins to check for conflicts

Style Conflicts

The widget uses Shadow DOM for style isolation, but if you experience issues:

1. Check your theme's CSS for overly specific selectors
2. Try different positioning options
3. Clear all caches (WordPress, CDN, browser)
4. Contact support with details about your theme

Plugin Conflicts

If the widget doesn't load properly:

1. Temporarily deactivate other plugins
2. Switch to a default WordPress theme (Twenty Twenty-Four)
3. Check if the widget works
4. Reactivate plugins one by one to identify conflicts

WooCommerce Integration

The plugin works seamlessly with WooCommerce:

Product Page Integration

Enable the widget on all product pages:

Settings:

• Enable Globally: ✓ Checked
• Or enable per product using the meta box

Cart & Checkout Support

For better conversion, enable on cart and checkout:

1. Navigate to WooCommerce → Settings → Advanced
2. Note the Cart and Checkout page IDs
3. Ensure these pages aren't in your exclusion list

Order Tracking

Add embedded chat to order tracking pages using shortcodes.

Hooks & Filters

Developers can extend the plugin using WordPress hooks:

Filters

// Modify widget configuration
add_filter('helloaivy_widget_config', function($config) {
    $config['primary_color'] = '#custom-color';
    return $config;
});

// Customize where widget appears
add_filter('helloaivy_should_display', function($should_display) {
    if (is_user_logged_in()) {
        return false; // Hide for logged-in users
    }
    return $should_display;
}, 10, 1);

Actions

// Before widget renders
add_action('helloaivy_before_render', function() {
    // Your custom code
});

// After widget renders
add_action('helloaivy_after_render', function() {
    // Your custom code
});

Uninstallation

To completely remove the plugin:

1. Deactivate the plugin from Plugins page
2. Click Delete on the plugin
3. All plugin settings will be removed from the database

Note: Deactivating the plugin does not delete settings. Only deletion removes all data.

Next Steps

• Customization Guide - Learn advanced customization options
• CDN Installation - Alternative installation method for non-WordPress sites

Support

For WordPress-specific issues:

1. Check the plugin's FAQ section
2. Review WordPress.org support forums
3. Contact HelloAivy support through your dashboard

Updates

The plugin will notify you when updates are available. Always backup your site before updating plugins.

To manually update:

1. Download the latest version
2. Deactivate the current version
3. Upload and activate the new version

Your settings will be preserved during updates.