Add an AI chat agent to your Contao website

What you need

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

   Install the extension

   In the Contao Manager, search for Hazelchat, add it and apply the changes; the Manager also updates the database. With Composer, run composer require hazelchat/contao-hazelchat and then vendor/bin/contao-console contao:migrate. Installing it alone loads nothing on your site.

4. In Contao

   Paste the code into your website root

   In the back end, open Site structure and edit your website root (the globe). Under Hazelchat, paste the code into Installation code and save. With one root per language on the same domain, one root is enough. If you pasted a Hazelchat script into a page 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 agency

No access to the Contao Manager? Copy this message, put your installation code where it says so, and send it to whoever looks after your site.

Please add the Hazelchat chat to our Contao website:

1. Install "Hazelchat" in the Contao Manager
   (or: composer require hazelchat/contao-hazelchat, then contao:migrate).
2. Site structure: edit our website root and, under Hazelchat,
   paste this into "Installation code":
   [our installation code from Hazelchat]
3. If we use Contao Cookiebar: add a cookie of the type "Hazelchat"
   to a group of our banner.

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

What the extension does

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

The extension adds https://app.hazelchat.co/widget.js, with your public key, just before </body> on every page below a website root that has the code, with classic and Twig page layouts. It stores only the key, so anything that is not a Hazelchat installation code is refused when you save. Other domains in the same Contao installation use their own code. It adds two fields to the website root and no tables, and sends nothing from Contao to Hazelchat; the back end never loads the chat. If the website root's Content-Security-Policy is on, the extension allows https://app.hazelchat.co for the chat. Its settings are in English and German, and it is free software under the LGPL, version 3 or later.

Cookie banners

Contao has no cookie banner of its own. With Contao Cookiebar (Oveleon), add a cookie to a group of your banner, for example a functional one, and choose the type Hazelchat. The chat then starts only after the visitor agrees in the banner, on every page, and stops when they decline. There is no script to paste and nothing else to switch on.

With another consent tool, turn on Wait for my cookie banner in the website root. The chat then stays closed and sends no chat requests until your tool sends this line once the visitor agrees:

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

Send detail: false when a visitor withdraws consent. Usercentrics, CCM19, consentmanager and several other tools work with a service named Hazelchat; cookie banners says what to do in each. If your site must block even the script download, let your consent tool block that script too.

If the chat does not appear

• Is the code in the website root?

  The code goes into the website root (the globe in the site structure), not into a normal page.

• Was the code refused?

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

• Did the visitor agree?

  With a Hazelchat cookie in Contao Cookiebar, or with the wait for your cookie banner on, the chat appears only after consent.

• 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 proxy sends its own policy, allow https://app.hazelchat.co in script-src, connect-src and frame-src there.

• A second domain

  The Free plan serves one website. A second domain needs a plan with more websites.

Change or remove

Updates and changes

The Contao Manager shows new versions with your other updates; with Composer, run composer update hazelchat/contao-hazelchat.

1.0.0 (21 October 2026): adds the Hazelchat chat to every page below a website root from one installation code; a "Hazelchat" cookie type for Contao Cookiebar; optional wait for any other cookie banner; English and German settings.