Help

Overview
Overview What to Expect Pre-Session Checklist Your Onboarding Session
Platform Mental Model Admin & Operator Essentials Guardrails and Governance What to Use When Roles and Responsibilities Post-Session Next Steps Optional Deep-Dives Deep-Dive: Agents and Prompts Deep-Dive: Search and Knowledge Deep-Dive: Functions and Secure Services Deep-Dive: Handoff and Escalation Deep-Dive: Voice Mode Deep-Dive: Analytics and Improvement Facilitator Guide
Overview Account Overview User Management Usage
Admin Chat UI Design Curated Answers Search Settings
Overview Concepts AI Assistant Categories Scopes Index Fields Facets Result Cards Layout Website Integration Styling Testing Preview Funnelback Migration Troubleshooting
Conversational Intelligence Data Sync Upload Documents
Overview General Crawl Scope Image Extraction Field Mappings
Overview Creating an Agent Editing An Agent
Overview Editing a Prompt User Segmented Prompts
Overview Writing Your First Function AirScript Functions AirScript Reference
Overview Privacy Security
Analytics API Documents Ingestion API
Human Handoff
Overview Customer Service Insights Categories And Themes Search Insights
Overview Identity Provider Widget SharePoint Integration How It Works SharePoint Checklist Implementation Checklist
Admin Console Authorisation
Methods Script Tag Gtm Analytics AI Question Input Fields
Overview Optimiser Monitor
Contact Support

Custom External Scripts

Airgentic Help

External Script URLs

External Script URLs let an approved account load one or more hosted JavaScript files inside the Airgentic widget iframe.

Use this feature only when CSS is not enough and you need custom behaviour in the chat widget or inline search interface.

Availability

This is an advanced feature currently enabled only for selected accounts. If you do not see the setting in Service Configuration → User Interface, contact Airgentic support.

For enabled accounts, the setting appears as External Script URLs. Enter one HTTPS URL per line.

https://www.example.edu/path/to/airgentic-enhancements.js

Only absolute https:// URLs are accepted. Empty lines, duplicate URLs, relative URLs, and http:// URLs are ignored.

Where Scripts Run

Scripts are loaded inside the Airgentic widget iframe after the core widget has initialized.

They are not injected into the parent website page, and they are not loaded into the floating chat icon iframe.

This means a custom script can change the Airgentic widget experience, but it should not be used as a general website script loader.

What Scripts Can Access

Treat any configured script as trusted code.

A script loaded this way may be able to:

  • Read and modify the widget DOM.
  • Read chat or search content currently displayed inside the widget iframe.
  • Listen for widget events and browser events inside the iframe.
  • Make network requests from the browser.
  • Interact with postMessage handlers exposed to the iframe.

A script should not be able to directly modify the parent website DOM unless the browser and website origin allow it through normal web platform rules.

Security And Privacy Risks

Custom JavaScript is much more powerful than custom CSS.

Before adding a script URL, make sure you understand these risks:

  • Arbitrary code execution: The script runs in the user's browser inside the Airgentic iframe.
  • Conversation visibility: The script may see chat messages, search queries, result text, and other content shown in the widget.
  • Supply-chain risk: If the hosted script file is changed or compromised later, all pages loading the widget may run the changed code.
  • Data collection risk: Third-party analytics, pixels, or beacons inside the script may affect your privacy disclosures and consent requirements.
  • User trust risk: A script can alter the widget UI, including labels, buttons, and messages.

Only use scripts hosted and reviewed by your organisation or by a trusted vendor.

Support Boundaries

External scripts are an advanced customisation point.

Airgentic can confirm that the configured URL is passed to the widget and that the browser attempts to load it. Airgentic does not guarantee that custom JavaScript will continue to work across widget updates.

Custom scripts may break if:

  • Widget markup changes.
  • CSS classes or component structure changes.
  • Browser security rules change.
  • The hosted script becomes unavailable.
  • The script depends on timing that changes in a later release.

Test scripts in staging before using them in production.

  • Keep scripts small and narrowly scoped.
  • Version-control the source code.
  • Serve scripts over HTTPS from a controlled domain.
  • Avoid collecting conversation data unless your privacy policy and consent model allow it.
  • Avoid depending on internal Airgentic class names where possible.
  • Add defensive checks before querying or changing DOM elements.
  • Log failures to the browser console without blocking the widget.
  • Remove scripts that are no longer needed.

Load Order

External scripts are appended after the Airgentic widget receives its service customisations.

The core widget bundle is already running at that point. If your script needs to wait for a specific element, observe the DOM or retry briefly rather than assuming the element is present immediately.

Troubleshooting

If a script does not appear to work:

  1. Check that the URL begins with https://.
  2. Open the browser developer tools and check the Network tab for the script request.
  3. Check the Console tab for script errors.
  4. Confirm the script URL is reachable without authentication.
  5. Confirm the service was saved and the page has refreshed.
  6. Test with a minimal script such as console.log('Airgentic custom script loaded').

If the script loads but the widget behaves unexpectedly, remove the URL and retest before contacting support.

You have unsaved changes