Add an AI chat agent to your Kirby site

What you need

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

   Install the plugin

   With Composer, run composer require hazelchat/kirby-hazelchat. Without Composer, download the latest release and put its hazelchat folder into site/plugins. Installing it alone loads nothing on your site.

4. In Kirby

   Paste the code in the Panel

   Log in to the Panel as an administrator, open Hazelchat in the menu, paste the code into Installation code and click 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 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 Kirby site:

1. composer require hazelchat/kirby-hazelchat
   (or put the release's "hazelchat" folder into site/plugins).
2. In site/config/config.php, add:
   'hazelchat.kirby.code' => '[our installation code from Hazelchat]',
   (or paste it in the Panel under Hazelchat).
3. Deploy, and empty site/cache if the page cache is on.

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

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 HTML page of your site, in every language. The Panel, JSON, RSS and other content representations never load the chat. The Hazelchat dialog is for administrators only; it saves the key and one switch in your site content, and a value in config.php takes precedence. The plugin has no database, makes no requests from Kirby to Hazelchat and sends nothing. Its Panel texts are in English and German, and it is free software under the MIT licence.

Visitor consent

Kirby 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 Hazelchat dialog (or set 'hazelchat.kirby.consent' => true). The chat then 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. The plugin does not configure consent tools for you. 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 in the menu?

  Only administrators see it. Check that the folder is site/plugins/hazelchat and holds index.php.

• Empty the cache

  Saving in the dialog empties Kirby's page cache. After a change in config.php, empty site/cache yourself.

• Check the code

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

• 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

  Kirby sends none for your pages. If your server or a plugin does, allow https://app.hazelchat.co in script-src, connect-src and frame-src.

• A second domain

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

Change or remove

Updates and changes

With Composer, run composer update hazelchat/kirby-hazelchat. Without Composer, replace the site/plugins/hazelchat folder with the one from the latest release.

1.0.0 (October 2026): adds the Hazelchat chat to every page of a Kirby site, from one installation code in the Panel or config.php; optional wait for your consent manager; English and German Panel texts.