Introduction
This guide walks you through installing the Airgentic module for Drupal (Drupal 10.3 or later, Drupal 11, and Drupal CMS). The module 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 module and enter your Account ID and Service ID once. The module includes a ready-made search results page, and points your existing search box at it. The Service Hub and Site Search are also available as blocks, which you can place with the block layout, Layout Builder or Drupal Canvas.
New installs start in Testing Mode: only logged-in Drupal users see Airgentic, at 100%. Turn Testing Mode off when you are ready for visitors.
1. Prerequisites
- Drupal 10.3 or later, Drupal 11, or Drupal CMS
- Developer access — someone who can add a module to the site's code and deploy it
- 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 module
The module installs from a zip file. It is not yet listed on drupal.org.
- Download airgentic-drupal.zip.
- Unzip it into
web/modules/custom/in your Drupal project (create the folder if it doesn't exist), so the module is atweb/modules/custom/airgentic. On sites without awebfolder, usemodules/custom/. - Go to Extend, tick Airgentic (under Web services) and click Install. Or run the command below.
- Commit the
airgenticfolder with your site code and deploy as usual. If you deploy configuration withdrush config:export, export after installing and configuring the module.
drush en airgentic3. Configure global settings
- Go to Configuration → Web services → Airgentic (
/admin/config/services/airgentic). - Enter Account ID and Service ID (required).
- Leave Enable Airgentic on the front-end on and click Save configuration.
Leave Search mode on None if you only want chat. Only users with the Administer Airgentic permission can change these settings.
Settings per environment
Any setting can be fixed in settings.php, for example to read the IDs from environment variables or keep Testing Mode on in staging:
$config['airgentic.settings']['account_id'] = getenv('AIRGENTIC_ACCOUNT_ID');
$config['airgentic.settings']['service_id'] = 'website';
$config['airgentic.settings']['testing_mode'] = FALSE;Settings in settings.php take precedence over the settings page, which shows a warning listing them.
Testing Mode (default for new installs)
- New installs have Testing Mode on.
- Log in to Drupal 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 module were not installed.
- When you are ready for visitors, untick Testing Mode and save. Drupal's page cache is cleared automatically, so visitors see Airgentic straight away.
View source of a front-end 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. Admin pages never include it.
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.
- On the Airgentic settings page, set Show to % of visitors (for example
20). The field is ignored while Testing Mode is on. - Click Save configuration.
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
Place the Airgentic Service Hub block where you want the full chat window:
- Block layout (Structure → Block layout): place it in the Content region, and under Pages restrict it to the page that should show it, for example
/contact. - Layout Builder: add it to the page's layout from the Airgentic category.
- Drupal CMS and Canvas: open the page in Canvas and add Airgentic Service Hub from the Blocks section of the component library.
The block outputs <div id="airgentic"></div>.
5. Add Site Search (inline, recommended)
Inline search is a results page on your site plus autocomplete on your existing search box. Visitors type in the search box, press Enter, and land on the results page.
For the full visitor journey and Ask-tab behaviour, see Site Search Website Integration.
5.1 The search results page
The module includes a results page at /airgentic/search, so there is nothing to build.
- On the Airgentic settings page, set Search mode to Inline.
- Leave Search page as
/airgentic/search. - Click Save configuration.
To give the page a friendlier address, add a URL alias at Configuration → Search and metadata → URL aliases, with system path /airgentic/search and an alias such as /site-search. Links to the page use the alias automatically.
To show results on a page of your own instead, place the Airgentic Site Search block on it (block layout, Layout Builder or Canvas) and enter that page's path as the Search page. The block outputs:
<div data-airgentic="search"></div>If the site already has a search page from Drupal core search or a Search API view, you can leave it in place. Your search box sends visitors to the Airgentic page instead.
5.2 Your header search box
The module finds your search box by the name of its text field. The default, keys, keywords, covers both common cases:
- Drupal core search (the Search form block, used by most Drupal 10 and 11 themes such as Olivero) uses
keys. - Drupal CMS search (the search block added by the Drupal CMS Search recipe) uses
keywords.
Leave Send the site search box to the Airgentic search page on. The module points every form containing one of those fields at your Search page, renames the field to query, and turns on autocomplete. A search for rates should open:
/airgentic/search?query=rates
If your theme uses a different search field, right-click it, choose Inspect, and add the input's name attribute to Search input name (separate several with commas).
While Testing Mode is on, the change applies only when you are logged in. Logged-out visitors keep your existing search.
5.3 Drupal CMS: headers built in Canvas
In Drupal CMS, the default Mercury theme builds the header and footer in Drupal Canvas. Blocks placed in Structure → Block layout do not appear in a Canvas header. To add a search box to the header, edit the header region in Canvas and add the Drupal CMS search block (or Airgentic Service Hub, if you want it there) from the Blocks section of the component library.
The module rewrites the Drupal CMS search box wherever it appears, so you don't need to change anything else. The chat widget itself is added to every page automatically and needs no Canvas changes.
5.4 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.5 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
/airgentic/search?query=…(or your alias). - 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.
- Enter Search input ID or class (and optionally the button). Drupal core's search field has the id
edit-keys. - Click Save configuration.
The search results page and the search box rewrite are not used in this mode.
7. Optional settings
Under Advanced on the settings page:
- 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 the Airgentic settings page: Account ID and Service ID are set and Enable Airgentic on the front-end is on.
- If Testing Mode is on, log in to Drupal. 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
settings.phpis not overriding the setting you changed (the settings page lists any overrides). - Confirm your Content-Security-Policy (for example from the CSP or Security Kit modules) allows
https://chat.airgentic.comfor scripts, connections, frames, styles and images. - View page source for
<script id="airgentic-script".
Inline search page is empty
- If Testing Mode is on, log in — logged-out visitors do not load the script.
- If you use your own page, confirm the Airgentic Site Search block is placed on it.
- 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 is set, and Send the site search box to the Airgentic search page 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 at Configuration → Development → Performance.
Block placed but not appearing (Drupal CMS)
- The header and footer are built in Canvas. Add the block in Canvas rather than in Block layout (see 5.3).
Duplicate widget
- Remove any hardcoded Airgentic script from your theme or from modules such as Asset Injector. Use the module only once.
Caching / CDN
- Drupal's own page cache is handled automatically. If you also use Varnish, Cloudflare, Fastly or Acquia or Pantheon edge caching, purge it after turning Testing Mode off or changing settings.
9. Removing the integration
Uninstall the module at Extend → Uninstall (or run drush pm:uninstall airgentic), then delete the web/modules/custom/airgentic folder. Uninstalling removes the module's settings and any Airgentic blocks you placed. The module adds no database tables.