WordPress Integration

WordPress Integration

WordPress powers over 40% of the web, making it the most common platform where Chatsby agents are deployed. This guide covers every method for embedding the Chatsby chat widget on your WordPress site, from the simplest plugin-based approach to advanced theme editor techniques. You will also find detailed troubleshooting steps for caching plugins, theme conflicts, and multisite configurations.

Prerequisites

Before you begin, make sure you have the following:

<script
  src="https://chatsby.co/widget.min.js"
  bot-id="YOUR_BOT_ID"
  async
  defer
></script>

Method 1: Plugin Method (Recommended)

This is the easiest and safest approach. It does not require editing any theme files, and the script persists through theme changes and updates.

Method 2: Theme Editor (functions.php)

This method is preferred by developers who want to avoid additional plugins. The script is added programmatically via your theme's functions.php file.

function chatsby_embed_widget() {
    ?>
    <script
      src="https://chatsby.co/widget.min.js"
      bot-id="YOUR_BOT_ID"
      async
      defer
    ></script>
    <?php
}
add_action('wp_footer', 'chatsby_embed_widget');

Method 3: Page-Specific Embedding

If you only want the chat widget on specific pages (for example, your pricing page or help center), you can use a shortcode approach or conditional logic.

Using Conditional Logic in functions.php

function chatsby_embed_widget_conditional() {
    // Only load on pages with slug 'pricing' or 'help'
    if ( is_page('pricing') || is_page('help') ) {
        ?>
        <script
          src="https://chatsby.co/widget.min.js"
          bot-id="YOUR_BOT_ID"
          async
          defer
        ></script>
        <?php
    }
}
add_action('wp_footer', 'chatsby_embed_widget_conditional');

Using the Custom HTML Block

For a single page, edit the page in the WordPress Block Editor, add a Custom HTML block at the bottom, and paste your embed script directly. This approach does not require any plugin or theme file changes.

Verifying the Installation

After installing the widget using any method above, verify that it is working correctly.

Troubleshooting

Widget Not Showing

Caching Plugin Conflicts

WordPress caching plugins are the most common cause of the widget not appearing after installation. If you have installed the script but do not see the widget, try the following:

• WP Super Cache: Go to Settings > WP Super Cache and click Delete Cache.
• W3 Total Cache: Navigate to Performance > General Settings and click Empty All Caches.
• WP Rocket: Go to Settings > WP Rocket and click Clear Cache.
• LiteSpeed Cache: Navigate to LiteSpeed Cache > Toolbox > Purge All.
• Cloudflare: If you use Cloudflare as a CDN, log in to your Cloudflare dashboard and purge the cache from Caching > Configuration > Purge Everything.

Theme Conflicts

Some themes aggressively minify or defer JavaScript in ways that can interfere with third-party scripts. If the widget loads inconsistently:

1. Temporarily switch to a default theme (like Twenty Twenty-Four) to confirm the issue is theme-related.
2. Check your theme's settings for a "Script Optimization" or "Defer JavaScript" option and add an exclusion for chatsby.co/widget.min.js.
3. If using an optimization plugin like Autoptimize, add chatsby.co to its script exclusion list.

Plugin Conflicts

If the widget breaks after installing a new plugin, deactivate your plugins one at a time and reload the page to identify which plugin is causing the conflict. Common culprits include JavaScript optimization plugins, security plugins that block external scripts, and cookie consent plugins that defer script loading.

WordPress Multisite Considerations

If you are running a WordPress Multisite network and want the widget on all sites:

• Network-wide plugin approach: Install the Insert Headers and Footers plugin as a network-activated plugin and configure the script from the network admin. Note that not all header/footer plugins support network-wide settings --- WPCode does.
• Per-site configuration: Alternatively, configure the embed script individually on each sub-site. This approach allows you to use different Chatsby agents for different sites in the network.
• Must-use plugin: For maximum reliability, create a file in wp-content/mu-plugins/ called chatsby-widget.php with the wp_footer hook code from Method 2. Must-use plugins are loaded on every site in the network automatically.

WooCommerce-Specific Tips

If your WordPress site runs WooCommerce, consider these optimizations:

• Product Page Context: Your Chatsby agent can provide better answers about products if you train it on your product catalog. Export your WooCommerce products as a CSV or PDF and upload it as a data source in the Chatsby dashboard.
• Cart and Checkout Pages: The widget will appear on cart and checkout pages by default. If you want to exclude it from checkout to reduce distractions, use the conditional loading approach in Method 3 with !is_checkout().
• Order Tracking: Train your agent on your shipping and return policies so it can answer common post-purchase questions directly in the chat widget.

Performance Impact

The Chatsby widget script is designed for minimal performance impact on your WordPress site:

• The script tag includes async and defer attributes by default, meaning it loads in the background without blocking page rendering.
• The widget JavaScript bundle is under 50 KB gzipped.
• No server-side resources are consumed --- all processing happens on Chatsby's infrastructure.
• The widget is compatible with Core Web Vitals optimization and does not negatively affect Largest Contentful Paint (LCP) or Cumulative Layout Shift (CLS) scores.

Updating the Widget

The Chatsby widget script is served from a CDN and updates automatically. You do not need to change your embed code when we release new widget features or fixes. As long as your embed script points to https://chatsby.co/widget.min.js, you will always receive the latest version.

If you need to change which agent is displayed on your site (for example, after creating a new agent), simply update the bot-id attribute in your embed script to the new agent's ID.