Add an AI chat agent to your October CMS site

What you need

Add Hazelchat to October CMS 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 October CMS

   Install the plugin

   Run composer require hazelchat/agent-plugin and then php artisan october:migrate in your October folder. Without a command line, download the latest release and put its hazelchat folder into plugins. Installing it alone loads nothing on your site.

4. In October CMS

   Paste the code in the back end

   Open Settings → Hazelchat, paste the code into Installation code and click Save. If you pasted a Hazelchat script into a layout 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 built and deployed 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 October CMS site:

1. composer require hazelchat/agent-plugin
   php artisan october:migrate
   (or put the release's "hazelchat" folder into plugins/).
2. In the back end, under Settings → Hazelchat, paste:
   [our installation code from Hazelchat]
   and save. The setting is kept in the database, so a deploy keeps it.
3. Give the people who should change it the
   "Change the Hazelchat settings" permission.

Guide: https://hazelchat.co/integrations/october-cms/

What the plugin 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 plugin adds https://app.hazelchat.co/widget.js, with your public key, just before </body> on every page October renders, whatever the theme or layout, on every site of a multisite installation. The back end, AJAX responses and pages without </body> never load the chat. The script address is fixed in the plugin 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. The plugin keeps only the key and one switch in October's settings table, adds no tables, routes or components, makes no requests from October to Hazelchat and sends nothing. Its back-end texts are in English and German, and it is free software under the MIT licence.

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 Settings → Hazelchat.

With OFFLINE.GDPR's cookie banner, add a cookie named Hazelchat (its code becomes hazelchat) to the group you choose. The plugin then adds the chat only for visitors who accepted it, from the next page they open. Until that cookie exists, Settings → Hazelchat reminds you in one sentence.

With another consent tool, the chat stays closed and sends no chat requests until your consent tool runs 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. If your site must block even the script download, let your consent tool block that script too. For ready settings for common cookie banners, see cookie banners.

If the chat does not appear

• No Hazelchat under Settings?

  Check that the folder is plugins/hazelchat/agent, that you ran php artisan october:migrate, and that your account has the Change the Hazelchat settings permission.

• Check the code

  Paste the whole installation code, or only its 64-character key. Anything else is refused with one sentence when you save.

• Using OFFLINE.GDPR?

  With Wait for my consent manager on, the chat appears only after a visitor accepts the Hazelchat cookie. Accept it yourself, then open another page.

• Leave the script alone

  If a caching or optimising plugin or service rewrites your pages, exclude https://app.hazelchat.co/widget.js from combining or delayed loading. A full-page cache stores the page as the first visitor saw it.

• Content-Security-Policy

  If your server or a plugin 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 October site on another domain needs a plan with more websites.

Change or remove

Updates and changes

Update with composer update hazelchat/agent-plugin, or by replacing the plugins/hazelchat/agent folder with the newer release, then run php artisan october:migrate.

1.0.0 (November 2026): adds the Hazelchat chat to every page of an October CMS 3 or 4 site, on any theme, from one installation code under Settings → Hazelchat; its own permission; optional wait for your consent manager, including OFFLINE.GDPR's cookie banner; English and German back-end texts.