Search Bar: ask from a search box on your site
The Search Bar is a search box you place on a page. A visitor types a question, presses Enter, and gets an answer. By default the answer opens in a window on the same page, so nobody leaves your site.
The visitor types a question in your search box. A window slides in on the same page and answers it.
What your visitors will see
- A search box where you placed it, with a hint such as "Ask me anything".
- They type a question and press Enter, or click the arrow.
- A window opens on the same page and answers. The box empties, ready for the next question.
- They can close the window and carry on browsing.
You can also send visitors to a page of your own to read the answer. That choice needs a second page on your site, explained next.
Want the answer on your own page? You need two pages
To show the answer on your own page, the visitor needs somewhere to land. That page has to exist first, and it has to run our Full Page widget. The other looks open on the same page and need nothing extra.
- Make a page on your site for the full chat. For example
yourwebsite.com/ask. A new, mostly empty page is fine. - Put the Full Page widget on it. Follow the Full Page guide, then add the few extra lines for an answer page so it shows the visitor's question.
- Copy that page's full address. The whole web address, starting with
https://. - Paste it into the builder below. Pick Your own page and paste it into URL of your answer page, 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: Choose your look and copy your snippet
Click what should happen after a visitor presses Enter. Switch the options you like. Your snippet below changes as you choose. Every picture shows what your visitors will see.
The snippet adds an empty spot to your page (the line that starts with <div>) and the script puts the search bar 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.
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.
Side window on the right. This picture changes as you choose.
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.
- YOUR_PUBLISHABLE_API_KEYYour publishable key from step 1.
<head>
<script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
<div id="rapidflare-search" style="display: flex; flex-direction: column;"></div>
<script>
// Start only on pages that have the box above
if (document.querySelector('#rapidflare-search')) {
window.rapidflare.init({
apiKey: 'YOUR_PUBLISHABLE_API_KEY',
display: {
type: 'search',
container: '#rapidflare-search',
placeholder: 'Ask me anything...',
}
});
}
</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 search bar. Then replace YOUR_PUBLISHABLE_API_KEY with your key from step 1. The search bar 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, type a question in the search box and press Enter. You should see the answer in the look you picked.
If you picked your own page
The search bar sends the visitor's question to a page of yours, and that page shows the answer. The builder already wrote the search bar side. The page that receives the question needs the snippet below. It reads the question from the URL and gives it to the agent, because the agent does not read the URL by itself.
The snippet for your answer page
Paste it on your answer page, for example https://yourwebsite.com/ask, and replace YOUR_PUBLISHABLE_API_KEY with your key.
<head>
<script src="https://cloud.rapidflare.ai/storage/v1/object/public/rapidflare-embed-sdk/latest/agent.js"></script>
</head>
<body>
<div id="rapidflare-agent" style="display: flex; flex-direction: column;"></div>
<script>
// Start only on pages that have the box above
if (document.querySelector('#rapidflare-agent')) {
const params = new URLSearchParams(window.location.search);
window.rapidflare.init({
apiKey: 'YOUR_PUBLISHABLE_API_KEY',
prompt: (params.get('prompt') || '').slice(0, 1000) || undefined,
autoSubmit: params.get('autoSubmit') === 'true',
display: { type: 'full-page', container: '#rapidflare-agent' }
});
}
</script>
</body>
More on how the hand-off works is in Continue on a page you host.
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
| Option | In the builder | Type | What it does |
|---|---|---|---|
container | ✓ | HTMLElement or string | Required. DOM node or CSS selector where the search bar is mounted. |
placeholder | ✓ | string | Placeholder text for the search input. Optional. |
minRows | Add by hand | number | Minimum visible rows for the search input. Default: 1. |
maxRows | Add by hand | number | Maximum visible rows for the search input. Default: 1. Set maxRows higher than minRows for a multiline, auto-expanding textarea-style input. |
autoFocus | Add by hand | boolean | Whether to auto-focus the search input when mounted. Default: false. |
disableKeyboardTrigger | Add by hand | boolean | When true, disables the default keyboard shortcuts (cmd+k, cmd+f, ctrl+f) that open and focus the search input. Default: false. |
action | ✓ | object | What happens on search. { type: 'widget', widget: { type: 'floating-launcher' | 'inline-trigger', ... } } opens an SDK-owned on-page conversation panel (see On-page conversation); { type: 'external-url', url, newTab? } navigates to a page you host (see Navigate to a second page). Omit for the default on-page panel (inline-trigger right-modal). Do not pass a trigger inside action.widget. |
searchUrl | Add by hand | string | Compat only (equivalent to action.type: 'external-url'). Flat destination URL where you mount the Full Page Widget (type: 'full-page'). Receives prompt and autoSubmit as above. Use an absolute URL (e.g. https://yoursite.com/ask); if the URL is not an absolute http(s) address, Send and Enter reopen the current page with the parameters added instead of your page. Prefer action for new integrations. |
searchNewTab | Add by hand | boolean | Compat only (equivalent to action.newTab). If false, the send link opens in the same tab. Otherwise it opens in a new tab. Default: new tab. |
aiSuggestionsDisabled | Add by hand | boolean | If true, disables typeahead ghost text and the LLM suggestions popover. Default: false (suggestions enabled). |
starterPromptsDisabled | Add by hand | boolean | If true, hides starter prompt chips. Default: false (starter prompts shown when configured for the copilot). |
starterPromptHeaderText | Add by hand | string | Optional heading shown above the starter prompts section. |
starterPromptAutoSubmit | Add by hand | boolean | If true, tapping a starter prompt acts like Send (opens the on-page panel, or navigates for an external-url action). If false, the chip only fills the input. Default: false. |
Next to apiKey: settings for the whole widget
| Setting | Required? | Type | Default | In the builder | What it does |
|---|---|---|---|---|---|
apiKey | Yes | string | - | Add by hand | |
id | Optional | string | - | Add by hand | |
userId | Optional | string | - | Add by hand | |
theme | Optional | 'light' | 'dark' | 'light' | ✓ | |
context | Optional | object | - | Add by hand | |
conversationId | Optional | string | - | Add by hand | |
onLoad | Optional | function | - | Add by hand | |
onError | Optional | function | - | Add by hand | |
doNotTrack | Optional | boolean | false | Add by hand |
If something does not work
| What you see | Why it usually happens | What to do |
|---|---|---|
| No search box appears | The empty box line is not on this page, or its name does not match the script | Paste the whole snippet on the page, or check the box line and the script use the same name, as shown in step 2. |
| Nothing changed after you pasted the snippet | The page was not published or saved, or your site is still showing an older copy of it | Publish 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 answers | The snippet still says YOUR_PUBLISHABLE_API_KEY, or your website address is not on the key's allowed list | Put your own key in the snippet. Then check your website address is on that key in the dashboard. See API keys. |
| Pressing Enter opens the page you are already on | You picked "Your own page", but the snippet still says YOUR_ASK_PAGE_URL | Put the full URL of your answer page in step 2, starting with https://. |
| A change you made in the dashboard does not show yet | Browsers keep the agent's settings for up to an hour | Wait an hour, or open your site in a private window to see it now. |
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 page | What to pass | How the conversation is recorded |
|---|---|---|
| Visitor is signed in | userId: their id, email recommended | Stored under that id, so you can filter and sort by user in Home » History |
| Visitor is signed out | Leave userId out | Stored 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 } : {}),
display: { type: 'search', container: '#rapidflare-search' }
});
</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.comoranonymousinstead merges every signed-out visitor into one user. userIdis 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 newuserIdis the simplest approach; if you callupdate({ 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.'
},
display: { type: 'search', container: '#rapidflare-search' }
});
</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.
referrerPageis 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
| Method | Description |
|---|---|
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 anyinit()call. If you add more than one widget, keep that single line and add oneinit()call for each widget. - The loader script does not overwrite
window.rapidflareif it is already set. - There is no global
window.rapidflare.update()orwindow.rapidflare.destroy(); all per-instance control is through the ref returned byinit()(or refs fromgetInstances()). - Multiple instances: Each
init()call returns a separate instance. Callupdate(),destroy(), andconfig()on the returned reference, not onwindow.rapidflare. Usewindow.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.containerat must already be on the page when you callinit(). 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, callinit()only whendocument.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.
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.