Introduction
This guide walks you through installing the Airgentic plugin for Craft CMS (Craft 4 and Craft 5). The plugin adds:
- A hover widget that appears on every page (bottom-right launcher)
- An optional Service Hub UI on selected pages only
- Optional Site Search — a search results page on your site (recommended), or an overlay popup as an alternative
You install one plugin and enter your Account ID and Service ID once. Your developer then places the Service Hub or Site Search in your templates with a Twig function. For inline search, the plugin also points your existing header search form at the results page.
New installs start in Testing Mode: only logged-in Craft users see Airgentic, at 100%. Turn Testing Mode off when you are ready for visitors.
1. Prerequisites
- Craft CMS 4 or 5
- PHP 8.0.2 or later for Craft 4, or 8.2 or later for Craft 5
- Developer access — someone who can run Composer and Craft console commands and deploy the site
- Airgentic IDs — have your Account ID and Service ID handy
- Site Search (optional) — ask Airgentic support to confirm inline search is enabled for your service
2. Install the plugin
The plugin installs with Composer from a folder in your project. It is not yet listed in the Craft Plugin Store.
- Download airgentic-craft.zip.
- Create a
pluginsfolder in the root of your Craft project and unzip the file into it, so the plugin is atplugins/airgentic. - From the project root, run the commands below.
- Commit
composer.json,composer.lock, theplugins/airgenticfolder andconfig/project/, then deploy as usual.
composer config repositories.airgentic '{"type": "path", "url": "plugins/airgentic"}'
composer require airgentic/craft-airgentic:^1.0
php craft plugin/install airgenticOn DDEV, put ddev in front of each command, for example ddev composer require airgentic/craft-airgentic:^1.0 and ddev craft plugin/install airgentic.
3. Configure global settings
- Go to Settings → Plugins → Airgentic.
- Enter Account ID and Service ID (required). Both accept environment variables, for example
$AIRGENTIC_ACCOUNT_ID. - Leave Enable on front-end on and click Save.
Leave Search mode on Disabled if you only want chat.
Production sites
Craft stores plugin settings in project config. Most production sites turn allowAdminChanges off, so the settings page can't be saved there. Either change the settings in your development environment and deploy the project config, or set them in config/airgentic.php:
<?php
return [
'accountId' => '$AIRGENTIC_ACCOUNT_ID',
'serviceId' => 'website',
'testingMode' => false,
'searchMode' => 'inline',
'searchPageUrl' => '/search',
];Settings in that file take precedence over the control panel, and the settings page shows a warning beside each one.
Testing Mode (default for new installs)
- New installs have Testing Mode on.
- Log in to Craft and browse the live site. Logged-in users see chat, search and Service Hub at 100% — Show to % of visitors is ignored.
- Logged-out visitors do not get the Airgentic script, and your search forms are left alone, so the public site behaves as if the plugin were not installed.
- When you are ready for visitors, turn Testing Mode off and save (or set
'testingMode' => falseinconfig/airgentic.php).
View source of a page while logged in and look for:
<script id="airgentic-script"
src="https://chat.airgentic.com/_js/airgentic-1.4.js" defer
data-account-id="YOUR_ACCOUNT_ID"
data-service-id="YOUR_SERVICE_ID"></script>A logged-out (or private) window should not include that script until Testing Mode is off.
Show to a percentage of visitors (optional)
After Testing Mode is off, you can show the floating chat widget to only some browsers — for example during a launch.
- In Settings → Plugins → Airgentic, set Show to % of visitors (for example
20). The field is ignored while Testing Mode is on. - Click Save.
Leave the field blank (or 100) to show Airgentic to everyone. 0 hides the launcher for all visitors. The script tag then includes data-traffic-percent="20".
Each browser is assigned once and stays in the same group. Search and Service Hub pages always load, so those pages are never empty. Append ?airgentic=1 or ?airgentic=0 to a URL to force Airgentic on or off in your own browser.
4. Add the Service Hub to selected pages
Add this Twig function to the template where you want the full chat window:
{{ airgenticServiceHub() }}- Outputs
<div id="airgentic"></div> - Place it wherever the Service Hub should appear, for example in the template of a Contact or Help page
5. Add Site Search (inline, recommended)
Inline search is a results page on your site (for example /search) plus autocomplete on your existing header search field. Visitors type in the header, press Enter, and land on the results page.
For the full visitor journey and Ask-tab behaviour, see Site Search Website Integration.
5.1 Create the search results page
- Create a template for the results page, for example
templates/search.twig, or use the template of an existing Search page. - Output
{{ airgenticSearch() }}where the results should appear (see the example below). If that template already lists Craft's own search results, replace that markup. - In Settings → Plugins → Airgentic, set Search mode to Inline search and Search page URL to the page's address (for example
/search). - Click Save.
A minimal search template:
{% extends '_layout' %}
{% block content %}
{{ airgenticSearch() }}
{% endblock %}The search function outputs:
<div data-airgentic="search"></div>5.2 Your header search form
Craft has no standard search form, so the plugin finds yours by the name of its text field.
- Right-click the header search field and choose Inspect.
- Note the input's
nameattribute. Craft templates usually useq. - Enter it in Search input name, and leave Rewrite site search forms on.
The plugin points every form containing that field at your Search page, renames the field to query, and turns on autocomplete. A search for rates should open:
/search?query=rates
While Testing Mode is on, the rewrite applies only when you are logged in. Logged-out visitors keep your existing search.
5.3 Search boxes that are not forms
If your header search is not a normal form (for example a field that runs JavaScript instead of submitting):
- Right-click the field and choose Inspect.
- Copy the input's id, or a class name with a leading dot (for example
.header-search). - Paste it into Search input ID or class.
- Fill Search button ID or class only if the button does not submit the form.
5.4 Test the visitor journey
- Stay logged in if Testing Mode is on.
- Open the homepage.
- Type a query in the header — autocomplete should appear.
- Press Enter and confirm the URL becomes
/search?query=…. - Confirm results render on the search page.
- If the Ask tab is enabled, repeat with a question (for example When is my bin collected?) and confirm the answer starts.
6. Overlay search (alternative)
Use overlay search when you want a popup instead of a results page.
- Set Search mode to Overlay search.
- Enter Search input ID or class (and optionally the button).
- Do not add
{{ airgenticSearch() }}to a template. - Click Save.
7. Optional settings
- Open-chat button ID or class — your own button or link that opens the chat widget.
- Extra script attributes — other script tag options from the JavaScript Integration guide, one per line, for example
data-hover-widget-expanded=true.
8. Troubleshooting
Widget not showing at all
- Check Settings → Plugins → Airgentic: Account ID and Service ID are set and Enable on front-end is on.
- If Testing Mode is on, log in to Craft. A private or logged-out window will not show Airgentic.
- If Show to % of visitors is below 100 (and Testing Mode is off), the launcher is hidden for some browsers. Append
?airgentic=1to the URL to force it on. - Check that
config/airgentic.phpis not overriding the setting you changed. - Confirm your Content-Security-Policy allows
https://chat.airgentic.comfor scripts, connections, frames, styles and images. - View page source for
<script id="airgentic-script".
Inline search container is empty
- Confirm
{{ airgenticSearch() }}is in the search page template. - If Testing Mode is on, log in — logged-out visitors do not load the script.
- Ask Airgentic support to confirm inline search is enabled for the service.
Header search still goes to the old results page
- Confirm Search mode is Inline, Search page URL is set, and Rewrite site search forms is on.
- Confirm Search input name matches the
nameattribute of the live field. - If Testing Mode is on, log in. The rewrite does not run for logged-out visitors.
- Clear caches after saving.
Service Hub not appearing
{{ airgenticServiceHub() }}must be in the template that renders the page, and not inside hidden markup.- If Testing Mode is on, log in.
Duplicate widget
- Remove any hardcoded Airgentic script from your templates. Use the plugin only once.
Caching / CDN
- If you use Blitz, a CDN page cache or Varnish, make sure pages viewed by logged-in users are not cached while Testing Mode is on, and clear the cache after changing settings.
9. Removing the integration
Remove {{ airgenticServiceHub() }} and {{ airgenticSearch() }} from your templates first — once the plugin is gone, Craft reports an error for any template that still calls them. Then uninstall the plugin in Settings → Plugins (or run php craft plugin/uninstall airgentic) and run composer remove airgentic/craft-airgentic. The plugin stores only its settings in project config (no custom tables).