Add an AI chat agent to your MODX® site

What you need

Add Hazelchat to MODX in five steps

1. In Hazelchat

   Prepare your agent

   Add your content, check the details and try your agent. Under Website → Install on your website, add your website's domain.

2. In Hazelchat

   Copy the installation code

   Copy the installation code. It holds your public widget key, which is not a password.

3. In MODX

   Install the Extra

   MODX's directory doesn't list the Extra yet, so you upload it yourself. Download the package. In the Manager, open Extras → Installer, click the arrow beside Download Extras, choose Upload a package and pick the file (on MODX 2.8: Choose file(s), pick it, Upload, Close). Beside hazelchat in the list, click Install, then Continue and OK. Installing alone adds nothing to your site.

4. In MODX

   Paste the code

   Open Extras → Hazelchat, paste the code into Installation code and click Save. If you pasted a Hazelchat script into a template or chunk before, remove it so the chat loads once.

5. On your site

   Switch it on and test it

   Back in Hazelchat, click Publish and switch on (or Switch on if your published agent is unchanged). Hazelchat checks that the script is on your website before the agent goes live. Then open your website, ask a question in the chat, return to Hazelchat and click Yes, I saw this answer.

Send this to your developer

Your site is looked after by someone else? Copy this message, put your installation code where it says so, and send it to them.

Please add the Hazelchat chat to our MODX site:

1. Download the package:
   https://github.com/hazelchat-co/modx-hazelchat/releases/latest
2. Extras → Installer, arrow beside Download Extras,
   Upload a package. Then install it from the list.
3. Extras → Hazelchat, paste:
   [our installation code from Hazelchat]
   and save.

Guide: https://hazelchat.co/integrations/modx/

What the Extra does

It adds one script to the pages of your site and nothing else. Your content, answers, enquiries and billing all stay in your Hazelchat workspace.

The Extra adds https://app.hazelchat.co/widget.js, with your public key, just before </body> on every HTML page, including your error page. The Manager, AJAX requests, JSON, XML, feeds, file downloads and output without </body> stay as they are. It works after MODX's page cache, so a changed code reaches cached pages within seconds. The script address is fixed in the Extra and cannot be changed in its settings. Only a valid key is saved: anything else, such as an API key, is refused when you click Save. Only users with MODX's settings permission can change it. The Extra keeps only the key and one switch in two system settings, adds no tables and no public files, makes no requests from MODX to Hazelchat and sends nothing. It is free software under the MIT licence; its Manager page is in English and German.

Several sites in one MODX: a context setting named hazelchat.installation_code, holding the bare 64-character key, gives that context its own code.

Visitor consent

The chat sets no cookies and keeps only a reference to the conversation until the tab is closed. If you want visitors to allow the chat first, turn on Wait for my consent manager under Extras → Hazelchat.

The chat then stays closed and sends no chat requests until your consent tool allows it. Several tools work without further steps; for the others, let yours run this line (it also works when the tool replays a stored choice as the page loads):

(function (start) { document.readyState === 'loading' ? document.addEventListener('DOMContentLoaded', start) : start(); })(function () { window.dispatchEvent(new CustomEvent('hazelchat-consent', { detail: true })); });

Send detail: false when a visitor withdraws consent. The script file itself still loads with the page, so a visitor's IP address reaches Hazelchat before they agree. If your site must block that too, let your consent tool block the script. For ready settings for common cookie banners, see cookie banners.

Data and removal

The Extra does nothing until you save a code, and saving one is your choice. From then on, visitors' browsers load the chat from app.hazelchat.co (Hazelchat, Germany). Hazelchat collects the questions visitors type and, if they leave an enquiry, their name, email address and message. Conversations can also record the page they started on and any campaign tags in its address. Hazelchat uses this to answer visitors and to show you the conversations; see the privacy notice.

You can delete conversations in Hazelchat. To ask for any data to be removed, write to hello@hazelchat.co. The script tag carries the id hazelchat-modx: when Hazelchat checks your website, it reads this id to record that the chat was installed with this Extra, and it counts the Extra's installations that way.

If the chat does not appear

• No Hazelchat under Extras?

  Reload the Manager. You also need the settings permission to see it.

• "No action specified!"

  If MODX says this right after installing, wait a moment and reload. Its caches catch up within seconds.

• Check the code

  Paste the whole installation code, or only its 64-character key. Anything else is refused with one sentence when you save. A wrong value typed into System Settings prints nothing, and the Hazelchat page says so.

• Leave the script alone

  If a caching or optimising Extra or service rewrites your pages, or stores them before MODX finishes, exclude https://app.hazelchat.co/widget.js from combining or delayed loading and clear its cache.

• Content-Security-Policy

  If your server or an Extra sends one, allow https://app.hazelchat.co in script-src, connect-src and frame-src.

• A second domain

  The Free plan serves one website. A second MODX site on another domain needs a plan with more websites.

Change or remove

Updates and changes

New versions are on the Extra's release page. Upload the new one the same way; your code stays when you update.

1.0.0 (November 2026): adds the Hazelchat chat to every HTML page of a MODX 2.8 or 3 site from one installation code on its own page in the Manager; optional wait for your consent manager.