Introduction

This guide shows you how to install and use the Airgentic Widget on a Squiz Matrix website.

The Airgentic widget has three modes:

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

You’ll use a reusable Component Template to inject the necessary script and configuration. One instance is added to your global layout to activate the hover widget site-wide (and, if you want search, to bind the header search field). Editors can then place the Service Hub or Site Search UI wherever needed by inserting the component on specific pages and ticking a checkbox. No metadata fields or head edits are required.

Inline Site Search also needs a small Design / Paint Layout change so existing search forms submit to your new search page. Overlay search skips that step.

1. Prerequisites

  • Matrix DXP version – Component Templates arrived in Matrix 6 and back-ported to late 5.5. You must be running Squiz Matrix DXP in the cloud to use this component. If you can see “Component Templates” in the asset tree you’re good.
    • create assets under Design & Layout → Component Templates
    • edit the site’s Design or Paint Layout (needed for inline search forms)
    • edit page contents
  • 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. You will also need permission to create a Standard Page and to edit the site Design or a global Paint Layout.

2. Install the component template

Option A – Import from URL

  1. Go to /_admin (Admin Mode).
  2. In the asset tree, right-click Design & Layout → Component Templates → New Child → Component Template.
  3. In the Details screen, choose Import manifest from URL, and copy/paste this URL:

https://chat.airgentic.com/_integrations/matrix/airgentic_component.json

  1. Unlock & Commit; the template appears with a green “Notice” status.
  2. Under Allowed Root Nodes, pick the site root so editors can see it, then change status to Live.

Option B – Upload the JSON file

Use the same steps as above, but download the Airgentic component.

Then choose Upload manifest file and browse to airgentic_component.json. The asset now behaves like any other template — you can rename, move, or clone it.

The imported template is named Airgentic Widget (v1.3).

3. Add the hover widget globally

We need exactly one script tag site-wide, so we’ll nest a single instance of the component into your design.

  1. Create a hidden Standard Page called “Airgentic Global Widget” anywhere outside navigation.
  2. Edit Contents → + to Add Component → choose Code (or any type).
  3. Click the gear icon, find Template, pick Airgentic Widget (v1.3), and fill in Account ID & Service ID.
  4. Leave the Service Hub and Site Search checkboxes unticked on this global instance.
  5. If you plan to use Site Search, fill in Search input ID or class with the id (or class name) of your header search field. Leave Overlay search unticked for inline search. Finding the field ID is covered in section 5.2.
  6. Make the page Live.
  7. Open your site Design or a global Paint Layout. At the bottom of the <body> (just before </body> is safest) add a Nest Content Design Area that points to the component asset ID of the code block you just made.

Example parse-file snippet:

<MySource_AREA id_name="airgentic_global" design_area="nest_content">
  <MySource_SET name="assetid" value="12345" />
</MySource_AREA>
  1. Save & commit the design. Publish a page and view source — you should see <script id="airgentic-script" …></script> on every page.

4. Add the Service Hub to selected pages

  1. Open any page in Edit Contents.
  2. Press + (Add Component), pick Code (or a suitable component type).
  3. In Properties, select Airgentic Widget (v1.3), fill (or paste) the same Account/Service IDs, tick Insert `<div id="airgentic">`, Save.
  4. Drag the component up or down in the components list to control where the div lands. Matrix writes components to the DOM in that order.
  5. Publish. The full chat window now appears exactly where you placed the div.

5. Add Site Search (inline, recommended)

Inline search is a dedicated results page on your website (for example /search) plus autocomplete on your existing header search field. The visitor types in the header, presses Enter, and lands on /search?query=… with results, scopes, filters, and the AI summary.

The component can place the search UI and bind the header field. It cannot change the site’s existing search forms — those almost always live in the Design parse file or a global Paint Layout, so a designer or developer needs to update them.

For the full visitor journey, Ask-tab behaviour, and generic HTML examples, see Site Search Website Integration. If you are replacing Funnelback, also see Funnelback Migration.

5.1 Create the search results page

  1. Create a Standard Page with a public URL such as /search (or reuse an existing search page and replace its contents).
  2. Edit Contents → + Add Component → Code (or a suitable type).
  3. In Properties, select Airgentic Widget (v1.3), fill in the same Account/Service IDs, tick Insert Site Search UI, leave Overlay search and Service Hub unticked, Save.
  4. Drag the component to where the search experience should render.
  5. Make the page Live.

The component outputs:

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

5.2 Bind the header search field

On the global nested instance from section 3:

  1. Right-click the site’s header search field in a browser and choose Inspect.
  2. Copy the input’s id. If it has no id, use a class name (with or without a leading dot), for example header-search or .header-search.
  3. If the field has no stable id or class, add one in the Design parse file.
  4. Paste that value into Search input ID or class. Leave Overlay search unticked.
  5. If your search button does not submit the form normally, also fill Search button ID or class.
  6. Save the global instance and re-commit the design if needed.

5.3 Update every site search form

In the Design parse file (or each search box asset), update header, homepage, and mobile search forms so they submit to the Airgentic search page:

  • Form action — your search page path (for example /search), so visitors land on the Airgentic results page
  • Form method — get, so the query is in the URL
  • Input name — query, which is the URL parameter Airgentic reads

When a visitor searches for engineering, the browser must open:

/search?query=engineering

Many Matrix sites already have a Funnelback search page. Point the forms at the new Airgentic page, or redirect the old Funnelback URL to /search.

5.4 Test the visitor journey

  1. Open the homepage (or any page with the search field).
  2. Type a query — autocomplete suggestions should appear.
  3. Press Enter and confirm the browser opens /search?query=….
  4. Confirm results, scopes, and filters render on the search page.
  5. 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. That safeguard stops search engines and bots from triggering AI requests. Answering a question costs an AI request, so a question URL on its own is never enough to trigger one. Keep using a normal GET form with name="query".

6. Overlay search (alternative)

Use overlay search when you cannot change the Design parse file, or when you want search to open as a popup instead of a separate page.

  1. On the global nested instance, fill Search input ID or class (and optionally Search button ID or class).
  2. Tick Overlay search.
  3. Do not create a search results page, and do not tick Insert Site Search UI.
  4. Save and publish.

The header field then opens Airgentic search in an overlay. You do not need to change form action or name="query".

Do not combine overlay search with inline search on the same site: leave Overlay search unticked when you are using a /search page.

7. Choosing the display position

Service Hub

  • Inline: put the component where you want the chat to render; Airgentic reads the div’s coordinates.
  • CSS override: leave the component near the end of the page and use a style rule like #airgentic {position:fixed; bottom:2rem; right:2rem;} if you want a floating launcher.

Site Search

The search UI renders where you placed the component on the search page. Drag that component up or down in Edit Contents to control the layout.

8. Updating from v1.2

Existing installs that imported Airgentic Widget (v1.2) will not show the new search fields until you refresh the template.

  1. Open the existing Component Template asset (do not create a second Live template).
  2. Re-import the manifest from https://chat.airgentic.com/_integrations/matrix/airgentic_component.json, or upload the updated JSON file onto that same asset.
  3. Unlock, Commit, and keep the template Live.
  4. Edit the global nested instance: the name should now read Airgentic Widget (v1.3). Fill Search input ID or class if you want search.
  5. For inline search, add the search results page from section 5 and update the Design search forms.

Chat-only sites can leave the new fields blank. Hover widget and Service Hub behaviour is unchanged.

9. If you can’t see things…

Component / admin

  • No “Component Templates” folder – you’re on an older Matrix or lack admin rights; ask a System Administrator.
  • Template doesn’t appear in the dropdown – check the template is Live and that the current page sits under an Allowed Root Node.
  • “+” button missing on Edit Contents – you likely don’t have Write permission for the asset or locks aren’t acquired.
  • Design parse file locked – need global design permission or a devops user to commit.

Site Search

  • Empty container on the search page – inline search may not be enabled for the service; contact Airgentic support. Confirm Insert Site Search UI is ticked on that page.
  • Search page loads but no results – the input name is probably still a Matrix or Funnelback name. It must be query.
  • Autocomplete does not appear – Search input ID or class on the global instance does not match the live field. Re-inspect the input.
  • Form still goes to Funnelback or the old search URL – the form action in the Design has not been updated.
  • Overlay opens instead of the results page – Overlay search is ticked on the global instance. Untick it for inline search.
  • Header field has no id – add an id or class in the Design parse file, or use overlay search if you cannot edit the design.