> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget on WordPress

> Install the IllumiChat chat widget on your WordPress site using the theme editor, a code snippets plugin, or the WordPress Customizer.

## Overview

This guide covers three methods for adding the IllumiChat widget to a WordPress website. Choose the method that best fits your comfort level and site setup.

| Method               | Difficulty | Survives Theme Updates | Best For    |
| -------------------- | :--------: | :--------------------: | ----------- |
| WPCode Plugin        |    Easy    |           Yes          | Most users  |
| WordPress Customizer |    Easy    |    Depends on theme    | Quick setup |
| Theme Editor         |   Medium   |           No           | Developers  |

## Method 1: WPCode Plugin (Recommended)

WPCode (formerly Insert Headers and Footers) is a free plugin that lets you add code snippets without editing theme files.

<Steps>
  <Step title="Install WPCode">
    In your WordPress dashboard, go to **Plugins** > **Add New**. Search for "WPCode" and install the free version. Activate the plugin.
  </Step>

  <Step title="Create a New Snippet">
    Go to **Code Snippets** > **+ Add Snippet**. Click **Add Your Custom Code (New Snippet)** and select **HTML Snippet**.
  </Step>

  <Step title="Add the Widget Code">
    Paste the following code into the snippet editor:

    ```html theme={null}
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="your-assistant-id"
      async
    ></script>
    ```

    Replace `your-assistant-id` with your actual assistant ID from the IllumiChat dashboard.
  </Step>

  <Step title="Configure the Snippet">
    * Set the **Location** to **Site Wide Footer**
    * Set **Status** to **Active**
    * Click **Save Snippet**
  </Step>
</Steps>

***

## Method 2: WordPress Customizer

If your theme supports the Customizer, you can add the widget code there.

<Steps>
  <Step title="Open the Customizer">
    Go to **Appearance** > **Customize** in your WordPress dashboard.
  </Step>

  <Step title="Find Additional CSS/JS Section">
    Look for a section called **Additional JavaScript**, **Custom Code**, or **Footer Scripts**. The exact name depends on your theme.

    <Note>
      Not all themes offer this option. If you don't see a JavaScript or footer scripts section, use the WPCode plugin method instead.
    </Note>
  </Step>

  <Step title="Add the Widget Code">
    Paste the widget script tag:

    ```html theme={null}
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="your-assistant-id"
      async
    ></script>
    ```
  </Step>

  <Step title="Publish">
    Click **Publish** to save your changes. The widget should appear on your site immediately.
  </Step>
</Steps>

***

## Method 3: Theme Editor

You can add the widget code directly to your theme's `footer.php` file. This method requires familiarity with WordPress theme files.

<Warning>
  Changes made directly to theme files are overwritten when the theme is updated. Use a child theme or one of the other methods for a more durable solution.
</Warning>

<Steps>
  <Step title="Open the Theme Editor">
    Go to **Appearance** > **Theme File Editor** in your WordPress dashboard.
  </Step>

  <Step title="Select footer.php">
    In the file list on the right, click **footer.php**.
  </Step>

  <Step title="Add the Widget Code">
    Add the script tag just before the closing `</body>` tag:

    ```php theme={null}
    <!-- IllumiChat Widget -->
    <script
      src="https://widget.illumichat.com/v1/widget.js"
      data-assistant-id="your-assistant-id"
      async
    ></script>
    <?php wp_footer(); ?>
    </body>
    </html>
    ```

    Make sure the script tag appears before `<?php wp_footer(); ?>`.
  </Step>

  <Step title="Update File">
    Click **Update File** to save your changes.
  </Step>
</Steps>

***

## Conditional Loading

You may want the widget to appear only on certain pages. Use WordPress template conditionals to control where the widget loads.

### Using WPCode Conditional Logic

WPCode Pro supports conditional logic natively. In the snippet settings, use the **Smart Conditional Logic** section to restrict the snippet to specific pages, post types, or URLs.

### Using PHP Conditionals

If editing your theme or using a PHP-capable snippet plugin:

```php theme={null}
<?php if (is_page('pricing') || is_page('contact') || is_singular('product')) : ?>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<?php endif; ?>
```

| Conditional              | Description                           |
| ------------------------ | ------------------------------------- |
| `is_page('pricing')`     | Only on a page with slug "pricing"    |
| `is_front_page()`        | Only on the homepage                  |
| `is_singular('product')` | Only on WooCommerce product pages     |
| `is_category()`          | Only on category archive pages        |
| `!is_admin()`            | Everywhere except the admin dashboard |

***

## WooCommerce Integration

If you run a WooCommerce store, you can configure the widget to show product-specific context on product pages.

```php theme={null}
<?php if (is_singular('product')) :
  $product = wc_get_product(get_the_ID());
?>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<?php else : ?>
<script
  src="https://widget.illumichat.com/v1/widget.js"
  data-assistant-id="your-assistant-id"
  async
></script>
<?php endif; ?>
```

This shows a product-specific greeting on product pages and the default widget everywhere else.

***

## Troubleshooting

<Accordion title="Widget does not appear after adding the code">
  * Clear your browser cache and any WordPress caching plugin (WP Rocket, W3 Total Cache, etc.)
  * Verify the assistant ID is correct
  * Check the browser console for JavaScript errors
  * Ensure the widget is enabled in the assistant's settings
  * Confirm your domain is in the assistant's allowed domains list
</Accordion>

<Accordion title="Widget appears briefly then disappears">
  * Check if a Content Security Policy (CSP) header is blocking the widget script
  * Add `widget.illumichat.com` and `app.illumichat.com` to your CSP `script-src` and `connect-src` directives
  * Some security plugins (Wordfence, Sucuri) may block external scripts -- add the widget domain to the allowlist
</Accordion>

<Accordion title="Widget conflicts with other chat plugins">
  * If you have another chat widget installed (Intercom, Drift, Tidio), it may conflict with the IllumiChat widget
  * Disable other chat plugins or use conditional loading to show only one widget per page
  * Check for CSS z-index conflicts -- the IllumiChat widget uses `z-index: 2147483647`
</Accordion>

<Accordion title="Caching plugins prevent widget updates">
  * Most caching plugins serve static HTML, which includes the widget script tag
  * If you change the assistant ID or widget configuration, clear the cache after making changes
  * The widget itself loads dynamically and is not cached, only the script tag inclusion is affected
</Accordion>

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Customization" icon="palette" href="/guides/widget-customization">
    Customize colors, position, and greeting messages
  </Card>

  <Card title="Widget Configuration" icon="gear" href="/widget/configuration">
    Full reference for all widget configuration options
  </Card>
</CardGroup>