How to Add an AI Agent to WordPress in 2 Minutes

No Plugin Required

Most WordPress agent solutions require you to install a plugin, configure API keys, deal with compatibility warnings, and hope it does not conflict with your existing setup. This is different.

Adding an AI agent to your WordPress site requires pasting a single line of code. One script tag. No plugin to install, no settings page to configure, no database tables to create. It works with every WordPress theme, every page builder, and every hosting provider.

Here is the complete process from start to finish.

Step 1: Create Your Agent on hiroi

Before you touch WordPress, you need an agent to embed.

1. Go to hiroi.ai and sign in
2. Click Create New Agent from your dashboard
3. Give it a name and configure its personality, knowledge base, and appearance
4. Go to the Settings tab and add your domain to the Allowed Domains list

This last step is important. The domain safelist is how the agent authenticates requests. Add both your root domain and www version:

• yourdomain.com
• www.yourdomain.com

If you are testing locally, add localhost as well.

Step 2: Copy Your Embed Code

From your agent's settings page, copy the embed script tag. It looks like this:

<script src="https://hiroi.ai/widget.js"
        data-site-id="your-site-uuid-here"></script>

The data-site-id is a public identifier for your agent. It is safe to expose in your HTML. Authentication happens server-side via the domain safelist you configured in Step 1.

Step 3: Add to WordPress

You have three options depending on your WordPress setup. Pick whichever is most comfortable.

Option A: Header/Footer Plugin (Easiest)

If you use a plugin like Insert Headers and Footers (by WPCode), Header Footer Code Manager, or similar:

1. Go to Settings > Insert Headers and Footers (or your plugin's settings page)
2. Paste the script tag in the Footer section
3. Save

Done. The agent will appear on every page of your site.

Option B: Theme Customizer

1. Go to Appearance > Theme Editor (or Appearance > Theme File Editor in newer WordPress)
2. Open your theme's footer.php file
3. Paste the script tag just before the closing </body> tag
4. Save

If you are using a child theme, make sure you are editing the child theme's footer.php. If one does not exist, create it by copying the parent theme's version.

Option C: Functions.php (Cleanest)

For developers who prefer doing things properly:

function add_hiroi_agent() {
    echo '<script src="https://hiroi.ai/widget.js"
                data-site-id="your-site-uuid-here"></script>';
}
add_action('wp_footer', 'add_hiroi_agent');

Add this to your theme's functions.php (or preferably your child theme's). This approach survives theme updates and keeps your footer template clean.

Works With Every Page Builder

The script tag approach means zero compatibility issues with page builders. It loads independently of your page content.

• Elementor: Works without configuration. The widget renders outside Elementor's content area.
• Divi: No conflicts. The agent loads after Divi's builder scripts.
• WPBakery: Compatible. No shortcode or element needed.
• Gutenberg: Works naturally. No block required.
• Beaver Builder, Oxygen, Bricks: All compatible.

The agent widget renders as a fixed-position element in the corner of the screen. It does not interfere with your page layout, content flow, or existing JavaScript.

Performance Impact

A common concern with adding third-party scripts is performance. Here is what actually happens when the widget loads:

• Single async script: The widget JavaScript loads asynchronously, meaning it does not block your page from rendering. Your content appears first, and the agent initializes in the background.
• No external CSS files: All styles are scoped and injected inline. No additional HTTP requests for stylesheets.
• Lazy initialization: The widget only establishes an API connection when a visitor actually interacts with it. Just having it on the page does not trigger API calls.
• Minimal DOM footprint: The widget adds a small number of elements to your page. It does not inject iframes, heavy libraries, or tracking scripts.

On a typical WordPress site, the performance impact is negligible. Your PageSpeed Insights and Core Web Vitals scores should not be meaningfully affected.

Controlling Where the Agent Appears

By default, embedding the script in your footer makes the agent appear on every page. If you want it only on specific pages:

Specific Pages Only

Use WordPress conditional tags in functions.php:

function add_hiroi_agent() {
    // Only on the Contact and Services pages
    if (is_page('contact') || is_page('services')) {
        echo '<script src="https://hiroi.ai/widget.js"
                    data-site-id="your-site-uuid-here"></script>';
    }
}
add_action('wp_footer', 'add_hiroi_agent');

Exclude Specific Pages

function add_hiroi_agent() {
    // Everywhere except the checkout page
    if (!is_page('checkout')) {
        echo '<script src="https://hiroi.ai/widget.js"
                    data-site-id="your-site-uuid-here"></script>';
    }
}
add_action('wp_footer', 'add_hiroi_agent');

Troubleshooting Common Issues

Agent does not appear

• Check your domain safelist: The most common issue. Make sure both yourdomain.com and www.yourdomain.com are in your agent's Allowed Domains. Domain matching is exact.
• Check for caching: If you use a caching plugin (WP Super Cache, W3 Total Cache, LiteSpeed Cache), clear the cache after adding the script tag.
• Check browser console: Open your browser's developer tools (F12) and look for errors. The widget logs messages prefixed with [VA Widget] that will tell you exactly what is happening.

Agent appears but does not respond

• Check your agent configuration: Make sure your agent has an AI provider configured and has available credits or a connected API key.
• Check for JavaScript conflicts: Rarely, another plugin's JavaScript can interfere. Check the browser console for errors.

Agent position conflicts with other elements

The widget defaults to the bottom-right corner. If you have a cookie banner, live chat button, or scroll-to-top button in the same position, you can adjust the widget's position from your hiroi dashboard settings.

What Happens Next

Once the agent is live on your WordPress site, you can:

• Train it with your site's content by uploading documents or adding FAQ entries
• Monitor conversations from your hiroi dashboard
• Customize appearance to match your brand colors and style
• Add Page Integration to let the AI read and interact with your page content
• Create guided tours to walk visitors through your site

The embed is the easy part. The real value comes from configuring the agent to genuinely help your visitors, and that starts from your dashboard the moment the script tag is live.