Install on WordPress

WordPress has no single built-in place to add a script to every page, so there are three common ways to do it. The easiest and safest is a header and footer scripts plugin. Menus and plugin names change between versions, so treat the paths below as a guide and consult the WordPress documentation or your plugin's own help if something looks different.

Before you start#

• Create a site in the SiteTrellis dashboard, publish an agent, and copy the embed snippet. See the quickstart.
• Add your WordPress site's origin to the site's allowed origins, for example https://www.example.com. Use the exact address visitors see, including www or not. See Install on any website.
• Decide whether the chat should appear on the whole site or only on some pages. Page rules in the widget settings can restrict it later without touching WordPress.

Option 1: a header and footer scripts plugin#

Plugins in this category (for example WPCode or Insert Headers and Footers) let you paste code into the site footer from the WordPress admin, and they survive theme changes and updates.

1. In the WordPress admin, open Plugins > Add New, search for a header and footer scripts plugin, then install and activate it.
2. Open the plugin's settings. Most expose a Footer (sometimes called "Scripts in Footer" or "Before </body>") box.
3. Paste the SiteTrellis snippet there and save.
4. Clear your site cache (see the caching section below), then load a public page in a private window.

<script src="https://cdn.sitetrellis.com/v/a44108d9c4521120/widget.js" data-site="site_xxxxxxxx" async></script>

Option 2: your theme's footer#

With a classic theme you can edit footer.php in Appearance > Theme File Editor and paste the snippet just above <?php wp_footer(); ?> or above the closing </body> tag. Two cautions: theme updates overwrite your edit unless you use a child theme, and a typing mistake in a PHP file can take the site down. Make a backup first. Block (full site editing) themes have no footer.php to edit this way; use a plugin or Option 3.

Option 3: enqueue it from code#

If you maintain a child theme or a small custom plugin, enqueue the script the WordPress way. WordPress does not add custom data attributes by default, so add them with the script_loader_tag filter:

<?php
// functions.php of a child theme, or a small custom plugin
add_action('wp_enqueue_scripts', function () {
    wp_enqueue_script(
        'sitetrellis-widget',
        'https://cdn.sitetrellis.com/v/a44108d9c4521120/widget.js',
        [],
        null,            // no version query string
        ['in_footer' => true, 'strategy' => 'async']
    );
});

add_filter('script_loader_tag', function ($tag, $handle) {
    if ($handle !== 'sitetrellis-widget') {
        return $tag;
    }
    return str_replace(' src=', ' data-site="site_xxxxxxxx" src=', $tag);
}, 10, 2);

The strategy option requires WordPress 6.3 or later; on older versions drop it and add async in the same str_replace.

Caching and optimization plugins#

These are the most common reason the widget does not show on WordPress.

• Page caches (WP Super Cache, W3 Total Cache, LiteSpeed Cache, host-level caches and similar) store a copy of your pages. After adding the snippet, purge the cache or the old copy without the widget keeps being served.
• Delay or defer JavaScript options may postpone third-party scripts until the first user interaction. The widget still works, but the launcher appears late. Add the SiteTrellis script URL to the plugin's exclusion list if you want it immediately.
• Combine/minify JavaScript should not include the SiteTrellis script. Exclude the CDN host.
• Cloudflare or another CDN in front of WordPress may cache HTML. Purge it after changes.

Identifying logged-in users (optional)#

You can tell the agent who is chatting by calling the JavaScript API from PHP. Only do this if your privacy policy covers sending the visitor's name and email to your chosen AI provider as part of the chat, and remember these values come from the browser and are not verified. See Widget JavaScript API.

<?php
add_action('wp_footer', function () {
    if (!is_user_logged_in()) {
        return;
    }
    $u = wp_get_current_user();
    $data = ['name' => $u->display_name, 'email' => $u->user_email];
    echo '<script>(function(){var d=' . wp_json_encode($data) . ';'
       . 'function go(){window.SiteTrellis("identify", d);}'
       . 'if(window.SiteTrellis){go();}else{var s=document.querySelector("script[data-site]");'
       . 's&&s.addEventListener("load",go);}})();</script>';
}, 20);

Multisite, staging and page builders#

• Multisite: create one SiteTrellis site per WordPress site (or per domain) so each has its own allowed origins and agent, or share one site id and list every origin.
• Staging copies: a staging domain is a different origin. Add it to the allowed origins or use a separate SiteTrellis site, otherwise the widget will be blocked there (which is also a handy way to keep test chats out of production).
• Page builders (Elementor, Divi and others) usually include their own "custom code" areas; the footer plugin approach above is still simpler and applies site-wide.

Verify#

Open a public page in a private browser window while logged out of WordPress, hard-refresh, and look for the launcher button. If it is missing, work through Troubleshooting. The first checks are the Network tab (does widget.js load?) and whether the agent is published.