Add the chat to a Joomla site

What it is

Joomla gives you two ways to add the Agentency chat widget. The no-code way is a Custom module containing the raw <script> tag, published to a template position that renders in the page head. The developer way is a few lines of PHP in your template's index.php, which uses Joomla's document API to inject the tag.

Both are shown in the Plugins drawer. Pick the module route unless you maintain the template yourself.

When you would use it

Use this for a Joomla 4 or Joomla 5 site. The PHP snippet in the drawer is written for those versions specifically: the old global document factory that most Joomla tutorials on the web still use was deprecated in Joomla 4 and removed in Joomla 5, so a copy-pasted legacy snippet will bring down a current site with a fatal error. The code Agentency gives you uses the supported API.

Where to find it

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

Before you start

• You need a Super User account in Joomla.
• Know which template your site uses, and prefer a child template if you are going to edit index.php.
• Add your site's domain to the widget allowlist in Agentency — see Allow the widget on your domains.
• Confirm the chatbot is Active on its Playground tab.

Steps

The no-code route (a Custom module):

1. Open Dashboard → Chatbots → your chatbot → Integrations → Plugins and click the Joomla card, then copy the plain <script> line from the snippet.
2. In Joomla, go to Content → Site Modules → New and choose the Custom module type.
3. Before pasting, set the editor to None — under User Menu → Edit Account → Basic Settings → Editor, or in Global Configuration. Joomla's default editor strips <script> tags on save, and this is the single most common reason the snippet "disappears".
4. Paste the tag into the module's content area.
5. Set Position to a position your template renders inside or near the head (a debug or head position works; any always-rendered position will do, since the widget floats above the page).
6. On the Menu Assignment tab, choose On all pages.
7. Set Status to Published and click Save.
8. Set your editor back to what it was.
9. Clear the Joomla cache under System → Clear Cache, open the site, and send a test message. Confirm it appears under Conversations.

The template route:

1. Click Copy template code in the Plugins drawer.
2. Open your template's index.php, before the closing </head>.
3. Paste the PHP block, save, and clear the Joomla cache.

What the snippet looks like

The template version uses Joomla 4/5's application document API:

<?php
// Add to your template's index.php (before </head>). Joomla 4/5 uses the
// application document API below; the legacy global document factory was
// removed in Joomla 5. No-code alternative: paste the raw <script> into a
// "Custom HTML" module published to a head/debug template position.
use Joomla\CMS\Factory;

$document = Factory::getApplication()->getDocument();
$document->addCustomTag('<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>');
?>

For the module route, you only need the <script …></script> part from inside the quotes. Copy your own from the drawer — the token above is a placeholder.

What you will see

With the module route, your Custom module appears in Site Modules as published on all pages. With the template route, nothing changes in the admin.

On the live site the chat bubble appears in the corner set by your chatbot's appearance settings, on every page including articles, category views, and any component pages.

Limits and plan notes

Embedding requires a paid Agentency plan; Free is hosted-link only. See Which plans include integrations and the pricing page.

Joomla 3 is not covered here. Its document API differs and it is out of support; upgrade before adding new third-party scripts.

If your site runs an ecommerce component such as VirtueMart or HikaShop, the widget appears on those pages too, but it does not read their catalogue or orders. Live lookups are a Call action job.

Common problems

I saved the module and the script is gone when I reopen it.

The editor stripped it. Set the editor to None, paste again, save, then restore your editor.

The site shows a fatal error after I edited index.php.

You almost certainly pasted a legacy snippet found elsewhere that calls the removed global document factory. Restore your backup and use the code from the Plugins drawer, which targets Joomla 4/5.

The module is published but the widget is missing.

The chosen position is not rendered by your template. Try another position, or switch to the template route.

The template edit disappeared after an update.

You edited the parent template. Use a child template, or use the module route instead.

Chat loads but is blocked.

The exact host visitors see must be on the allowlist, including www. See The widget is blocked.