Widget Integration

Add the DemoAgent chat widget to your website with a single script tag. The widget creates a floating chat interface that connects visitors to your AI demo agent.

HTML Script Tag

The simplest integration. Add this before the closing </body> tag:

<script
  src="https://cdn.iraa.ai/widget.js"
  data-api-key="pk_live_YOUR_KEY"
  async>
</script>

The widget auto-initializes using the data-api-key attribute.

Programmatic Initialization

For more control, load the script without data-api-key and call DemoAgent.init() manually:

<script src="https://cdn.iraa.ai/widget.js" async></script>
<script>
  window.addEventListener('DemoAgentReady', function() {
    DemoAgent.init({
      apiKey: 'pk_live_YOUR_KEY',
      theme: 'auto',
      position: 'bottom-right'
    });
  });
</script>

React (Vite or Create React App)

Do not inject the script via useEffect.

The widget reads ?iraa-demo=<token> from location.search at boot. React Router and other client-side routers strip query params during hydration, so by the time a useEffect fires the demo token is already gone and the agent never appears. Place the script in the static HTML entry file instead.

Vite + React — add to index.html:

<!-- index.html -->
<head>
  <script
    src="https://cdn.iraa.ai/widget.js"
    data-api-key="pk_live_YOUR_KEY"
    async></script>
  <script type="module" src="/src/main.tsx"></script>
</head>

Create React App — add to public/index.html:

<!-- public/index.html -->
<body>
  <div id="root"></div>
  <script
    src="https://cdn.iraa.ai/widget.js"
    data-api-key="pk_live_YOUR_KEY"
    async></script>
</body>

Next.js

import Script from 'next/script';

export default function Layout({ children }) {
  return (
    <>
      {children}
      <Script
        src="https://cdn.iraa.ai/widget.js"
        data-api-key="pk_live_YOUR_KEY"
        strategy="lazyOnload"
      />
    </>
  );
}

Vue (Vite or Vue CLI)

Same constraint as React: don't inject from onMounted — Vue Router will have stripped ?iraa-demo= by the time the hook fires. Add the script directly to the static HTML entry file.

Vite + Vue — add to index.html:

<!-- index.html -->
<head>
  <script
    src="https://cdn.iraa.ai/widget.js"
    data-api-key="pk_live_YOUR_KEY"
    async></script>
  <script type="module" src="/src/main.ts"></script>
</head>

Vue CLI — add to public/index.html before </body>.

Configuration Options

Options passed to DemoAgent.init(config):

Option	Type	Default	Description
`apiKey`	`string`	required	Your public API key (`pk_live_...` or `pk_test_...`)
`apiUrl`	`string`	`https://api.iraa.ai`	API base URL (override for self-hosted)
`wsUrl`	`string`	derived from apiUrl	WebSocket URL (auto-derived if not set)
`theme`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Widget color theme
`position`	`'bottom-right' \| 'bottom-left'`	`'bottom-right'`	Widget position on page

Events

DemoAgentReadyDispatched on window when the widget script is loaded and ready for init().

How It Works

The widget script loads and creates a floating action button (FAB) on the page
When the visitor clicks the FAB, a session is created via POST /api/v1/session
The agent sends an initial greeting with suggested conversation starters
A WebSocket connection is established for real-time messaging
The agent can navigate your product in a live iframe, clicking buttons, filling forms, and highlighting elements
Lead capture forms appear based on your Product Discovery Protocol (PDP) configuration triggers