Rapidflare

Rapidflare Documentation

Deploying Rapidflare

Web

Overview

Rapidflare offers several ways to run the AI agent on your web properties. They fall into two groups:

For Slack or Discord, see Slack or Discord.

Which mode should I use?

Use this as a quick map—the table below has more detail.

  • Corner launcher and popup chat on any page → Floating Launcher
  • Agent inside a page you own (help center, /ask continuation page, etc.) → Full Page Widget (displayModeConfig.type: 'inline')
  • Search row on your site that sends people to a full chat page → Search Bar — set searchClickUrl to the page where you mount the Full Page Widget
  • Short AI summary + button into full chat → AI Overview — set buttonClickUrl to the page where chat should continue
  • Hosted URL or iframe; no script on your pages → Whitelabel domain
ModeImplementationIntegration detailContainer needed?Best for
Floating LauncherEmbed SDKdisplayModeConfig.type: 'floating'NoPersistent help button on every page
Full Page WidgetEmbed SDKdisplayModeConfig.type: 'inline'YesHelp centers, embedded panels, and follow-up pages after Search Bar & AI Overview
Search BarEmbed SDKdisplayModeConfig.type: 'search' + searchModeConfigYesSite search UI that navigates to a full conversation on another URL you host
AI OverviewEmbed SDKaiModeConfig + container (and usually prompt / autoSubmit)YesShort summary with a button into full chat
Whitelabel domainStandalone URL or iframeHosted agent only; not rapidflare.init(). Full-page recommended; iframe uses your URL as src, optionally with prompt / autoSubmit / userId / theme query params.N/ABranded agent without the Embed SDK

Good to know!

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

The Rapidflare Embed SDK is delivered as a single script from our CDN: https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js. It is lightweight, does not overwrite your page styles, and exposes window.rapidflare.init() for each mode below.

Ways to show the widget

The same loader and API support every option in this table—pick the one that fits each page or flow.

SurfaceTypical use
Floating LauncherPersistent corner control and overlay chat; no layout container on your page.
Full Page WidgetAgent in a region you own—including the page people open after Search or AI Overview.
Search BarSite search entry point; visitors are sent to a URL where you run the Full Page Widget (or equivalent).
AI OverviewSummary block with a button; buttonClickUrl should open a page where chat continues (usually Full Page Widget).

Quick start

  1. Add the loader <script> (for example in <head>).
  2. For Full Page Widget, Search Bar, and AI Overview, add a container <div> before you call init. Floating Launcher does not use container (it mounts to document.body).
  3. Call window.rapidflare.init({ ... }) at the end of <body> (or after the container exists). init() returns a ref with update(), destroy(), and config().

Floating Launcher

A launcher button anchored to a corner of the page. Clicking it opens the agent in a popup overlay. No container needed — the widget mounts to document.body.

Example 

<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',
            userId: 'user@example.com',
            theme: 'light',
            displayModeConfig: {
                type: 'floating',
                floatingModeConfig: {
                    position: 'bottom-right',
                    overlay: true,
                    // widgetTriggerSelector: '#my-trigger-button',
                    // Optional: uncomment and use above to create a custom selector
                }
            }
        });
    </script>
</body>

If you omit widgetTriggerSelector, the widget's default launcher button is shown in the corner you specify; otherwise your own element is used as the trigger.

floatingModeConfig

PropertyTypeDescription
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.
overlaybooleanIf true, shows a dimmed backdrop behind the popup when it's open and allows click-to-close. Default: false.
widgetTriggerSelectorstring | HTMLElement | SVGElementCSS 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.
More options—This table lists only floatingModeConfig. Shared init() parameters—apiKey, theme, userId, agent, onLoad, and the rest—apply to all modes and are documented in Shared configuration.

Full Page Widget

Shows the agent inside a container you provide—good for help centers, support pages, or any layout with a dedicated agent area. This is the default displayModeConfig and is usually the page people land on when Search Bar or AI Overview sends them to another URL to keep chatting.

Example 

<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',
            userId: 'user@example.com',
            theme: 'light',
            container: '#my-mount-node',
            displayModeConfig: { type: 'inline' }
        });
    </script>
</body>

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

Container layout

Container sizing and auto height

No additional nested config is needed for this mode — just displayModeConfig: { type: 'inline' }.

More options: That is the only mode-specific piece. Shared init() parameters—apiKey, theme, userId, prompt, onLoad, and the rest—apply to every mode and are documented in Shared configuration.

A search bar UI with optional LLM suggestions, starter prompt chips, and a send control. It requires a container on the page where the bar is embedded.

Why you need a second page

The Search Bar sends people to a URL you control when they run a search (or tap a starter prompt, when starterPromptAutoSubmit is on). That URL is searchClickUrl.

Set searchClickUrl to the page where chat should continue—almost always a page you host that loads the Embed SDK with displayModeConfig: { type: 'inline' } (Full Page Widget). That page reads the query parameters Rapidflare adds and calls init() so the user opens full-page chat with their search already in place—not a generic page with no widget.

Rapidflare adds query parameters to searchClickUrl when someone searches (see below). Without a second page that loads the inline widget, they have nowhere to go after search.

Search bar on your page 

<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://yoursite.com/support/ask',
                    searchClickOpenNewTab: false,
                    starterPromptAutoSubmit: false,
                    className: 'my-search-bar'
                }
            }
        });
    </script>
</body>

Next page (inline widget)

Same host and path as searchClickUrl—here https://yoursite.com/support/ask—with the Full Page Widget reading the query string. Use URLSearchParams so you only pass userId and conversationId into init() when those keys are in the URL (for example if the user landed with them from another journey or a direct link that includes those parameters).

<div id="agent-mount" style="display: flex; flex-direction: column;"></div>
<script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
<script>
    const searchParams = new URLSearchParams(window.location.search);
    window.rapidflare.init({
        apiKey: 'YOUR_API_KEY',
        theme: 'light',
        container: '#agent-mount',
        displayModeConfig: { type: 'inline' },
        prompt: searchParams.get('prompt') || undefined,
        autoSubmit: searchParams.get('autoSubmit') === 'true',
        userId: searchParams.has('userId') ? searchParams.get('userId') : undefined,
        conversationId: searchParams.has('conversationId') ? searchParams.get('conversationId') : undefined
    });
</script>

Query parameters on searchClickUrl

When someone sends a search (or taps a starter prompt with starterPromptAutoSubmit on), the widget updates your searchClickUrl: it drops any old prompt, autoSubmit, and conversationId, then adds the values below. This is how Rapidflare’s search embed works.

Query parameterValuePurpose
promptThe search text the user sent (URL-encoded)Pre-fills the agent; that page should pass this into init({ prompt, ... }).
autoSubmitAlways trueTells that page to submit the prompt on load; read it as URLSearchParams.get('autoSubmit') === 'true'.

No other query keys are added on navigation. Preserve any other query parameters already on your searchClickUrl base—they are kept when the new keys are applied.

searchModeConfig

PropertyTypeDescription
placeholderstringPlaceholder text for the search input. Optional.
minRowsnumberMinimum visible rows for the search input. Default: 1.
maxRowsnumberMaximum visible rows for the search input. Default: 1. Set maxRows higher than minRows for a multiline, auto-expanding textarea-style input.
autoFocusbooleanWhether to auto-focus the search input when mounted. Optional.
classNamestringExtra class name(s) on the search input row in the embed. Your page CSS must target it appropriately (e.g. shadow DOM / scoping). Optional.
searchClickUrlstringRequired for a complete flow. Must be the page URL where you mount the Full Page Widget (type: 'inline'). Receives prompt and autoSubmit as above.
searchClickOpenNewTabbooleanIf true, the send link opens in a new tab; if false, the same tab. Default: true.
aiSuggestionsDisabledbooleanIf true, disables typeahead ghost text and the LLM suggestions popover. Default: false (suggestions enabled).
starterPromptsDisabledbooleanIf true, hides starter prompt chips. Default: false (starter prompts shown when configured for the copilot).
starterPromptHeaderTextstringOptional heading shown above the starter prompts section.
starterPromptAutoSubmitbooleanIf true and searchClickUrl is set, tapping a starter prompt navigates like Send. If false, the chip only fills the input. Default: false.
More options—This table lists only searchModeConfig. Shared init() parameters—apiKey, theme, userId, agent, onLoad, and the rest—apply to all modes and are documented in Shared configuration.

AI Overview

AI Overview shows a search-style block on your site (summary plus overlay). It uses the same Embed SDK as the other modes. You pass a container, optional prompt / autoSubmit for the first topic, and aiModeConfig for overlay text, branding, and the button.

Why you need a second page

The overlay button (for example “Dive deeper”) opens buttonClickUrl from aiModeConfig. Point buttonClickUrl at the page where chat should continue—same idea as Search Bar: a URL you host that loads the widget as displayModeConfig: { type: 'inline' } (Full Page Widget). That’s how people go from the short summary to full chat. If buttonClickUrl is missing or isn’t a page with the inline widget, the button won’t help.

Rapidflare may add userId and conversationId to buttonClickUrl when someone clicks the button—pass them into init() on the next page if you want to keep the same chat (see Next page (inline widget) below).

Example

Use a flex column container so streaming height and expand/collapse behave correctly (see Layout and expand/collapse below).

<div
  id="rapidflare-ai-overview-container"
  style="display: flex; flex-direction: column; width: 100%;"
></div>
<script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
<script>
  const widget = window.rapidflare.init({
    apiKey: 'YOUR_API_KEY',
    userId: 'user@example.com',
    theme: 'light',
    container: '#rapidflare-ai-overview-container',
    prompt: 'Getting started with Acme products',
    autoSubmit: false,
    aiModeConfig: {
      showOverlay: true,
      overlayTitleText: 'AI Overview',
      overlayButtonText: 'Continue with Copilot',
      overlayButtonColor: '#222222',
      overlayButtonBackground: '#38BDF8',
      overlayTitleLogo: 'https://yourdomain.com/logo.png',
      buttonClickUrl: 'https://yoursite.com/support/ask',
      buttonClickOpenNewTab: false
    }
  });
</script>

Next page (inline widget)

Use the same URL as buttonClickUrl—for example https://yoursite.com/support/ask—for the Full Page Widget (type: 'inline'). When someone clicks the AI Overview button, Rapidflare adds userId and conversationId to that URL (see query parameters on buttonClickUrl); read them from the address bar and pass them into init() only when they’re there so full-page chat can continue the same thread.

<div id="agent-mount" style="display: flex; flex-direction: column;"></div>
<script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
<script>
  const searchParams = new URLSearchParams(window.location.search);
  window.rapidflare.init({
    apiKey: 'YOUR_API_KEY',
    theme: 'light',
    container: '#agent-mount',
    displayModeConfig: { type: 'inline' },
    userId: searchParams.has('userId') ? searchParams.get('userId') : undefined,
    conversationId: searchParams.has('conversationId') ? searchParams.get('conversationId') : undefined
  });
</script>

aiModeConfig

Object passed to rapidflare.init({ aiModeConfig: { ... } }) for AI Overview.

PropertyTypeDescription
showOverlaybooleanWhether to show the AI mode overlay.
overlayButtonColorstringButton text color (e.g. CSS color).
overlayButtonBackgroundstringButton background color.
overlayButtonTextstringButton label text.
overlayTitleTextstringOverlay title text.
overlayTitleLogostringURL of logo image for the overlay.
buttonClickUrlstringRequired for a complete flow. URL opened when the button is clicked—should be a page you host where the user continues in the Full Page Widget (type: 'inline').
buttonClickOpenNewTabbooleanWhether to open buttonClickUrl in a new tab (default true).
More options—This table lists only aiModeConfig. Shared init() parameters—apiKey, theme, userId, prompt, onLoad, and the rest—apply to all modes and are documented in Shared configuration.

Query parameters on buttonClickUrl

When someone clicks the button, the Embed SDK updates query parameters on your buttonClickUrl: it removes any existing prompt, autoSubmit, and aiModeConfig keys, then sets the values below. (These are query parameter names on the opened URL, not init() option names.) This matches how Rapidflare’s embed widget behaves.

Query parameterWhen setPurpose
userIdWhen the widget knows a user idSo the next page can use the same user ID (read it from the URL if you need it).
conversationIdWhen there is an active chatSo the next page can continue that chat when your full-page widget reads it from the URL.

Unlike query parameters on searchClickUrl, the AI Overview button does not add prompt or autoSubmit—the next page should use conversationId (and your init() options) for context.

Layout and expand/collapse

While the AI-generated answer streams, the block uses a default max height of 400px. After streaming completes, Expand removes that cap; Collapse restores 400px.

For expand/collapse and height transitions to work reliably, the same display: flex and flex-direction: column rules apply as for the Full Page Widget container:

<div id="rapidflare-ai-overview-container" style="display: flex; flex-direction: column; width: 100%;"></div>

Without flex on the container, expand/collapse can look broken even though the overlay renders.

Need help?

Our team can help you set up AI Overview on your site—reach out if you want help with your button URLs and hosting pages.

Shared configuration

These settings apply to every Embed SDK mode—Floating Launcher, Full Page Widget, Search Bar, and AI Overview—unless the Modes column below says otherwise. Earlier sections for each mode (for example floatingModeConfig, searchModeConfig, aiModeConfig) are extra options; you still pass the shared options in the same rapidflare.init() call. Whitelabel does not use this API—see Whitelabel Domain.

All surfaces use the same rapidflare.init() API. The table lists each parameter and which surfaces use it.

Configuration options

ParameterRequired?TypeDefaultModesDescription
apiKeyYesstring-AllConnects your agent to Rapidflare. Do not share outside your enterprise.
userIdOptionalstring-AllWe recommend the current user's email for usage tracking and feedback.
themeOptional'light' | 'dark'-AllMatches your site's color scheme. Invalid values are ignored.
containerOptionalHTMLElement or string-Full Page Widget, Search Bar, AI OverviewDOM node or CSS selector where the widget is mounted. Ignored for Floating Launcher (mounts to document.body). If omitted, the widget is inserted after the script tag.
agentOptionalstring'qa'AllWhich agent to show: qa (conversational) or product-selection.
promptOptionalstring-Floating Launcher, Full Page Widget, AI OverviewStarter text; with autoSubmit, can run on load. Search Bar uses the next page’s URL (see Search Bar) instead of this field when the user sends from the search row.
autoSubmitOptionalbooleanfalseFloating Launcher, Full Page Widget, AI OverviewIf true and prompt is set, submits on load. Search Bar uses query params on that next page.
conversationIdOptionalstring-AllID of an existing chat so you can resume it.
catalogIdOptionalstring-AllWhich catalog the widget should use.
displayModeConfigOptionalobject{ type: 'inline' }AllSets the display mode. See Floating Launcher, Full Page Widget, and Search Bar. Type cannot be changed via update().
onLoadOptionalfunction-AllRuns when the widget has finished loading and is ready to use.
aiModeConfigOptionalobject-AI Overview (primary)Overlay and button for AI Overview.

container vs widgetTriggerSelector

container is the mount target for the widget in Full Page Widget, Search Bar, and AI Overview. widgetTriggerSelector (inside floatingModeConfig) is only for the Floating Launcher: it attaches open/close to your own control and is not a layout container.

API

MethodDescription
rapidflare.init(config)Mounts the widget with the given config. Required: apiKey. Returns a ref object with id (string), update(partial), destroy(), and config().
rapidflare.getInstances()Returns an array of refs for all currently mounted widget instances. Each ref has id, update, destroy, and config.
ref.update(partial)Updates a subset of options (e.g. theme, prompt, userId) without remounting. displayModeConfig.type cannot be changed via update(); for the Floating Launcher only floatingModeConfig.position, floatingModeConfig.overlay, and floatingModeConfig.widgetTriggerSelector can be updated.
ref.destroy()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.

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.

Script URL

Load the Embed SDK from this URL (always the latest build—we do not publish or support pinning to older semver paths for this script the way the legacy widget did):

https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js

If you need a fixed artifact for compliance, host a copy you control or coordinate with Rapidflare—do not rely on undocumented URL patterns.

Whitelabel Domain

Whitelabel means people open your AI agent at a URL you control—often on your own domain (for example https://support.yourcompany.com or https://ai.yourcompany.com). We agree the exact address with you; you don’t have to use a specific subdomain like agent..

How you get your whitelabel URL: You can’t turn this on yourself in the dashboard yet. Email support@rapidflare.ai (or contact your Rapidflare account team). We help you pick the URL, set it up for your agent, and send the DNS records to add. When DNS is working, that URL is yours.

For whitelabel, most teams open the agent at its URL as a full page in the browser. No Rapidflare Embed SDK is involved.

Direct access

When setup and DNS are done, people can bookmark or open your whitelabel URL directly—for example https://support.example.com (example only; your real URL is the one Rapidflare gives you). That opens the full-page, branded agent.

Embedding as an iframe

You may put the same URL in an <iframe> on another page. Set src to your whitelabel URL. Size the iframe with CSS. Add an allow attribute if your agent needs things like the microphone or fullscreen (ask Rapidflare if you’re not sure what to list).

For a short summary with a button that opens full chat on your own pages, use the Embed SDK AI Overview mode. On a whitelabel iframe you can still pass prompt, autoSubmit, userId, and theme in the src URL to pre-fill text, auto-submit, set who the user is, and pick light or dark—same options as the widget’s shared settings—but that only affects the full agent inside the iframe, not the AI Overview layout.

<!-- Replace src with YOUR whitelabel URL from Rapidflare -->
<iframe
  src="https://your-whitelabel-host.example.com"
  title="Rapidflare"
  style="width: 100%; min-height: 500px; border: none; outline: none; box-shadow: none;"
  allow="microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share"
></iframe>

Optional: prompt, autoSubmit, userId, and theme on iframe src

You can append query parameters to the whitelabel URL used as the iframe src so the embedded agent opens with starter text, optional auto-submit, an optional signed-in user identity, and optional light or dark appearance.

Query parameterRequired?TypeDescription
promptOptionalstringInitial message or question for the agent. Must be URL-encoded when used in src.
autoSubmitOptionalbooleanIf true, the agent submits the prompt when the iframe loads. Use the string true or false in the query string.
userIdOptionalstringA unique ID for the user (we recommend email for usage tracking and feedback—same as Embed SDK userId). Must be URL-encoded when used in src.
themeOptionalstringlight or dark to match your page (same as the Embed SDK theme). Invalid values are ignored.

Static src: build the query string yourself (encode prompt and userId).

<!-- Replace src with YOUR whitelabel URL from Rapidflare -->
<iframe
  src="https://your-whitelabel-host.example.com?theme=light&userId=user%40example.com&prompt=How%20do%20I%20reset%20my%20password%3F&autoSubmit=true"
  title="Rapidflare"
  style="width: 100%; min-height: 500px; border: none; outline: none; box-shadow: none;"
  allow="microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share"
></iframe>

Building the URL in JavaScript: use URL + URLSearchParams so encoding is handled correctly, then set the iframe src (or render it in your app shell).

<iframe
  id="rf-whitelabel"
  title="Rapidflare"
  style="width: 100%; min-height: 500px; border: none; outline: none; box-shadow: none;"
  allow="microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share"
></iframe>
<script>
  // Replace `base` with YOUR whitelabel URL domain from Rapidflare
  const base = new URL('https://your-whitelabel-host.example.com');
  base.searchParams.set('theme', 'light');
  base.searchParams.set('userId', 'user@example.com');
  base.searchParams.set('prompt', 'How do I reset my password?');
  base.searchParams.set('autoSubmit', 'true');
  document.getElementById('rf-whitelabel').src = base.href;
</script>

Security

You use an API key to connect the widget to Rapidflare. We recommend restricting it to specific domains in your dashboard so only your sites can use it. 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

ScenarioWill API key work?
Request coming from spam / bot / known bad IP addressNo ❌
Request coming from non allow-listed domainNo ❌
Request not from a real browserNo ❌
Request initiated by a human and coming from allow-listed domainYes âś…

Legacy widget

Deprecated

The legacy widget is deprecated and will not receive future updates. Use the Embed SDK for new deployments.

Full reference for existing integrations—code snippets, launcher position, configuration, and script versioning—is on Legacy widget. It is not listed in the sidebar so the main Web guide stays focused on the Embed SDK.

Previous
Overview
Next
Slack