Add an AI chat agent to your Craft site

What you need

Add Hazelchat to Craft 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 Craft

   Install the plugin

   Open Plugin Store in the control panel, search for Hazelchat and install it. It is free. With Composer, run composer require hazelchat/craft-hazelchat and php craft plugin/install hazelchat. Installing it alone loads nothing on your site.

4. In Craft

   Paste the code

   Open Settings → Plugins → Hazelchat, paste the code into Installation code and save. If you pasted a Hazelchat script into a template 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 agency

Your agency runs the site? Copy this message, put your installation code where it says so, and send it to them.

Please add the Hazelchat chat to our Craft site:

1. Install the free plugin "Hazelchat" from the Plugin Store
   (or composer require hazelchat/craft-hazelchat, then
   php craft plugin/install hazelchat).
2. Under Settings → Plugins → Hazelchat, paste this into
   "Installation code" (or set it as HAZELCHAT_KEY in .env
   and enter $HAZELCHAT_KEY):
   [our installation code from Hazelchat]
3. Save, and deploy the project config to production.

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

What the plugin does

It adds one script to the pages of your sites 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 Craft renders from your site templates. It keeps only the key and its settings in the project config, has no database tables, and sends nothing from Craft to Hazelchat. The control panel, previews and the console never load the chat, and neither do templates without a </body> tag, such as JSON. Its settings are in English and German, and it is free software under the MIT licence.

Several sites and environments

Every site in one Craft installation uses the same code. With more than one site, open More in the plugin settings to switch the chat off for a site or give it its own code.

Instead of the code you can enter an environment variable such as $HAZELCHAT_KEY and set it in each environment's .env. Where admin changes are off in production, set the plugin up in development and deploy the project config as usual.

Visitor consent

Craft has no cookie banner of its own. If your consent tool must allow the chat first, turn on Wait for my consent manager in the plugin settings. The chat then stays closed and sends no chat requests until your consent tool tells it to start:

window.dispatchEvent(new CustomEvent('hazelchat-consent', { detail: true }));

Send detail: false when a visitor withdraws consent. Usercentrics, CCM19, consentmanager and other common tools can start it for you; see the cookie banner guide. If your site must block even the script download, let your consent tool block that script too.

If the chat does not appear

• Check the code

  Paste the whole installation code, or only its 64-character key. Anything else, such as an API key, is refused when you save.

• Check your layout

  Craft adds the script before </body>. A layout without that tag gets nothing.

• Clear static caches

  If a static cache such as Blitz serves your pages, clear it after you install or change the code.

• Leave the script alone

  Exclude https://app.hazelchat.co/widget.js from script combining, rewriting or delayed loading. The script must keep its own address and key.

• Content-Security-Policy

  If your server or a plugin sends a policy, allow https://app.hazelchat.co in script-src, connect-src and frame-src.

• A second domain

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

Change or remove

Updates and changes

Craft shows new versions under Utilities → Updates; with Composer, run composer update hazelchat/craft-hazelchat.

1.0.0 (20 October 2026): adds the Hazelchat chat to the pages of every site from one installation code or an environment variable; per site, switch it off or use another code; optional wait for your consent manager; English and German settings.