Introduction

This guide shows you how to add Airgentic to a Squiz Matrix website using a reusable Component Template. You don't need to add metadata fields or edit the page head.

You can set up three things:

  • Chat widget: a hover chat button on every page of your site.
  • Service Hub (optional): the full chat window embedded in selected pages.
  • Site Search (optional): a dedicated search results page, with autocomplete on your existing header search field.

The chat widget is the only required step. Add the Service Hub and Site Search if you want them.

1. Before you start

You will need:

  • Squiz Matrix DXP in the cloud, version 6 or late 5.5. Component Templates arrived in Matrix 6 and were back-ported to late 5.5. If you can see Component Templates in the asset tree, you're good.
  • Permission to:
    • create assets under Design & Layout → Component Templates
    • edit your site's Design or a global Paint Layout
    • create Standard Pages and edit page contents
  • Your Airgentic Account ID and Service ID.
  • For Site Search only: confirmation from Airgentic support that Site Search is enabled for your service.

2. Install the component template

You only do this once per Matrix system.

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

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

If your Matrix system can't reach external URLs, download the Airgentic component file instead, choose Upload manifest file and select airgentic_component.json.

  1. Unlock and Commit. The template appears with a green "Notice" status.
  2. Under Allowed Root Nodes, select your site root so editors can use the template.
  3. Change the template's status to Live.

The template is named Airgentic Widget (v1.4). You can rename, move or clone it like any other asset.

3. Add the chat widget to every page

The chat widget needs exactly one script on every page, so you'll create one instance of the component and nest it into your site's Design.

  1. Create a hidden Standard Page outside your navigation, called something like "Airgentic Global Widget".
  2. Open Edit Contents, click + (Add Component) and choose Code.
  3. Click the gear icon, set Template to Airgentic Widget (v1.4), and enter your Account ID and Service ID.
  4. Leave the checkboxes and other fields at their defaults for now. You'll come back to this instance to add Site Search (step 5) or optional settings (step 6).
  5. Save, then make the page Live.
  6. Open your site's Design or global Paint Layout. Just before </body>, add a Nest Content Design Area that points to the asset ID of the component you just created.
  7. Save and commit the Design.

The Nest Content Design Area looks like this in the parse file (replace 12345 with your asset ID):

<MySource_AREA id_name="airgentic_global" design_area="nest_content">
  <MySource_SET name="assetid" value="12345" />
</MySource_AREA>

Check it worked: open any page on your site and view the page source. You should see <script id="airgentic-script" …></script>, and the chat button should appear.

We call this instance the global instance in the rest of this guide.

4. Add the Service Hub to selected pages (optional)

The Service Hub embeds the full chat window directly in a page, for example on a "Contact us" or "Get help" page. Repeat these steps for each page that should host it.

  1. Open the page in Edit Contents.
  2. Click + (Add Component) and choose Code.
  3. Set Template to Airgentic Widget (v1.4), enter the same Account ID and Service ID, and tick Insert `<div id="airgentic"></div>`. Leave the other options empty.
  4. Save.
  5. Drag the component up or down in the components list to position the chat window. It appears exactly where the component sits on the page.
  6. Publish the page.

If you'd rather the Service Hub float in a corner of the screen, place the component near the end of the page and add a CSS rule to your site, for example:

#airgentic { position: fixed; bottom: 2rem; right: 2rem; }

5. Add Site Search (optional)

Site Search gives your website a dedicated search results page (for example /search) and adds autocomplete to your existing header search field. A visitor types in the header, presses Enter and lands on /search?query=… with results, filters and an AI summary.

There are four steps:

  1. Create the search results page.
  2. Connect your header search field.
  3. Point your site's search forms at the new page.
  4. Test it.

The component handles the first two. The third step is a change to your Design or Paint Layout, which may need a designer or developer.

For more detail, including how the Ask tab behaves, see Site Search Website Integration. If you're 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. You can also reuse your existing search page and replace its contents.
  2. Open Edit Contents, click + (Add Component) and choose Code.
  3. Set Template to Airgentic Widget (v1.4), enter the same Account ID and Service ID, and tick Insert Site Search UI. Leave the other options empty.
  4. Save.
  5. Drag the component to where the search results should appear on the page.
  6. Make the page Live.

5.2 Connect your header search field

  1. On your live site, right-click the header search field and choose Inspect.
  2. Copy the input's id. If it has no id, copy a class name instead, for example header-search or .header-search. If it has neither, add an id to the field in your Design parse file.
  3. Open the global instance you created in step 3.
  4. Paste the value into Search input ID or class. Leave Overlay search unticked.
  5. If your search button doesn't submit the form normally (for example, it runs a script), also fill in Search button ID or class.
  6. Save, and re-commit the Design if Matrix asks you to.

5.3 Point your search forms at the new page

Your site's existing search forms usually live in the Design parse file, a global Paint Layout or separate search box assets. Update every one of them (header, homepage, mobile menu) so that:

  • the form action is your new search page, for example /search
  • the form method is get
  • the search input's name is query

To check, search for engineering. The browser should open /search?query=engineering.

If you have an old Funnelback search page, either point the forms at the new page or redirect the old URL to /search.

5.4 Test it

  1. Open your homepage and type in the header search field. Autocomplete suggestions should appear.
  2. Press Enter. The browser should open /search?query=… and show results and filters.
  3. If the Ask tab is enabled, ask a question (for example, "How do I enrol?") and check that an answer starts.
  4. Copy that Ask URL and paste it into a new tab. The question should be filled in but not answered until the visitor confirms. This is intentional: it stops search engines and bots from triggering AI requests through links.

6. Optional settings

The component has extra settings for fine-tuning how Airgentic behaves. Every one is optional: leave a field blank (or on its default) and Airgentic uses your service's settings from the admin console.

Where to set them:

  • Across the whole site: set them on the global instance from step 3.
  • On one page only: add the component to that page (as in step 4), enter the same Account ID and Service ID, and fill in only the settings you want to change. A page's own component overrides the global instance for that page. You don't need to tick any checkboxes.

For example, to pin one page to a specialist agent, add the component to that page with only Agent ID filled in.

Chat icon

  • Chat icon: show or hide the floating chat icon. Hiding it is useful on pages that use the Service Hub instead.
  • Wait until the chat icon is not covered: holds back the icon and its callout until nothing covers them, for example until the visitor accepts a cookie banner. Leave this off if something covers the icon permanently, or the icon will never appear.
  • Chat icon callout: number of page visits that show it: how many visits in a browser show the callout beside the icon. Enter 0 to never show it. Blank means 1.
  • Chat icon callout: seconds it stays on screen: from 1 to 120. Blank means 6.
  • Open-chat button ID or class: the ID or class of your own button or link, such as a "Chat with us" button in your header. Clicking it opens the chat. A class can match several buttons. Enter the value without a # or ..
  • Open the chat widget in expanded mode: opens chat in the wider layout. This has no effect on screens narrower than 500px.

Chat behaviour

  • Agent ID: sends every chat question on the page to one specialist agent. Use the agent's ID from the Agents section of the admin console, not its display name. An unknown ID falls back to normal routing, and visitors can still ask for a person.
  • AI question target URL: the page that answers questions typed into AI question input fields, for example /ai-support. Blank opens the chat widget on the current page.
  • User ID cookie name: the name of a cookie on your site whose value is sent to Insights and your CRM as the visitor's user ID. It overrides the service setting. The cookie must be readable by JavaScript (not HttpOnly).

Search autocomplete

These settings apply to the header search field you connected in step 5.2.

  • Search input XPath: use this only when your search field has no usable ID or class.
  • Autocomplete: characters typed before suggestions appear: blank means 2.
  • Autocomplete: selecting a suggestion only fills the search field: by default, choosing a suggestion opens that page or runs the search. Tick this to just fill in the field instead.
  • Autocomplete theme: Light, Dark, Auto or Transparent. The default follows your Site Search theme.

Rollout and loading

  • Show Airgentic to this percentage of visitors: from 0 to 100, for a gradual launch. Each browser stays in the same group, so raising the number later adds visitors without reshuffling. 0 turns Airgentic off; blank shows it to everyone. Your search results and Service Hub pages always load. To test, add ?airgentic=1 (force on) or ?airgentic=0 (force off) to a page URL.
  • Start Airgentic as soon as the page HTML is parsed: by default, pages with only the chat icon wait until the whole page, images included, has loaded. Tick this to show the icon sooner. The page itself may finish loading slightly more slowly.

For full details of each option, see Website Integration Script Tag.

7. Updating from an earlier version

If you installed an earlier version of the component (v1.2 or v1.3), refresh the existing template rather than creating a new one.

  1. Open your existing Airgentic Component Template asset. Don't create a second Live template.
  2. Re-import the manifest from https://chat.airgentic.com/_integrations/matrix/airgentic_component.json, or upload the latest airgentic_component.json onto the same asset.
  3. Unlock, Commit, and keep the template Live.
  4. Open your global instance and check the template name now reads Airgentic Widget (v1.4).

Your existing chat widget and Service Hub pages keep working without any changes, and the new optional settings start out blank. To add Site Search, follow step 5. To use the optional settings, see step 6.

8. Troubleshooting

Installing the component

  • No Component Templates folder: you're on an older version of Matrix or don't have admin rights. Ask your System Administrator.
  • Template isn't in the dropdown: check the template is Live and the page sits under one of its Allowed Root Nodes.
  • No + button in Edit Contents: you don't have Write permission for the asset, or the locks haven't been acquired.
  • Can't commit the Design: you need global Design permission, or ask a user who has it.
  • New settings are missing from the component: the template is still on an older version. Re-import it as described in step 7.

Site Search

  • Search page is empty: check Insert Site Search UI is ticked on that page's component, then ask Airgentic support to confirm Site Search is enabled for your service.
  • Search page loads but shows no results: the search input's name is probably still the old Matrix or Funnelback name. It must be query.
  • No autocomplete suggestions: the Search input ID or class on the global instance doesn't match the live field. Inspect the field again and copy the exact value.
  • Searches still go to the old search page: the form action hasn't been updated. Check every search form, including the mobile menu.
  • Search opens in a popup instead of the results page: Overlay search is ticked on the global instance. Untick it.

Optional settings

  • A page setting has no effect: the page's component must sit in the page content, which renders before the global instance near </body>. Also check you entered the same Account ID and Service ID on both components.
  • Airgentic doesn't appear for you after setting a percentage: your browser may be outside the rollout group. Add ?airgentic=1 to the URL to force it on.