Rapidflare

Control the web widget with JavaScript

Your page controls a Rapidflare widget through two things: the ref that rapidflare.init() returns, and the callbacks you pass to init(). The ref has methods such as open(), ask() and getState(). The callbacks tell your page when the widget loads, opens, closes, changes, fails, or when a visitor accepts the AI disclaimer. This page lists all of them. It applies to every Embed SDK widget: Floating Launcher, Inline Trigger, Search Bar, Full Page and AI Overview.

Get the ref

You get a widget's ref in three ways. All three give the same object.

<script>
    // 1. init() returns it.
    const ref = window.rapidflare.init({
        apiKey: 'YOUR_PUBLISHABLE_API_KEY',
        display: { type: 'floating-launcher', position: 'bottom-right' },
        // 2. onLoad receives it.
        onLoad: (loadedRef) => {
            console.log('Widget loaded:', loadedRef.id);
        }
    });

    // 3. getInstances() lists every widget on the page.
    const allRefs = window.rapidflare.getInstances();
</script>
  • rapidflare.init(config) mounts a widget and returns its ref. You can call the ref's methods at once, even before the script has finished loading.
  • rapidflare.getInstances() returns an array with the ref of every widget that is mounted now. Before the script has finished loading it returns an empty array.
  • There is no global update() or destroy(). You always call methods on a ref, so several widgets on one page never get in each other's way.

Methods on the ref

MethodReturnsWhat it does
idstringThe widget's id. It is the id you passed to init(), or one generated for you.
open()nothingOpens the panel of a Floating Launcher or an Inline Trigger. Called before the widget has loaded, it opens the panel as soon as it loads.
close()nothingCloses the panel of a Floating Launcher or an Inline Trigger.
maximize()nothingMakes the open panel of a Floating Launcher or an Inline Trigger wider.
minimize()nothingBrings the panel back to its normal size.
ask(question){ ok: true } or { ok: false, reason }Sends a question to the agent, and opens the panel first when it is closed. See Ask a question from your page.
getState()objectThe widget's current state, for example whether it is loaded or open. See Widget state.
update(partial)nothingChanges some settings without mounting the widget again, for example theme, userId, context or display options other than type. To change display.type, call destroy() and then init() again.
resetConversation()nothingClears the conversation and starts a new one in the same widget. Use it for a "New chat" button in your own page. The panel stays open. Before the widget has loaded there is no conversation, so it does nothing.
config()objectThe widget's current settings.
destroy()nothingRemoves this widget from the page. Other widgets are not changed.

Callbacks

Pass the callbacks you need to init(), next to apiKey. All of them are optional.

CallbackArgumentsWhen it runs
onLoadrefOnce, when the widget is on the page and you can control it. From here on, open(), ask() and the other methods work.
onReadynoneOnce, when the chat itself is built. See Loaded and ready.
onUpdatestate, changedEach time the widget's state changes: it opens or closes, gets bigger or smaller, a visitor drags the launcher to another corner, the AI overview expands or collapses, or consent changes. See Widget state.
onOpennoneEach time the panel of a Floating Launcher or an Inline Trigger opens.
onClosenoneEach time the panel of a Floating Launcher or an Inline Trigger closes.
onErrorerrorEach time the widget shows an error screen instead of the chat, for example after a wrong apiKey. See Errors.
onConsentnoneOnce, when the visitor accepts the AI disclaimer. See AI disclaimer consent.
<script>
    window.rapidflare.init({
        apiKey: 'YOUR_PUBLISHABLE_API_KEY',
        display: { type: 'floating-launcher', position: 'bottom-right' },
        onLoad: (ref) => { /* The widget is on the page. */ },
        onReady: () => { /* The chat is built. */ },
        onUpdate: (state, changed) => { /* state is the full state, changed lists what just changed. */ },
        onOpen: () => { /* The panel opened. */ },
        onClose: () => { /* The panel closed. */ },
        onError: (error) => { /* error.message is the text the visitor sees. */ },
        onConsent: () => { /* The visitor accepted the AI disclaimer. */ }
    });
</script>

Loaded and ready

A widget is loaded when it is on the page and you can control it. It is ready when its chat is built. onLoad runs when it is loaded, and onReady runs when it is ready.

WidgetLoadedReady
Full PageWhen it showsAt the same time as loaded
AI OverviewWhen it showsAt the same time as loaded
Floating LauncherWhen its button showsThe first time the panel opens
Inline TriggerWhen it is set up on your triggerThe first time the panel opens
Search BarWhen the search box showsWhen the chat it opens on your page is built. If it sends visitors to another page, at the same time as loaded.
  • Each callback runs once. A widget is never ready before it is loaded.
  • A panel nobody opens is never ready. A Floating Launcher or an Inline Trigger builds its chat only when it first opens. If no visitor opens it, onReady does not run.
  • You do not need to wait for ready before you ask. ask() needs only onLoad. It opens the panel and waits for the chat itself.

Ask a question from your page

ref.ask(question) sends a question to the agent, as if the visitor had typed it and pressed Enter. Use it for questions after the widget has loaded: your own ask bar, a suggested-question chip, or an "Ask about this product" button.

To open the widget with a question already asked, do not use ask(): pass prompt and autoSubmit: true to init().

<script>
    // Opens with this question already asked.
    window.rapidflare.init({
        apiKey: 'YOUR_PUBLISHABLE_API_KEY',
        display: { type: 'full-page', container: '#rf-agent' },
        prompt: 'How do I reset my device?',
        autoSubmit: true
    });
</script>
<button id="ask-reset">How do I reset my device?</button>
<script>
    const widget = window.rapidflare.init({
        apiKey: 'YOUR_PUBLISHABLE_API_KEY',
        display: { type: 'floating-launcher', position: 'bottom-right' }
    });

    // Asks later, when the visitor clicks your button.
    document.getElementById('ask-reset').addEventListener('click', () => {
        widget.ask('How do I reset my device?');
    });
</script>
  • It opens the panel for you. On a Floating Launcher or an Inline Trigger that is closed, ask() opens the panel, waits for the chat, and then sends the question.
  • On a Search Bar it uses the search's chat. The question goes to the chat that the search opens on your page. A Search Bar that sends visitors to another page has no chat on this page.
  • If your agent shows an AI disclaimer, a visitor who has not accepted it sees the consent screen first. The question is sent as soon as they accept. Your page does nothing extra.
  • If the agent is still answering, the new question waits and is sent when the answer is finished.

ask() returns a result at once:

ResultWhat it means
{ ok: true }The question is on its way to the chat. When the visitor must first accept the AI disclaimer, it is sent once they accept.
{ ok: false, reason: 'empty-question' }The question was empty or only spaces. Nothing was sent.
{ ok: false, reason: 'not-loaded' }ask() was called before onLoad. Nothing was sent. To start with a question, use prompt and autoSubmit in init().

The Inline Trigger page has a complete example with your own ask bar.

Widget state

ref.getState() returns the widget's current state. onUpdate(state, changed) gives you the same object each time it changes, plus the names of the fields that changed. The state never contains the conversation text.

FieldTypeWhat it means
isLoadedbooleantrue once the widget is loaded (when onLoad runs).
isReadybooleantrue once the chat is built (when onReady runs).
isOpenbooleantrue while the panel is open. For a Search Bar, the panel that the search opens.
isMaximizedbooleantrue while the panel is in its wider view.
positionstring or undefinedThe corner of a Floating Launcher, for example 'bottom-right'. It changes when a visitor drags the launcher. undefined for the other widgets.
aiOverview{ isExpanded: boolean }Whether an AI Overview card is expanded.
consent{ required: boolean, accepted: boolean } or undefinedWhether your agent asks visitors to accept an AI disclaimer, and whether this visitor has accepted it. undefined until the widget has loaded your agent's settings.

changed is an array of field names. It holds one or more of 'isLoaded', 'isReady', 'isOpen', 'isMaximized', 'position', 'aiOverview' and 'consent'.

<script>
    window.rapidflare.init({
        apiKey: 'YOUR_PUBLISHABLE_API_KEY',
        display: { type: 'floating-launcher', position: 'bottom-right' },
        onUpdate: (state, changed) => {
            if (changed.includes('isOpen')) {
                // Hide your own help button while the panel is open.
                document.getElementById('my-help-button').hidden = state.isOpen;
            }
        }
    });
</script>
  • Before the widget loads, getState() returns the starting values: not loaded, not ready, closed, normal size, and the position you set.
  • Use onUpdate to follow changes. Do not call getState() on a timer.

Your agent can ask each visitor to accept an AI disclaimer before the first question. The visitor then sees a short consent screen in the chat with a button to continue. After they accept, the chat works as usual, and they are not asked again on later visits in the same browser. A question your page sends with ask() while the consent screen is up is sent as soon as the visitor accepts.

Rapidflare can set up a consent screen for your agent. To add one or change its text, reach out to us at support@rapidflare.ai.

Your page does not need to do anything for consent. To know about it, for example for your own analytics, use:

  • getState().consent tells you at any time whether your agent asks for consent (required) and whether this visitor has accepted (accepted). A visitor who accepted on an earlier visit reads accepted: true.
  • onConsent() runs once, at the moment a visitor accepts. It does not run for a visitor who accepted on an earlier visit.

Errors

onError(error) runs when the widget shows an error screen instead of the chat, for example when the apiKey is wrong or a request fails. It can run more than once. Use it to hide your trigger, show your own fallback, or record the failure.

FieldTypeWhat it holds
messagestringThe same text the visitor sees on the error screen.
codestring, optionalA code for some errors. When the reCAPTCHA check cannot run it is rf-recaptcha-blocked-by-content-security-policy or rf-recaptcha-script-unavailable. See Security.
detailsobject, optionalMore facts for some errors. For a Content Security Policy block it holds blockedUrl and violatedDirective.