This guide will help you learn how to integrate our agent into your web applications.

Embedding via whitelabel domain URL

We offer the ability to create a whitelabel domain for your copilot agent, allowing you to use a custom URL that matches your brand or requirements. For example, you can have your agent accessible at a URL like agent.your-domain.com.

Similarly, we can set up any custom URL for your organization with a simple change in your DNS configuration. If you would like to enable this feature, please reach out to us and our team will assist you with the setup process.

To embed your agent into your website, simply use an iframe pointing to your whitelabel domain. For example:

<iframe
  src="https://agents.rapidflare.ai"
  title="Rapidflare"
  loading="eager"
  allow="microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share"
  style="height: 100%; width: 100%; border: none; border-radius: 0rem; user-select: none; outline: none; box-shadow: none;">
</iframe>

You can embed this iframe anywhere in your website or application. Our system will automatically render the agent at the specified location. To enable this feature, please contact support@rapidflare.ai and we will work with your team and provision a whitelabel domain URL for your agent.

Embedding iframe for custom use cases such as AI generated answers in search results

We support using our iframe for use cases such as showing AI generated answers in your website's internal search results. If you have a search input field on your website where a user can type a search query and see search results, you can augment that user experience by leveraging our agent to render AI generated answers in addition to your search results. Consider the code snippet below -

  <div id="rapidflare-widget-iframe-container"></div>
  <script type="text/javascript">
    try {
      const searchQueryTerm = new URLSearchParams(window.location.search).get('s');
      const rapidflareIframeUrl = new URL("https://your-rapidflare-white-label-domain.com");
      const searchResultsConfig = JSON.stringify({
        showAiModeOverlay: true,
        aiModeOverlayButtonText: "Dive deeper in AI mode",
        aiModeButtonClickUrl: new URL("https://your-rapidflare-white-label-domain.com/askAI", window.location.origin).href
      });
      rapidflareIframeUrl.searchParams.set("aiModeConfig", searchResultsConfig);
      rapidflareIframeUrl.searchParams.set("prompt", searchQueryTerm);
      rapidflareIframeUrl.searchParams.set("autoSubmit", "true");
      const rapidflareWidgetIframe = document.createElement("iframe");
      rapidflareWidgetIframe.id = "rapidflare-widget-iframe";
      rapidflareWidgetIframe.src = rapidflareIframeUrl.href;
      rapidflareWidgetIframe.allow = "microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share";
      rapidflareWidgetIframe.style = "height: 270px; min-height: 270px; width: 100%; transition: all 0.3s ease; padding: 0px; margin: 30px 0px -15px 0px; border: none; border-radius: 0rem; user-select: none; outline: none; box-shadow: none;"
      document.querySelector('#rapidflare-widget-iframe-container').insertAdjacentElement('afterbegin', rapidflareWidgetIframe);
      window.addEventListener("message", ({ data }) => {
        if (!!data && data.type === "EMBED_WIDGET_SEARCH_RESULTS_LOADING_COMPLETE") {
          // AI search results streaming completed
          rapidflareWidgetIframe.style.height = "100%";
          rapidflareWidgetIframe.style.minHeight = "540px";
        }
      });
    } catch {
      // Handle error
    }
  </script>

aiModeConfig Query Parameters

Below is a table describing each parameter you can use inside the aiModeConfig object:

You can extend aiModeConfig with additional fields as needed for your use case. Pass this object as a JSON string in the query parameter.

Other Query Parameters

Below is a table describing additional query parameters you can use:

Iframe Permissions

The iframe uses the allow attribute to enable advanced features such as:

• Showing inline YouTube videos in references
• Allowing users to view the agent in fullscreen mode
• Enabling clipboard, microphone, and other capabilities for richer interactions

These permissions are required for the best user experience and to unlock all available features. The default recommended value for the allow attribute on the iframe HTML tag is microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share

Styling Recommendations

The height values of 270px and 540px in the example code are recommended defaults for typical use cases. You are free to adjust these values to best fit your page design and user experience needs.

What happens when user clicks on the "Dive deeper in AI mode" (customizable) CTA button

When a user clicks the "Dive deeper in AI mode" button (or your customized CTA text), our system will open the URL you configured in the aiModeButtonClickUrl parameter. This allows you to control exactly where users are taken for a deeper AI-powered experience where they can continue the conversation with our AI beyond just the initial search query.

To enable seamless context transfer, our system automatically appends two query parameters to the URL: userId and conversationId. These parameters uniquely identify the user and the current conversation, making it possible to continue the experience or reference previous interactions.

On the destination page, you should ensure that your whitelabel domain iframe is initialized with these parameters. Pass them back to our iframe so the agent can load the correct context and provide a personalized experience for the user. Here's a code snippet to demonstrate how this works -

<div id="rapidflare-widget-iframe-container"></div>
<script type="text/javascript">
  try {
    const userId = new URLSearchParams(window.location.search).get('userId');
    const conversationId = new URLSearchParams(window.location.search).get('conversationId');
    const rapidflareIframeUrl = new URL("https://your-rapidflare-white-label-domain.com");
    if (userId) {
      rapidflareIframeUrl.searchParams.set("userId", userId);
    }
    if (conversationId) {
      rapidflareIframeUrl.searchParams.set("conversationId", conversationId);
    }
    const rapidflareWidgetIframe = document.createElement("iframe");
    rapidflareWidgetIframe.id = "rapidflare-widget-iframe";
    rapidflareWidgetIframe.src = rapidflareIframeUrl.href;
    rapidflareWidgetIframe.allow = "microphone; midi; encrypted-media; autoplay; accelerometer; fullscreen; gyroscope; usb; magnetometer; clipboard-read; clipboard-write; picture-in-picture; web-share";
    rapidflareWidgetIframe.style = `height: 100%; min-height: 540px; width: 100%; transition: all 0.3s ease; padding: 0px; margin: 0px; border: none; border-radius: 0rem; user-select: none; outline: none; box-shadow: none;`
    document.querySelector('#rapidflare-widget-iframe-container').insertAdjacentElement('afterbegin', rapidflareWidgetIframe);
  } catch {
    // Handle error
  }
</script>

As you can see from the snippet, we are initializing a new iframe tag with src set to your whitelabel domain URL, and we passed on the userId and conversationId query parameters that our system had attached to the current URL before opening it in a new tab. Please feel free to adjust the style attribute on the iframe as per your need. Set height/width etc to whatever makes most sense in your web page.

Here's a short screen recording to demonstrate how the UI would look like on your website.

In this video example here are the steps that happened -

1. User lands on your search page and types a query, gets redirected to the search results page. On this page the rapidflare iframe is mounted.
2. The rapidflare iframe shows a snippet of the generated answer and a CTA to take user to a fullpage experience where they can choose to continue interacting with our AI
3. When the CTA is clicked a separate new page (configurable) is opened with query parameters for userId and conversationId that you need to pass back into a new iframe instance created on this page for our whitelabel domain.
4. Our system renders the conversation and user can continue interacting with our AI.