AI Overview: a short answer with a button into full chat

The AI Overview is a short answer written by the agent, shown in the middle of one of your pages, like the answer box at the top of a search results page. Under the answer is a button. When a visitor clicks it, another page of yours opens where they can keep chatting about the same thing.

yoursite.com/search/ask
A short answer, then the full chat

The card answers a topic you choose. Its button opens another page of yours, which continues the same conversation.

What your visitors will see

  • A card on your page with a short answer about a topic you picked. It appears by itself, nobody has to ask.
  • The answer writes itself out line by line.
  • A button under the answer. It says Dive deeper in AI mode unless you change the words.
  • When they click the button, a new page opens and the chat carries on from the answer they just read. That next page is a page of yours that shows the agent in full, using the Full Page widget.
  • The card grows up to 400 pixels tall while it writes. A longer answer gets an Expand button.

Before you start: you need two pages

Page with the answer cardPage with Full Page
This widget needs a second page on your site

The button under the answer takes visitors to a page where they can keep chatting. That page has to exist first, and it has to run our Full Page widget. Without it, the button has nowhere useful to go.

  1. Make a page on your site for the full chat. For example yourwebsite.com/ask. A new, mostly empty page is fine.
  2. Put the Full Page widget on it. Follow the Full Page guide, then add the few extra lines so the chat carries on from the answer.
  3. Copy that page's full address. The whole web address, starting with https://.
  4. Paste it into the builder below. Paste it into URL of the page the button opens, in step 2.

Add it to your site

There are four steps. Step 2 is a small tool: you click what you want, and it writes your snippet for you.

Step 1: Get your key

Open the dashboard, go to Hubs » Configure » Security, and create a publishable key. Then add your website address to that key, so it only works on your site. A publishable key is safe to put on your page. More in API keys.

Step 2: Set up and copy your snippet

Fill in the topic and the URL of the page the button opens. Switch the options you like. Your snippet below changes as you type.

The button opens a second page on your site, one that already runs the Full Page widget. How to set up that page
Options

The snippet adds an empty spot to your page (the line that starts with <div>) and the script puts the answer card there. This is how the script finds that spot: #name for an id (the default), .name for a class, or [data-name] for a data attribute. Change it here and both lines in the snippet change together. If your page already has the spot, point to it, and the snippet will not add another.

Required. Write it like a question or a title, for example: Getting started with our products.

Required. A page of yours that already shows the agent. Use the full URL, starting with https://.

Optional. The default is "Dive deeper in AI mode".

Optional. A color code such as #0284c7.

Optional. A color code such as #ffffff.

Optional. The full URL of an image, starting with https://. It appears in the picture.

Optional. Leave it empty to use the title set up in the dashboard.

Light unless you choose Dark. The chat window does not follow your visitor's device setting by itself. If your site switches between light and dark, ask your developer to pass the matching one.

What your visitors will see
yoursite.comAI OverviewDive deeper in AI modeyoursite.com/ask

This picture changes as you choose.

Your starter snippet

This is starter code. It already works. Add anything else we support whenever you need it. Every option we support is in the full table below, and each one can go inside the snippet next to the others.

Before you paste: replace these with your own
  • YOUR_PUBLISHABLE_API_KEYYour publishable key from step 1.
  • YOUR_TOPICThe topic the card answers, for example Getting started with our products.
  • YOUR_ASK_PAGE_URLThe full URL of your own page that shows the agent, starting with https://.
These must match. The empty box line has id="rapidflare-ai-overview" and the script looks for #rapidflare-ai-overview. In the script, # means "the id". So #rapidflare-ai-overview finds the line with id="rapidflare-ai-overview". If you change one, change the other, or the widget will not find its place on the page.
Optional lines

Lines that start with // are switched off and change nothing. To use one, delete the // and put in your own value, or fill the matching box above.

  • YOUR_TITLEThe title at the top of the chat. Without it, the name set up in the dashboard is used.
  • YOUR_BUTTON_WORDSThe words on the button. Without it, the button says Dive deeper in AI mode.
  • YOUR_LOGO_URLThe full URL of your logo image, starting with https://.
<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
    <div id="rapidflare-ai-overview" style="display: flex; flex-direction: column; width: 100%;"></div>
    <script>
        // Start only on pages that have the box above
        if (document.querySelector('#rapidflare-ai-overview')) {
            window.rapidflare.init({
                apiKey: 'YOUR_PUBLISHABLE_API_KEY',
                prompt: 'YOUR_TOPIC',
                display: {
                    type: 'ai-overview',
                    container: '#rapidflare-ai-overview',
                    ctaUrl: 'YOUR_ASK_PAGE_URL',
                    // ctaText: 'YOUR_BUTTON_WORDS',  (optional: delete the // at the start and put in your own value)
                    // titleText: 'YOUR_TITLE',  (optional: delete the // at the start and put in your own value)
                    // titleLogo: 'YOUR_LOGO_URL',  (optional: delete the // at the start and put in your own value)
                }
            });
        }
    </script>
</body>

Step 3: Paste it into your page

Paste the whole snippet into your page's HTML at the spot where you want the answer card. Then replace YOUR_PUBLISHABLE_API_KEY with your key from step 1. The card shows up where the empty box line is, the one that starts with <div>.

Add the script line only once

The first line of the snippet, the one that starts with <script src=, loads Rapidflare. Put it on the page one time, even if you add more than one widget later. It has to come before the code under it.

Built your site with a website builder such as WordPress or Wix? Our website builder guides show where the snippet goes. Not sure? Send the snippet to the person who edits your site.

Step 4: Check that it works

Open the page in a private window. The card should write its answer. Click the button to confirm it opens your next page.

Every option

Everything this widget accepts. A ✓ means the builder above already sets it. Anything else you can add by hand. Options in the first table go inside display: { ... }. Settings in the second table go next to apiKey.

Inside display: the look and behavior

OptionIn the builderTypeWhat it does
container✓HTMLElement or stringRequired. DOM node or CSS selector where the overview card is mounted.
titleText✓stringTitle label at the top of the overview card. Defaults to the hub-configured title when omitted.
titleLogo✓stringLogo URL rendered alongside the title. Defaults to the hub-configured logo when omitted.
ctaText✓stringCTA button label. Default: 'Dive deeper in AI mode'.
ctaBackground✓stringCSS color for the CTA button background. Defaults to the hub-configured value when omitted.
ctaColor✓stringCSS color for the CTA button text. Default: '#ffffff'.
ctaUrl✓stringRequired 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: 'full-page'). When omitted, the current page URL is used as the fallback target, which is usually not what you want for continuation.
ctaNewTabAdd by handbooleanWhether to open ctaUrl in a new tab. Default: true.
More optionsAdd by hand—This table lists only ai-overview display properties. Shared init() parameters—apiKey, theme, userId, prompt, onLoad, and the rest—apply to all modes and are documented in Shared configuration. prompt is required for AI Overview and it auto-submits on load. Without it init() fails and nothing renders.

Next to apiKey: settings for the whole widget

SettingRequired?TypeDefaultIn the builderWhat it does
apiKeyYesstring-Add by hand
idOptionalstring-Add by hand
userIdOptionalstring-Add by hand
themeOptional'light' | 'dark''light'✓
promptYesstring-✓
contextOptionalobject-Add by hand
conversationIdOptionalstring-Add by hand
onLoadOptionalfunction-Add by hand
onErrorOptionalfunction-Add by hand
doNotTrackOptionalbooleanfalseAdd by hand

If something does not work

What you seeWhy it usually happensWhat to do
No answer card appearsThe empty box line is not on this page, or the topic still says YOUR_TOPICPaste the whole snippet on the page and fill in the topic in step 2.
Nothing changed after you pasted the snippetThe page was not published or saved, or your site is still showing an older copy of itPublish or save the page. If your site has a caching or speed plugin, clear its cache. Then open the page in a private window.
The chat opens but shows an error instead of answersThe snippet still says YOUR_PUBLISHABLE_API_KEY, or your website address is not on the key's allowed listPut your own key in the snippet. Then check your website address is on that key in the dashboard. See API keys.
The button opens the page you are already onThe snippet still says YOUR_ASK_PAGE_URLPut the full URL of your next page in step 2, starting with https://.
The next page does not show the chatThat page does not have the agent on it yetAdd the Full Page widget to that page.
A change you made in the dashboard does not show yetBrowsers keep the agent's settings for up to an hourWait an hour, or open your site in a private window to see it now.

Need help?

Our team can help you set up the AI Overview on your site. Reach out if you want help with the URL the button opens and the page behind it.

For developers: what the button sends

When the button is clicked, the widget opens ctaUrl (a full http(s) URL; if it is missing or not a full URL, the current page is used) and changes its query string:

  • It adds userId (the conversation's user, when known) and conversationId (when a conversation exists).
  • It removes any prompt, autoSubmit and aiModeConfig already on the URL and keeps every other parameter.
  • It opens a new tab unless ctaNewTab is false.

The next page copies userId and conversationId into its own init() call, with the same API key, so the visitor resumes the same conversation. The exact parameters and the page's code are in Continue on a page you host.

If a visitor quotes part of the answer and asks about it, the same ctaUrl opens with the quote in prompt and autoSubmit=false. The next page should then put that text in the message box without sending it.

For developers: every setting

Everything below is for the person who edits your site's code. If you only want the widget on your page, the steps above are all you need. The full list of options is in the table above.

Identifying your users

Rapidflare cannot see your site's login state. The widget runs in its own frame and never reads your session, cookies, or SSO. Whether a conversation is attributed to a person is decided entirely by the userId you pass to init().

On your pageWhat to passHow the conversation is recorded
Visitor is signed inuserId: their id, email recommendedStored under that id, so you can filter and sort by user in Home » History
Visitor is signed outLeave userId outStored under an anonymous id we generate for that browser
<script>
    window.rapidflare.init({
        apiKey: 'YOUR_API_KEY',
        // Signed in: their id. Signed out: leave the key out entirely.
        ...(currentUser ? { userId: currentUser.email } : {}),
        prompt: 'Getting started with our products',
            display: { type: 'ai-overview', container: '#rapidflare-ai-overview' }
    });
</script>
  • Set it per visitor, never once for your whole site. A single hardcoded value (a support engineer's address, admin@yourcompany.com) files every visitor's conversation under that one person, and your history and analytics become unreadable. This is the most common mistake we see.
  • Omitting beats inventing. The anonymous id we generate is derived from the visitor's browser and your site's host, so the same browser usually comes back as the same id and keeps its earlier conversations. A placeholder such as guest@example.com or anonymous instead merges every signed-out visitor into one user.
  • userId is a claim, not authentication. We record it as declared by your page and never verify it. Don't treat it as an access-control boundary, and don't put anything secret in it.
  • Changing it starts a clean slate. The chat-history list lives in the visitor's browser, scoped per agent and userId, and a conversation can only be resumed by the id that started it. So after a sign-in or sign-out, the panel no longer lists or resumes what the previous identity said. Reloading the page with the new userId is the simplest approach; if you call update({ userId }) in place, do it when a new conversation starts.

Giving the agent page context

The agent answers better when it knows what page the visitor is asking from. Pass that in context:

<script>
    window.rapidflare.init({
        apiKey: 'YOUR_API_KEY',
        context: {
            referrerPage: { url: window.location.href, title: document.title },
            ambient: 'Viewing the Enterprise plan. Trial ends in 3 days.'
        },
        prompt: 'Getting started with our products',
            display: { type: 'ai-overview', container: '#rapidflare-ai-overview' }
    });
</script>

Your page tells us that page—we don't guess it. The browser's own document.referrer is empty whenever the link carried rel="noopener noreferrer", the page was opened through window.open, or a referrer policy stripped it on a cross-origin hop, and it never carries a title at all. Reading it would give you a value that quietly disappears on the journeys you most want to see, so you pass what your page already knows.

  • referrerPage is the page the question is coming from. With the widget embedded in your site that is the page it sits on, as above.
  • Both fields are optional. Send referrerPage, ambient, or both.
  • It travels with every message in that conversation, not just the first.
  • It is stored with the conversation and shown in Home » History, so treat it as visible: put in what helps the agent answer, not credentials, payment details, or anything you would not show the visitor.
  • Keep it short. A few lines is the intent. Everything you send is combined into a single block capped at 10,000 characters; past that the tail is cut and marked as truncated.

Changing it later. update({ context }) replaces the whole object rather than merging, so send every field you still want:

<script>
    const ref = window.rapidflare.init({ /* … */ });

    // Single-page app: the visitor navigated, so tell the agent where they are now.
    ref.update({ context: { referrerPage: { url: window.location.href, title: document.title } } });

    // Signed out, or moved somewhere the context no longer applies.
    ref.update({ context: undefined });
</script>

Replacing ambientContext

ambientContext, the earlier flat string, still works: pass it to init() and it becomes context.ambient, with a one-time console warning. Prefer context for new integrations, and if you send both, context.ambient wins. It is honored at init() only—update({ ambientContext }) is ignored, so use update({ context }).

API

MethodDescription
rapidflare.init(config)Mounts the widget with the given config. Required: apiKey and display. Returns a ref object with id (string), open(), close(), maximize(), minimize(), update(partial), resetConversation(), destroy(), and config().
rapidflare.getInstances()Returns an array of refs for all currently mounted widget instances. Each ref has id, open, close, maximize, minimize, update, resetConversation, destroy, and config.
ref.update(partial)Updates a subset of options (e.g. theme, prompt, userId, display properties other than type) without remounting. display.type cannot be changed via update()—call destroy() then init() with a new type instead.
ref.resetConversation()Clears the current conversation and starts a fresh one in place, without remounting the widget. Use it to back a "New chat" control in your own UI. The panel stays open and keeps its config; only the conversation is discarded.
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

  • Load the script only once per page. Put the <script src=...> line in once, before any init() call. If you add more than one widget, keep that single line and add one init() call for each widget.
  • 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.
  • The widget keeps your agent's settings (colors, logo, header text) in the visitor's browser for up to one hour after the visitor first opens the page. A change you make in the dashboard can take up to an hour to appear for returning visitors. Open the page in a private window to see the latest version.
  • The box you point display.container at must already be on the page when you call init(). If it is not found, the widget is added right after the script, or at the end of the page, instead of in your box. If one script serves many pages, call init() only when document.querySelector('...') finds the box.
  • resetConversation() is a no-op if called before the runtime has loaded: the widget has not rendered yet, so there is no conversation to clear.

Script URL

This is the one script every widget needs. Add it once, before your init() call:

<head>
    <script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>

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):

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.

Other ways to show the agent

Every widget type has its own page. Compare all of them or jump to another one.

A chat bubble in a corner of every page. Visitors click it and the agent opens as a popup.

Your own button or link opens the agent in a modal or a drawer.

A search box that opens the agent in a panel, or on a page you host.

The agent inside a page you own. Also where a search or an AI overview continues.

Your agent on your own domain, like ask.yourcompany.com. Nothing to install.