Install the WordPress plugin

What it is

WordPress is the one platform with an official Agentency plugin, and it is the easiest install in the whole Plugins gallery. You install it, paste one key, pick your chatbot, and you are done — no theme editing, and no separate trip to add your domain to the allowlist, because the plugin registers your site for you.

The plugin is a connector, not a second chatbot. Your knowledge, instructions and conversations all stay in Agentency; the plugin's job is to fetch the right widget details for this site and print one script tag on your public pages.

WooCommerce is covered by the same plugin. WooCommerce runs on WordPress, so there is nothing extra to install — the chat appears on your shop, cart and checkout pages along with everything else.

When you would use it

Use the plugin on any self-hosted WordPress site. Use the PHP snippet fallback only when you cannot install plugins — some managed hosts restrict this — or when your agency insists on managing everything in code.

The strongest reason to prefer the plugin is the domain step. A hand-pasted snippet works perfectly and then shows nothing, because the widget is blocked on a domain you never added. The plugin does that for you.

Where to find it

Open Dashboard → Chatbots → your chatbot → Integrations → Plugins → WordPress.

Before you start

• You need an administrator account on the WordPress site.
• The plugin needs WordPress 6.3 or newer and PHP 7.4 or newer.
• Confirm the chatbot is Active on its Playground tab. The plugin will list a chatbot that is not active yet, and flag it as such, but it will not answer visitors until you activate it.
• You will need a key from Settings → Developer in Agentency. That page is owner-only — see Why Billing is missing for the same rule applied to Billing.

Steps

1. Open Dashboard → Chatbots → your chatbot → Integrations → Plugins and click the WordPress card (or WooCommerce — same plugin).
2. If an Install the plugin button is shown, use it to get the plugin. Otherwise install it from the listing your provider gave you, under Plugins → Add New → Upload Plugin in WordPress.
3. Activate the plugin in WordPress.
4. In Agentency, open Settings → Developer and create a personal access token with the widget:manage scope and nothing else. See Choose token scopes for why the narrow scope matters.
5. Copy the key. It is shown once.
6. In WordPress, open Settings → Agentency Chatbot and paste the key into the API key field, then click Connect.
7. The plugin lists the chatbots on your account. Pick the one you want on this site and click the button to add it.
8. The plugin registers this site's host with Agentency and stores the widget details. Visit a public page — the bubble should be there.
9. Back in Agentency, confirm the host now appears in the allowlist on Integrations → Web, and that the site is listed under Connected websites at the bottom of the Plugins tab.

Where the PHP fallback goes

If you cannot use the plugin, the drawer keeps a PHP snippet. Do not paste it into your parent theme — a theme update will erase it. Use a child theme's functions.php, or a code-snippets plugin such as the free WPCode, which gives you a safe place to store PHP that survives theme changes:

<?php
// Add this to your active theme's functions.php file
function agentency_chatbot_widget() {
    ?>
    <script src="https://agentency.com/js/chatbot-widget.js" defer data-widget-token="wt_YOUR_WIDGET_TOKEN" data-api-base-url="https://api.agentency.com" referrerpolicy="strict-origin-when-cross-origin" crossorigin="anonymous"></script>
    <?php
}
add_action('wp_head', 'agentency_chatbot_widget');
?>

Copy your own from the Plugins drawer — the token above is a placeholder. If you take this route, you must add your site's domain to the allowlist yourself: see Allow the widget on your domains.

What you will see

In WordPress, the settings screen has three states. Before you connect, it asks for an API key. After the key is accepted, it shows a list of your chatbots to choose from. Once connected, it shows a green Connected panel naming the chatbot and the registered host, a masked hint of the key, and when the site last checked in.

The connected screen also has display settings the plugin applies for you: which corner the launcher sits in, how big it is, whether it opens by itself, whether to hide the floating bubble in favour of your own button, and which pages to hide it on. There is also an option — off by default — to send the display name of logged-in WordPress users, so your conversations list shows a name instead of "anonymous". That is the WordPress equivalent of Name visitors on the widget.

In Agentency, the Plugins tab grows a Connected websites table listing the site, its platform, the plugin version, and when it last checked in. Sites check in about once a day, and a site that has not been seen for a couple of weeks is flagged as possibly gone. Disconnected sites stay in the table on purpose — when someone asks why the widget vanished, a disconnect row is very often the answer.

Limits and plan notes

The plugin needs a paid Agentency plan, like every other embedding route. See Which plans include integrations and the pricing page.

One chatbot can hold up to 100 site records in the Connected websites registry, including disconnected ones, and up to 50 allowed domains. Those are backstops against a misconfigured multisite network, not day-to-day limits.

Give the key on your WordPress site the widget:manage scope only. A key living in a third-party admin should not be able to create, edit, or delete a chatbot, or read your knowledge base. If your site is ever compromised, that narrow scope is what limits the damage — and you can revoke the key without signing yourself out of the dashboard.

If your provider ever turns the plugin connect service off, sites that are already connected keep working: they hold a widget token and talk to the public chat endpoints, which are unaffected. Only new connections stop.

Common problems

Connect succeeds but the bubble is missing.

Clear the WordPress page cache and any CDN cache, and confirm your theme actually calls the standard head hook — a small number of custom themes do not. Then check the public host against the allowlist: example.com and www.example.com are different hosts.

I typed my dashboard password into the API key field.

The plugin needs a personal access token from Settings → Developer, not your sign-in password. Create one and paste that.

The Developer page is not in my Settings.

You are signed in as a team member, or you are viewing someone else's account. Developer and Billing stay with the account owner. Switch back to your own account.

The chatbot list is empty after I paste the key.

The key has the wrong scope, or it belongs to an account with no chatbots. Create a fresh key with widget:manage on the account that owns the chatbot.

The plugin says connected but the last check-in is old.

Your site's outbound requests may be blocked by a firewall or a security plugin. Chat still works for visitors — the check-in is only how Agentency knows the site is alive.

I run WordPress Multisite.

Connect each site in the network separately. Each has its own host and needs its own registration.