Introduction

This guide walks you through installing the Airgentic plugin for WordPress (version 1.3.1 or later). The plugin has three modes:

  • A hover widget that appears on every page (bottom-right launcher)
  • An optional Service Hub UI on selected pages only
  • Optional Site Search — a dedicated search results page (recommended), or an overlay popup as an alternative

You install one plugin and enter your Account ID and Service ID once. Editors can then place the Service Hub or Site Search UI with a shortcode. For inline search, the plugin can also point the WordPress Search block, Search widget, and theme search form at your results page.

New installs start in Testing Mode: only logged-in WordPress users see Airgentic, at 100%. Turn Testing Mode off when you are ready for visitors.

1. Prerequisites

  • WordPress 5.8 or later (tested up to 6.8)
  • PHP 7.4 or later
  • Permissions — a user with Administrator rights who can install plugins and edit pages
  • 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

Option A – WordPress.org (recommended)

  1. Go to Plugins → Add New.
  2. Search for Airgentic.
  3. Install and activate Airgentic AI Chat Overlay.
  4. You will see Settings → Airgentic.

The directory listing is wordpress.org/plugins/airgentic-ai-chat-overlay.

Option B – Upload a ZIP

  1. Download airgentic.zip.
  2. Go to Plugins → Add New → Upload Plugin.
  3. Choose the ZIP, click Install Now, then Activate.
  4. You will see Settings → Airgentic.

3. Configure global settings

  1. Go to Settings → Airgentic.
  2. Enter Account ID and Service ID (required).
  3. Tick Enable on Front-end and click Save Settings.

Leave Search mode on Disabled if you only want chat.

Testing Mode (default for new installs)

Plugin 1.3.1 and later can keep Airgentic off the public site while you preview it.

  1. New installs have Testing Mode ticked. Existing sites stay off on upgrade, so visitors are not hidden after you update.
  2. Stay logged in to WordPress and browse the live site. Logged-in users see chat, search, and Service Hub at 100% — Show to % of visitors is ignored.
  3. Logged-out visitors do not get the Airgentic script, and native WordPress search is left alone, so the public site behaves as if the plugin were not installed.
  4. When you are ready for visitors, untick Testing Mode and save.

View source of a page while logged in and look for:

<script async id="airgentic-script"
    src="https://chat.airgentic.com/_js/airgentic-1.4.js"
    data-account-id="YOUR_ACCOUNT_ID"
    data-service-id="YOUR_SERVICE_ID"
    defer></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, plugin 1.3.0 and later can show the floating chat widget to only some browsers — for example during a launch.

  1. In Settings → Airgentic, set Show to % of visitors (for example 20). The field is ignored while Testing Mode is on.
  2. Save Settings.

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:

<script async id="airgentic-script"
    src="https://chat.airgentic.com/_js/airgentic-1.4.js"
    data-account-id="YOUR_ACCOUNT_ID"
    data-service-id="YOUR_SERVICE_ID"
    data-traffic-percent="20"
    defer></script>

Each browser is assigned once and stays in the same group. Dedicated search ([airgentic_search]) and Service Hub pages always load, so those pages are never empty. Append ?airgentic=1 or ?airgentic=0 to a URL to force the widget on or off while testing.

Show the chat icon sooner

The plugin waits until the page has finished loading before it starts the floating chat icon, so Airgentic does not compete with the page's images. There is no plugin setting for this.

If you add the script tag yourself — in a theme file, the Code Snippets plugin, or Google Tag Manager — add data-boot="early" to that tag. See the JavaScript Integration guide.

4. Add the Service Hub to selected pages

Add this shortcode where you want the full chat window:

[airgentic_service_hub]

  • Works in the block editor (Shortcode block) or the Classic Editor
  • Outputs <div id="airgentic"></div>
  • Place it wherever the Service Hub should appear

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 /search?query=… with results, scopes, filters, and the AI summary.

The plugin can create that page and rewrite native WordPress search forms. You do not need to inspect HTML for the Search block or Search widget.

For the full visitor journey and Ask-tab behaviour, see Site Search Website Integration.

5.1 Create the search results page

  1. In Settings → Airgentic, set Search mode to Inline search.
  2. Click Create Search page. That publishes a page titled Search (slug search) containing [airgentic_search].
  3. If you prefer to create the page yourself, add [airgentic_search] to a page and select it under Search page.
  4. Leave Rewrite WordPress search forms and Redirect WordPress searches checked.
  5. Save Settings.

The search shortcode outputs:

<div data-airgentic="search"></div>

The plugin does not create a page on activation. Create Search page runs only when you click the button.

5.2 Native WordPress search forms

With rewrite enabled, the plugin updates:

  • the Search block (including in the site header)
  • the Search widget
  • the theme’s get_search_form() form

Each form is pointed at your Search page, the input name is set to query, and autocomplete is turned on. A search for engineering should open:

/search?query=engineering

?s= URLs are redirected to the same page so leftover WordPress searches still land on Airgentic.

While Testing Mode is on, rewrite and redirect apply only when you are logged in. Logged-out visitors keep native WordPress search.

5.3 Custom header search fields

If your header search is custom HTML (not the Search block or widget):

  1. Right-click the field and choose Inspect.
  2. Copy the input’s id, or a class name with a leading dot (for example .header-search).
  3. Paste it into Search input ID or class.
  4. Fill Search button ID or class only if the button does not submit the form.

5.4 Test the visitor journey

  1. Stay logged in if Testing Mode is on.
  2. Open the homepage.
  3. Type a query in the header — autocomplete should appear.
  4. Press Enter and confirm the URL becomes /search?query=….
  5. Confirm results render on the search page.
  6. If the Ask tab is enabled, repeat with a question (for example How do I enrol?) and confirm the answer starts. Then paste that URL into a new tab: Ask should open with the question typed but not run by itself.

6. Overlay search (alternative)

Use overlay search when you want a popup instead of a results page.

  1. Set Search mode to Overlay search.
  2. Enter Search input ID or class (and optionally the button).
  3. Do not add [airgentic_search] to a page.
  4. Save Settings.

Existing 1.1.0 installs that already filled a search input ID stay on overlay after upgrading, until you change Search mode.

7. Updating the plugin

  1. Update from Dashboard → Updates, or upload the new ZIP.
  2. Overlay search from 1.1.0 is unchanged if you already had a search input ID.
  3. To switch to inline search, set Search mode to Inline, click Create Search page, and save.
  4. 1.3.0: optional Show to % of visitors. Existing sites are unchanged until you set a percentage below 100.
  5. 1.3.1: Testing Mode is on for new installs and off for existing sites. Untick it when you are ready for visitors.

8. Troubleshooting

Widget not showing at all

  • Check Settings → Airgentic: Account ID and Service ID are set and Enable on Front-end is ticked.
  • If Testing Mode is on, log in to WordPress. 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=1 to the URL to force it on, or clear the field to show it to everyone.
  • Confirm your Content-Security-Policy allows scripts from https://chat.airgentic.com.
  • View page source for <script id="airgentic-script".

Inline search container is empty

  • Confirm [airgentic_search] is on the Search page.
  • If Testing Mode is on, log in — logged-out visitors do not load the script.
  • Ask Airgentic support that inline search is enabled for the service.

Header search still goes to `/?s=`

  • Confirm Search mode is Inline, a Search page is selected, and Rewrite WordPress search forms is checked.
  • If Testing Mode is on, log in. Rewrite does not run for logged-out visitors.
  • If the field is custom HTML, fill Search input ID or class.
  • Purge caches after saving.

Autocomplete does not appear

  • For the Search block, use Rewrite WordPress search forms (no id needed).
  • For custom HTML, the id or class must match the live field. Class names may start with a dot.

Overlay opens instead of the results page

  • Search mode is still Overlay. Switch to Inline search.

Service Hub not appearing

  • [airgentic_service_hub] must be on the page and not inside a hidden block.
  • If Testing Mode is on, log in.

Duplicate widget

  • Remove any hardcoded Airgentic script from the theme. Use the plugin only once.

Caching / CDN

  • After install or a settings change, purge page cache and any CDN. Most WordPress caches already vary on the logged-in cookie; if a host serves one HTML file to everyone, Testing Mode preview will not work until logged-in users are excluded from that cache.

9. Removing the integration

Deactivate or delete the plugin. The script tag and shortcode output disappear. The plugin stores only options in the WordPress options table (no custom tables). If you created a Search page, delete that page separately if you no longer need it.