Add an AI chat agent to your Drupal site

What you need

Add Hazelchat to Drupal in six 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 Drupal

   Install the module

   Run composer require drupal/hazelchat in your site's folder, then turn on Hazelchat under Extend (or run drush en hazelchat). Installing it alone loads nothing on your site.

4. In Drupal

   Paste the code

   Go to Configuration → Web services → Hazelchat, paste the code into Installation code and click Save configuration. Only the key is kept. Drupal clears its own page caches for you.

5. In Drupal

   Remove old snippets

   If you pasted a Hazelchat script into your theme or a block before, remove it so the chat loads once. If a proxy or CDN caches your pages, clear it too.

6. 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.

What the module does

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

The module adds https://app.hazelchat.co/widget.js, with your public key, to the head of your public HTML pages. It stores only that key and one consent setting, has no database tables and no JavaScript of its own, and sends nothing from Drupal to Hazelchat. Administration pages and feeds never load the chat. Its settings page is in English and German, and it is free software under the GPL, version 2 or later.

Visitor consent

Klaro! If your site uses the Klaro! module (Drupal CMS includes it), the Hazelchat module adds a Hazelchat service to it, under Live chat. Klaro then holds the chat back until a visitor accepts it, and nothing loads from Hazelchat before that. Klaro only does this for roles with its Use Klaro! UI permission, so give that permission to anonymous users, as Klaro's own setup asks.

Other consent tools. Turn on Wait for my consent manager on the Hazelchat settings page. 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. With Wait for my consent manager on, the small script still downloads before consent. See also cookie banners for the consent tools Hazelchat follows by itself.

Caching and security headers

• Page caches

  Drupal's own caches update when you save the settings. Clear any proxy or CDN in front of the site yourself.

• 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 you send one (for example with the CSP module), allow https://app.hazelchat.co in script-src, connect-src and frame-src.

Change or remove

Updates and changes

New versions are published on drupal.org. Drupal's Update Status module tells you about them, and composer update drupal/hazelchat installs them.

1.0.0: adds the Hazelchat chat to every public page with one installation code; works with Klaro!; optional wait for your consent manager; English and German.