Add an AI chat agent to your Grav site

What you need

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

   Install the plugin

   In the admin, open Plugins, click Add and install Hazelchat. Or run bin/gpm install hazelchat. Installing it alone loads nothing on your site. Without Grav's plugin list, download grav-plugin-hazelchat-1.0.1.zip and upload it under Tools → Direct Install, or unzip it into user/plugins.

4. In Grav

   Paste the code in the admin

   In the admin, open Plugins → Hazelchat, paste the code into Installation code and click Save. If you pasted a Hazelchat script into a theme 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 Grav site:

1. Run bin/gpm install hazelchat
   (or add the Hazelchat plugin under Plugins in the admin).
2. In user/config/plugins/hazelchat.yaml:
   enabled: true
   code: '[our installation code from Hazelchat]'
   (or paste it in the admin under Plugins → Hazelchat).
3. Deploy, then run bin/grav clearcache.

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

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 admin and pages in other formats, such as JSON or RSS, never load the chat. The script address is fixed in the plugin and cannot be changed in its settings. The plugin keeps only the code and one switch in user/config/plugins/hazelchat.yaml, adds no database tables, makes no requests from Grav to Hazelchat and sends nothing. Its admin texts are in English and German, and it is free software under the MIT licence.

Visitor consent

With Grav's Consent plugin (Grav 2), there is nothing to set up. Hazelchat appears on the banner under Necessary: 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 in the plugin's settings. Hazelchat then moves to Functional, starts once a visitor allows that category, without a page reload, and forgets the conversation if they withdraw it. Consent asks your visitors once more after a plugin adds something to its list.

With another consent tool, turn on Wait for my consent manager. 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. 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 Plugins?

  Check that the folder is user/plugins/hazelchat and holds hazelchat.php, and that the plugin is enabled.

• "Only official GPM URLs are allowed"?

  By default, Grav installs from a web address only if it is on getgrav.org. Run bin/gpm install hazelchat instead, or download the zip first, then upload it or give bin/gpm direct-install the file.

• Clear the cache

  Saving in the admin is enough. After a change in user/config/plugins/hazelchat.yaml, run bin/grav clearcache.

• Check the code

  Paste the whole installation code, or only its 64-character key. Anything else, such as an API key, shows nothing, and Hazelchat's check will say it cannot find the chat.

• Leave the script alone

  Grav's asset pipeline does not touch the script. If a caching or optimising service rewrites your pages, exclude https://app.hazelchat.co/widget.js from combining or delayed loading.

• Content-Security-Policy

  Grav 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 Grav site on another domain needs a plan with more websites.

Change or remove

Updates and changes

Update under Plugins in the admin, or run bin/gpm update hazelchat. Without Grav's plugin list, download the new zip and upload it under Tools → Direct Install, or replace the user/plugins/hazelchat folder.

1.0.1 (November 2026): no change in how the plugin works. The README now says how installations are counted, that the script file loads before consent, and when to turn the consent switch on.

1.0.0 (November 2026): adds the Hazelchat chat to every HTML page of a Grav 1.7 or Grav 2 site, from one installation code in the plugin's settings; optional wait for your consent manager; lists Hazelchat on the banner of Grav's Consent plugin; English and German admin texts.