Integrating our AI Agent with your internal web applications

This guide shows you how to add our AI Agent to your website.

The web widget loads our AI Agent as a widget that fits inside a container on your page. It won't affect your site’s styles. This is the recommended way to add the agent.

Good to know!

Get your API key from the dashboard under Hubs » Configure » Security. You need it to connect the widget to your account.

Quick start

Add the loader script to your page (e.g. in <head>).
Add a container (a <div>) where you want the widget to appear (for inline mode).
Call window.rapidflare.init({ ... }) with your API key and any options. Run this after the container exists—e.g. put the init script at the end of <body>. init() returns a widget ref; call update(), destroy(), and config() on that reference.

Example (inline mode):

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
    <div id="my-mount-node" style="display: flex; flex-direction: column;"></div>
    <script>
        const widget = window.rapidflare.init({
            apiKey: 'YOUR_API_KEY', // Required
            userId: 'user@example.com', // Optional
            theme: 'light', // Optional, either 'light' or 'dark'
            container: '#my-mount-node', // Optional, can be any valid CSS selector or HTMLElement
            displayModeConfig: { type: 'inline' } // Optional; inline is the default
        });
        // Later: widget.update({ theme: 'dark' });
        // Teardown: widget.destroy();
    </script>
</body>

If you don’t set container, the widget is inserted after the script tag.

Container sizing and auto height

Example (floating mode):

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
    <script>
        const widget = window.rapidflare.init({
            apiKey: 'YOUR_API_KEY', // Required
            userId: 'user@example.com', // Optional
            theme: 'light', // Optional, either 'light' or 'dark'
            displayModeConfig: {
                type: 'floating',
                floatingModeConfig: {
                    position: 'bottom-right', // Optional: 'top-left', 'top-right', 'bottom-left', 'bottom-right'
                    overlay: true, // Optional: dimmed backdrop behind the popup when open
                    widgetTriggerSelector: '#my-trigger-button' // Optional: CSS selector or HTMLElement; omit to use default launcher
                }
            }
        });
        // Later: widget.update({ theme: 'dark' });
        // Teardown: widget.destroy();
    </script>
</body>

If you don’t set widgetTriggerSelector inside floatingModeConfig, the widget's default launcher button is shown in the corner you specify; otherwise your own element is used as the trigger to open the widget.

Example (search mode):

When displayModeConfig.type is 'search', the widget shows the search-only UI (search input + LLM suggestions). No extra flag is required. Pass optional searchModeConfig to customize the input (e.g. placeholder, minRows, maxRows, autoFocus) and to set the search send button behavior: searchClickUrl (base URL when the user clicks send) and searchClickOpenNewTab (open in new tab or same tab). Use minRows and maxRows to control the input height and to achieve a multiline (textarea-style) search bar; both default to 1 if not passed. Provide a container for the search UI. The send-button link always omits conversation ID and uses autoSubmit: true, so the user gets a new full-page conversation—similar to the AI Overview "dive deeper" button.

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
    <div id="search-mount" style="display: flex; flex-direction: column;"></div>
    <script>
        const widget = window.rapidflare.init({
            apiKey: 'YOUR_API_KEY',
            container: '#search-mount',
            displayModeConfig: {
                type: 'search',
                searchModeConfig: {
                    placeholder: 'Ask me anything...',
                    autoFocus: true,
                    searchClickUrl: 'https://acme.rapidflare.ai',
                    searchClickOpenNewTab: true
                }
            }
        });
    </script>
</body>

Display modes

Inline (type: 'inline'): The widget renders inside a container you provide. Use for embedding the agent in your layout. No nested config required; e.g. displayModeConfig: { type: 'inline' }.
Floating (type: 'floating'): A launcher button opens the agent in a popup. Pass floatingModeConfig with position, overlay, and optional widgetTriggerSelector. No container needed; the widget mounts to document.body.
Search (type: 'search'): A search-style input with LLM suggestions. Set displayModeConfig.type to 'search' to enable search mode; searchModeConfig is optional and used only to customize the search input (e.g. placeholder, minRows, maxRows, autoFocus, className) and the search send button: searchClickUrl (base URL for the send link; expected for search mode) and searchClickOpenNewTab (open in new tab vs same tab). minRows and maxRows control the input height and can be used to achieve a multiline (textarea-style) input; both default to 1 if not passed. The send link always starts a new full-page conversation (no conversation ID, autoSubmit true). Provide a container for the search UI.

Script loading and behavior

The loader script does not overwrite window.rapidflare if it is already set.
There is no global window.rapidflare.update() or window.rapidflare.destroy(); all per-instance control is through the ref returned by init() (or refs from getInstances()).
Multiple instances: Each init() call returns a separate instance. Call update(), destroy(), and config() on the returned reference, not on window.rapidflare. Use window.rapidflare.getInstances() to get all currently mounted instances.
If you call init() before the runtime script has finished loading, your config is queued and applied automatically when the runtime is ready.

Method	Description
`rapidflare.init(config)`	Mounts the widget with the given config. Required: `apiKey`. Config type: `CopilotWidgetPropsV2`. Returns a ref object with `id` (string), `update(partial)`, `destroy()`, and `config()`. See Configuration options.
`rapidflare.getInstances()`	Returns an array of refs for all currently mounted widget instances. Each ref has `id`, `update`, `destroy`, and `config`.
`ref.update(partial)`	On the reference returned by `init()`: updates a subset of options (e.g. `theme`, `prompt`, `userId`) without remounting. `displayModeConfig.type` cannot be changed via `update()`; for floating widgets only `floatingModeConfig.position`, `floatingModeConfig.overlay`, and `floatingModeConfig.widgetTriggerSelector` can be updated.
`ref.destroy()`	On the reference returned by `init()`: unmounts that widget instance and cleans up. Other instances are unaffected. Call before calling `init()` again for the same container if you need a different config.
`ref.config()`	Returns the current config

You can pass these options to init() (and most to ref.update() for live changes).

Parameter	Required?	Type	Default	Description
`apiKey`	Yes	string	-	Connects your agent to Rapidflare. Do not share outside your enterprise.
`userId`	Optional	string	-	We recommend the current user’s email for usage tracking and feedback.
`theme`	Optional	`'light'` \| `'dark'`	-	Matches your site’s color scheme. Invalid values are ignored.
`container`	Optional	HTMLElement or string	-	For inline or search mode: DOM node or CSS selector where the widget is mounted. Ignored when `displayModeConfig.type` is `'floating'` (the widget mounts to `document.body`). If omitted or invalid for inline/search, the widget is inserted after the script tag.
`agent`	Optional	string	`'qa'`	Which agent to show: `qa` (conversational) or `product-selection`.
`prompt`	Optional	string	-	Starter prompt text pre-filled in the input (and optionally submitted if `autoSubmit` is true).
`autoSubmit`	Optional	boolean	`false`	If true and `prompt` is set, the starter prompt is submitted automatically when the widget loads.
`conversationId`	Optional	string	-	Conversation context to resume or scope the session.
`catalogId`	Optional	string	-	Catalog context for the widget.
`displayModeConfig`	Optional	object	`{ type: 'inline' }`	Display mode: inline, floating, or search. Type cannot be changed via `update()`. Pass `floatingModeConfig` when `type === 'floating'`, or `searchModeConfig` (optional) when `type === 'search'` to customize the search input. See table below.
`onLoad`	Optional	function	-	Callback invoked when the widget has finished loading and is ready to interact.
`aiModeConfig`	Optional	object	-	AI overview overlay and CTA. See table below.

displayModeConfig — a single object that describes how the widget is displayed. It has type (required): 'inline' | 'floating' | 'search'. Type cannot be changed via update(). When type === 'floating', pass floatingModeConfig; when type === 'search', you can pass searchModeConfig (optional) to customize the search input; for 'inline', no nested config is required. For floating widgets, only floatingModeConfig.position, floatingModeConfig.overlay, and floatingModeConfig.widgetTriggerSelector can be updated at runtime.

Property	Type	Description
`type`	`'inline'` \| `'floating'` \| `'search'`	Required. `'inline'`: Renders the widget inside your page (e.g. in a `<div>` you provide via `container`). Use when you want the agent embedded in your layout. `'floating'`: Renders a launcher button that opens the agent in a popup overlay; use `floatingModeConfig` for position, overlay, and optional custom trigger. `'search'`: Renders a search-style input with LLM suggestions; set `type` to `'search'` to enable search mode. Pass optional `searchModeConfig` to customize placeholder, minRows, maxRows, autoFocus, etc., and provide a `container`.
`floatingModeConfig`	object	When `type === 'floating'` only. See sub-table below.
`searchModeConfig`	object	When `type === 'search'` only. Optional. Use to customize the search input. See sub-table below.

floatingModeConfig (when displayModeConfig.type === 'floating'):

Property	Type	Description
`position`	`'top-left'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-right'`	Where the launcher button is anchored. Default: `'bottom-right'`. When omitted, the default launcher can be dragged and its position is persisted in localStorage.
`overlay`	boolean	If `true`, shows a dimmed backdrop behind the popup when it's open and allows click-to-close. Default: `false`.
`widgetTriggerSelector`	string \| HTMLElement \| SVGElement	CSS selector or DOM element for your own button that opens the widget. If provided, the default launcher is hidden and this element is the trigger. If omitted, the default trigger is shown.

searchModeConfig (when displayModeConfig.type === 'search'):

Optional. Use to customize the search input and the search send-button behavior. When the user clicks the send button in the search bar, the link uses searchClickUrl as the base; query params (e.g. prompt, autoSubmit) are added. The URL is always built without a conversation ID and with autoSubmit set to true, so it starts a new full-page conversation (no existing conversation is loaded). searchClickOpenNewTab controls whether that link opens in a new tab or the same tab—the same pattern as the AI Overview dive-deeper button. Use minRows and maxRows to control the visible height of the search input; both default to 1 if not passed. Setting maxRows greater than minRows (e.g. minRows: 1, maxRows: 5) gives a multiline, auto-expanding textarea-style input.

Property	Type	Description
`placeholder`	string	Placeholder text for the search input. Optional.
`minRows`	number	Minimum visible rows for the search input. Default: `1`. Use with `maxRows` to achieve a multiline (textarea-style) input.
`maxRows`	number	Maximum visible rows for the search input. Default: `1`. Set greater than `minRows` for an auto-expanding multiline input.
`autoFocus`	boolean	Whether to auto-focus the search input. Optional.
`className`	string	CSS class name(s) for the search input. Optional.
`searchClickUrl`	string	Base URL for the search send button. When the user clicks send, this URL is used; query params (e.g. `prompt`, `autoSubmit`) are added. Conversation ID is omitted and `autoSubmit` is true so the link starts a new full-page conversation. Search-mode equivalent of the AI overview buttonClickUrl / dive-deeper URL. Expected for search mode when you want the send action to navigate.
`searchClickOpenNewTab`	boolean	When `true`, the search send link opens in a new tab; when `false`, the same tab. Default: `true`.

container vs widgetTriggerSelector

container is the mount target for the whole widget in inline and search modes. widgetTriggerSelector (inside floatingModeConfig) is different — it is the optional element to which the floating bubble open/close trigger event is attached. It replaces the widget's default floating bubble-style trigger; it is not a container for the widget itself.

aiModeConfig (optional) — customize the overlay title, button text, and logo:

Property	Type	Description
`showOverlay`	boolean	Whether to show the AI mode overlay.
`overlayButtonColor`	string	Button text color (e.g. CSS color).
`overlayButtonBackground`	string	Button background color.
`overlayButtonText`	string	Button label text.
`overlayTitleText`	string	Overlay title text.
`overlayTitleLogo`	string	URL of logo image for the overlay.
`buttonClickUrl`	string	URL opened when the overlay button is clicked.
`buttonClickOpenNewTab`	boolean	Whether to open the button URL in a new tab (default `true`).

Script URL

Use this URL in your site:

Latest (recommended): {SUPABASE_STORAGE_BASE_URL}/rapidflare-embed-sdk/latest/agent.js — e.g. https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js

We recommend latest so you get updates automatically. To pin to a specific version, replace latest in the URL with a version (e.g. 1.0.x).

AI Overview

The AI Overview mode lets you render a search-results–style experience on your site—similar to Google search's AI Overview experience — where users see an AI-generated summary or answer before diving into a full conversation. The web widget supports this via an widget with a customizable title, logo, and call-to-action button (e.g. "Dive deeper in AI mode") that directs users to your agent in a fullpage experience. Use this when you want to highlight AI capabilities or guide users into a full AI flow. Configure it via the web widget init option aiModeConfig (see the aiModeConfig table above for overlay title, button text, colors, and click URL). Search mode has the same concept: its own searchClickUrl and searchClickOpenNewTab in searchModeConfig for the search send button, always starting a new full-page conversation (no conversation ID, autoSubmit true).

Need help?

Our team can help you set up AI Overview for your site. Just reach out to us and our team will assist you with the setup process.

Container sizing, auto height, and expand/collapse

The legacy option shows a floating button that opens the agent in a popup. For new integrations we recommend the web widget above. To use the legacy widget, add one of the code snippets below to the <head> of your page:

Option 1 (recommended)

<head>
    <script type="text/javascript">
        window.RFCopilotConfig = {
            apiKey: '<< insert your API key here >>',
            userId: '<< set a user ID (email) based on current user context >>',
            theme: '<< "light" | "dark" >>',
            position: '<< "bottom-right" | "bottom-left" | "top-right" | "top-left" | undefined >>',
            widgetTriggerSelector: '<< insert any valid CSS selector here (optional) >>',
            agent: '<< set agent to show (optional) "qa" | "product-selection" >>',
            onLoad: () => {
                // This function will be called when the agent widget is loaded and is ready to interact with
            },
            onOpen: () => {
                // This function will be called when the agent widget is opened
            },
            onClose: () => {
                // This function will be called when the agent widget is closed
            }
        };
    </script>
    <script type="text/javascript" src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/latest/script.js" defer></script>
</head>

Option 2

<head>
    <script id="rfCopilotWidgetScript" type="text/javascript" src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/latest/script.js" defer></script>
    <script>
        rfCopilotWidgetScript.addEventListener('load', function () {
            window.RFCopilot({
                apiKey: '<< insert your API key here >>',
                userId: '<< set a user ID (email) based on current user context >>',
                theme: '<< "light" | "dark" >>',
                position: '<< "bottom-right" | "bottom-left" | "top-right" | "top-left" | undefined >>',
                widgetTriggerSelector: '<< insert any valid CSS selector here (optional) >>',
                agent: '<< set agent to show (optional) "qa" | "product-selection" >>',
                onLoad: () => {
                    // This function will be called when the agent widget is loaded and is ready to interact with
                },
                onOpen: () => {
                // This function will be called when the agent widget is opened
                },
                onClose: () => {
                // This function will be called when the agent widget is closed
                }
            });
        });
    </script>
</head>

This will launch the AI Agent in the bottom right corner of your web application.

Choose where the launcher icon appears: bottom-right, bottom-left, top-right, or top-left. If you don’t set position, it defaults to bottom-right and users can drag it to any corner. The widget opens in the same corner as the icon. See the example below:

Options you can pass to the legacy widget:

Parameter	Required?	Default	Description
`apiKey`	Yes	-	This securely connects your AI Agent to Rapidflare. Do not share this key outside your enterprise!
`theme`	Optional	-	You can customize the appearance of the AI Agent by setting this parameter to either `light` or `dark` based on what your host website's color theme is.
`userId`	Optional	-	We recommend setting `userId` to the email of the current user logged into your web application. This will help track usage, and act on feedback from users
`position`	Optional	-	You can pass `position` to set the initial position of the AI Agent widget. The possible values are `bottom-right`, `bottom-left`, `top-right`, `top-left`. If you do not pass anything then the default position is `bottom-right` and user will be able to drag and drop the widget to any corner.
`widgetTriggerSelector`	Optional	-	CSS selector for the element that opens the floating bubble (e.g. your own button). If you do not pass it, or if no element matches your selector, our script renders its default launcher.
`agent`	Optional	-	You can pass `agent` as an optional value to configure which agent is rendered inside the widget. The possible values are `qa`, `product-selection`. If you do not pass anything then the default agent is `qa`
`onLoad`	Optional	-	This function will be called when the agent widget is loaded and is ready to interact with
`onOpen`	Optional	-	This function will be called when the agent widget is opened
`onClose`	Optional	-	This function will be called when the agent widget is closed

Good to know!

The API keys we provide to you control authentication to Rapidflare. Please do not distribute these keys outside your enterprise.

Use this script URL: https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/latest/script.js. We recommend latest so you get updates automatically. If you need to pin to a specific version, use one of the URLs below:

Method	Latest Stream / Version	URL
Pin to major, receive additve improvements and bug fixes	`3.x`	https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/3.x/script.js
Pin to minor, receive only bug fixes	`3.0.x`	https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/3.0.x/script.js
Pin to specific version	`3.0.4`	https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/3.0.4/script.js
Pin to latest version	`latest`	https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-copilot-widget/latest/script.js

The current latest version is 3.0.4.

Deprecated

The legacy web widget is deprecated and will not receive any future updates. We strongly recommend that you do not use it for new deployments. Use the web widget (recommended) instead.

Security

You use an API key to connect the widget to Rapidflare. You can add the key to your site; we recommend restricting it to specific domains in your dashboard so only your sites can use it. That helps prevent abuse. Domain allow-listing is optional but recommended.

We use Google reCAPTCHA Enterprise to help protect your key. Google's terms of service and privacy policy apply.

reCAPTCHA Sequence Diagram

Scenario	Will API key work?
Request coming from spam / bot / known bad IP address	No ❌
Request coming from non allow-listed domain	No ❌
Request not initiated from a genuine device / browser	No ❌
Request initiated by a human and coming from allow-listed domain	Yes ✅

Here's a video demo illustrating creating/updating/deleting your own API keys.

What does versioning control?

The script version only affects how the widget is loaded and shown on your page. The AI Agent inside the widget keeps getting updates from us regardless of which script version you use. Your branding stays the same.

Warning!

If you pin to a specific version, you may miss new features. We recommend using latest.

Rapidflare Documentation

Integrating our AI Agent with your internal web applications

Web Widget (recommended)

Quick start

Display modes

Script loading and behavior

API

Configuration options

Script URL

AI Overview

Legacy web widget

Option 1 (recommended)

Option 2

Widget Position

Widget Configuration

Widget Versioning

Security