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()ordestroy(). You always call methods on a ref, so several widgets on one page never get in each other's way.
Methods on the ref
| Method | Returns | What it does |
|---|---|---|
id | string | The widget's id. It is the id you passed to init(), or one generated for you. |
open() | nothing | Opens 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() | nothing | Closes the panel of a Floating Launcher or an Inline Trigger. |
maximize() | nothing | Makes the open panel of a Floating Launcher or an Inline Trigger wider. |
minimize() | nothing | Brings 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() | object | The widget's current state, for example whether it is loaded or open. See Widget state. |
update(partial) | nothing | Changes 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() | nothing | Clears 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() | object | The widget's current settings. |
destroy() | nothing | Removes 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.
| Callback | Arguments | When it runs |
|---|---|---|
onLoad | ref | Once, when the widget is on the page and you can control it. From here on, open(), ask() and the other methods work. |
onReady | none | Once, when the chat itself is built. See Loaded and ready. |
onUpdate | state, changed | Each 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. |
onOpen | none | Each time the panel of a Floating Launcher or an Inline Trigger opens. |
onClose | none | Each time the panel of a Floating Launcher or an Inline Trigger closes. |
onError | error | Each time the widget shows an error screen instead of the chat, for example after a wrong apiKey. See Errors. |
onConsent | none | Once, 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.
| Widget | Loaded | Ready |
|---|---|---|
| Full Page | When it shows | At the same time as loaded |
| AI Overview | When it shows | At the same time as loaded |
| Floating Launcher | When its button shows | The first time the panel opens |
| Inline Trigger | When it is set up on your trigger | The first time the panel opens |
| Search Bar | When the search box shows | When 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,
onReadydoes not run. - You do not need to wait for ready before you ask.
ask()needs onlyonLoad. 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:
| Result | What 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.
| Field | Type | What it means |
|---|---|---|
isLoaded | boolean | true once the widget is loaded (when onLoad runs). |
isReady | boolean | true once the chat is built (when onReady runs). |
isOpen | boolean | true while the panel is open. For a Search Bar, the panel that the search opens. |
isMaximized | boolean | true while the panel is in its wider view. |
position | string or undefined | The 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 undefined | Whether 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 thepositionyou set. - Use
onUpdateto follow changes. Do not callgetState()on a timer.
AI disclaimer consent
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().consenttells 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 readsaccepted: 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.
| Field | Type | What it holds |
|---|---|---|
message | string | The same text the visitor sees on the error screen. |
code | string, optional | A 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. |
details | object, optional | More facts for some errors. For a Content Security Policy block it holds blockedUrl and violatedDirective. |