Add an AI chat agent to your Umbraco site

What you need

Add Hazelchat to Umbraco in four 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 two lines for your developer

   Choose Umbraco. Hazelchat shows the package and the setting with your key already in it. Click Copy for my developer. The key is public, not a password.

3. In your Umbraco project

   Add the package and the setting, then deploy

   Run dotnet add package Hazelchat.Umbraco, add "Hazelchat": { "InstallationCode": "your key" } to appsettings.json (or set the environment variable Hazelchat__InstallationCode), then build and deploy as usual. No template or Program.cs changes. If a Hazelchat script was pasted into a template before, remove it so the chat loads once.

4. 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 key where it says so, and send it to them. Hazelchat's install step gives you the same lines with your key filled in.

Please add the Hazelchat chat to our Umbraco site:

1. dotnet add package Hazelchat.Umbraco
2. In appsettings.json (or as the environment variable
   Hazelchat__InstallationCode on the live site):
   "Hazelchat": {
     "InstallationCode": "[our key from Hazelchat]"
   }
3. Build and deploy as usual. No template or Program.cs changes.
   Settings → Health Check → Hazelchat confirms the setting.

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

Leave the setting empty on staging and set it only on the live site if you do not want the chat there.

What the package 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 package adds https://app.hazelchat.co/widget.js, with your public key, just before </body> on every page Umbraco renders from its content, whatever the template, on every site of the installation. It changes only finished HTML pages: the back office, preview, the Delivery API and other APIs, media and other files, other controllers' pages and pages without </body> stay exactly as they are. The script address is fixed in the package. A setting that is not a valid key, such as an API key, prints nothing and leaves one warning in Umbraco's log. Settings → Health Check → Hazelchat shows whether the key is set and valid. The package stores nothing, adds no tables, routes or back-office screens, makes no requests from your site to Hazelchat and sends nothing. It is free software under the MIT licence.

Visitor consent

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, add "RequireConsent": true to the Hazelchat setting.

With Cookiebot or CookieTractor, the chat then follows the visitor's choice for preferences (Cookiebot) or functional cookies (CookieTractor) by itself. Usercentrics, Borlabs, CCM19, consentmanager and Complianz are recognised too; see cookie banners.

With another consent tool, the chat 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.

If the chat does not appear

• Check the health check

  In the back office, open Settings → Health Check → Hazelchat. It says whether the key is missing, not valid, or set.

• Check the setting

  Use the 64-character key from Hazelchat, under Hazelchat:InstallationCode. An environment variable wins over appsettings.json. Restart the site after changing environment variables.

• Compression after Umbraco

  Compression belongs before Umbraco (app.UseResponseCompression() before app.UseUmbraco()) or in your web server. If something compresses pages after Umbraco, the chat is not added.

• Caches and optimisers

  If a CDN or optimiser rewrites your pages, exclude https://app.hazelchat.co/widget.js from combining or delayed loading, and purge cached pages after deploying.

• Content-Security-Policy

  If your site sends one, allow https://app.hazelchat.co in script-src, connect-src and frame-src.

• A second domain

  The Free plan serves one website. Several sites in one Umbraco installation share one key; another domain needs a plan with more websites.

Change or remove

Updates and changes

Update with dotnet add package Hazelchat.Umbraco (it takes the newest version) or your NuGet tools, then deploy.

1.0.0 (November 2026): adds the Hazelchat chat to every content page of an Umbraco 13 to 18 site from one setting, with no template changes; optional wait for your consent manager; a Hazelchat health check.