Brainfish Help Center - Configuring Web Agents

The Web Agent is a JavaScript library that can be integrated into your website to allows your users to get answers to their questions without leaving your website. The widget is fully customisable and can be configured to match the look and feel of your website.

Key Features

Seamless integration: The widget can be easily integrated into your existing frontend application or website.
Customisation options: The pluggable nature of the widget allows for easy customisation to align with your specific requirements.
User-friendly interface: The intuitive design and functionality of the widget ensure a smooth and effortless user experience.
Powerful search capabilities: The widget efficiently scans through the available resources and content within the help center, enabling users to quickly find relevant information.
Reduced time and effort: By providing quick access to relevant help content, the widget reduces the time and effort required for users to find solutions.
Widget Opened / Closed events (NEW): The widget now emits events the customers can listen to within their app, so they can for instance, call functions on their end to do whatever they need. A possible use case could be: tracking when their users open or close the widget.

Installation

To install the agent, it’s just a few lines of code to copy and paste within your product or website

To create a Brainfish agent:

Go to Agents > Create new agent
Choose Search or Sidebar agent style
Configure the Agent, you can preview and test it while doing this.
Save changes, and choose which coding framework you need before pressing Copy Config, which will give the engineers the specific code needed to put into the product.

Getting the Agent Installation Code

Once your agent is configured, you can retrieve the exact installation snippet for different frameworks directly from the agent configuration page:

From the desired agent's configuration page, click the </> Code button located in the top-right corner of the screen.
A side panel will appear, showing the installation code. By default, it will display the HTML version.
To get the code for a different framework, click the language dropdown menu (e.g., HTML) at the top of the panel.
Select your desired framework, such as React, from the list.
The displayed code will update to the selected format.
Click the Copy button to copy the code snippet to your clipboard.
You can also use the Send to Developer button to share the code directly with an engineer or teammate.

Allow Brainfish domains for CSP connection

If your application is using a Content Security Policy (CSP) directive, you will need to add these to your existing CSP:

For frame-src:, add https://app.brainfi.sh https://agent.brainfi.sh
For connect-src: add `wss://analytic.brainfi.sh

Example integration:

If your current CSP is:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; frame-src 'self' https://example.com; connect-src 'self' https://api.com;">

Update it to:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; frame-src 'self' https://example.com https://app.brainfi.sh https://agent.brainfi.sh; connect-src 'self' https://api.com wss://analytic.brainfi.sh;">

Here are the instructions for the 2 default types of implementations:

Implementation via `<script type="module">`

To integrate the Brainfish widget using a <script type="module">, follow these steps:

Add the Script to Your HTML: Insert the following <script> tag into the <head> section of your HTML file (preferred but not mandatory):

<head>
...
<script type="module">
  import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/web-widget@latest/dist/web.js";
  Brainfish.Widgets.init({ widgetKey: "bf_agent_YOUR_WIDGET_KEY" });
</script>
...
</head>

Implementation via NPM Package

To integrate the Brainfish widget using an NPM package, follow these steps:

Install the Package: Run the following command in your project directory:
```
npm install @brainfish-ai/web-widget
```
Initialize the Widget: Import and initialize the widget in your JavaScript code:

import Brainfish from '@brainfish-ai/web-widget';

Brainfish.Widgets.init({ 
  widgetKey: "bf_agent_SXHc8HshR9yV04ijBKR4Jt5o2zThaKN2VWGwq1" 
});

Final Step

Once you’ve configured your widget and implemented the appropriate code, press "Copy Config" at the top of the page. This will generate the exact code needed to integrate the Brainfish widget into your product.

Can I create multiple agents?

Yes you can - Navigate to Agents section to create a new agetn, and configure it, before copying it into your app/website.

Tracking for Guidance & Nudges

How to Identify a User with Brainfish Analytics

Use the identify method to uniquely identify a user and attach relevant properties to their profile. This allows you to track user-specific behavior and better understand their interactions.

Here’s how to identify a user:

Brainfish.Widgets.identify({
  userId: user.id,       // Required: A unique identifier for the user (e.g., their database ID).
  email: user.email,     // Optional: The user's email address for additional context.
  properties: {          // Optional: Custom attributes to enrich the user profile.
    teamId: user.teamId,           // The team or organization the user belongs to.
    subscription: user.subscription, // The user's subscription level or plan.
    isAdmin: user.isAdmin,         // A boolean indicating if the user is an admin.
  },
});

Example: If you want to identify a user named "John Doe" with an ID of 12345, an email of john.doe@example.com, and some additional properties, your code might look like this:

Brainfish.Widgets.identify({
  userId: "12345",
  email: "john.doe@example.com",
  properties: {
    teamId: "team_67890",
    subscription: "premium",
    isAdmin: true,
  },
});

Why Use These Methods?

Identify: Helps you understand who your users are by attaching user-specific information to their profiles.

Events

The widget now emits events the you can listen to within your app, so you can for instance, call functions on your end to do whatever you need. A possible use case could be: tracking when your users open or close the widget.

onBrainfishHelpWidgetClosed

This event is emitted after the widget close animation is finished

Your can listen to this event and handle it within your app with the following code.

<script>
  // Step 1: Create an AbortController instance if you haven't already
  const controller = new AbortController();
  const signal = controller.signal;

  const yourClosedHandlerFunction = () => {
    console.log('do something after widget is closed');
  }
  window.addEventListener('onBrainfishHelpWidgetClosed', yourClosedHandlerFunction, { signal });
</script>

onBrainfishHelpWidgetOpened

This event is emitted after the widget open animation is finished

You can listen to this event and handle it within your app with the following code.

<script>
  // Step 1: Create an AbortController instance if you haven't already
  const controller = new AbortController();
  const signal = controller.signal;

  const yourOpenedHandlerFunction = () => {
    console.log('do something after widget is opened');
  }
  window.addEventListener('onBrainfishHelpWidgetOpened', yourOpenedHandlerFunction, { signal });
</script>

When your page no longer needs the widget, you should remove these event listeners. You can do it like so.

<script>
  controller.abort(); // aborts all handlers registered against the controller.
</script>

Below is a matrix of the events you can subscribe to

	Description	Popup	Legacy
search	When the user submits a search	Coming soon	✅
onBrainfishWidgetOpen	When widget opens	✅
onBrainfishWidgetClose	When widget closes	✅
onBrainfishReady	When widget is loaded and ready	✅
BrainfishActionClick	When user clicks on an action button	Coming soon	✅
AskNewQuestionButtonClick	When user clicks on Ask new question button	Coming soon	✅

Customisations

Within Settings, you are able to configure custom Action buttons to display in either the Body, Footer, or after an answer appears as Next Best Actions.

These Action Buttons can be a link, a phone number to call, email, or a callback. However, callbacks are recommended to be configured as an override when implementing the widget, so that your developers can have full access to what they intend to do with the callback.

eg:

<script type="module">
    import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/widgets-initiator@latest/dist/web.js"
    Brainfish.Widgets.init({
      widgetKey: "bf_search_widget_WIDGET_KEY", overrides: {
        nextBestActions: [
          {
            "type": "callback",
            "label": "Chat support",
            "value": ({ query, answer }) => {
              // Close the widget before opening the chat widget
              Brainfish.HelpWidget.close('brainfish-trigger-button');
              // Open chat widget and prepopulate with question asked
              window.openChat({ query })
            }
          }
        ]
      }
    });
  </script>

Pre-loading a question into a Brainfish agent widget

You can pre-ask a question by setting up a trigger event in your application. Below is an example where one is setup to act as a Help button on a unique feature

 <button class="brainfish-trigger-button" 
          onClick="Brainfish.Widgets.onContextHelp('How do I setup the Notion integration?')" >
    Notion Help
 </button>

Here’s a video overview of it working in practice:

Pre-loading a question into a Brainfish widget 2246x1214

Setting Up a DNT Tag for Brainfish AI Agent

By default, Brainfish agents do not use cookies to track users, we use a cookie-less approach to ensure GDPR compliance.

However, if you’d like to setup a specific Do Not Track (DNT) request using a cookie handler like CookieBot or CookiePro that will disable session recordings, and ambient knowledge for certain users that have not opted in to cookies, here is how to do so:

Setup

To disable tracking (stops recording, screenshots, etc.) when cookies are not accepted, use the following code within your cookie handler:

window.BrainfishAnalytics('disableTracking');

// To re-enable tracking (requires a page reload for full effect)
window.BrainfishAnalytics('enableTracking');

// To check if tracking is currently disabled
const isDisabled = window.BrainfishAnalytics('isTrackingDisabled');
console.log('Is tracking disabled?', isDisabled); // true or false

Real World Example of DNT handler set up to disable session recording

// When user clicks "Accept All" on cookie banner
document.getElementById('accept-all').addEventListener('click', () => {
  window.BrainfishAnalytics('enableTracking');
  // Store consent preference
  localStorage.setItem('cookie-consent', 'all');
  // Reload page to restart recording
  window.location.reload();
});

// When user clicks "Reject Optional" on cookie banner
document.getElementById('reject-optional').addEventListener('click', () => {
  window.BrainfishAnalytics('disableTracking');
  // Store consent preference
  localStorage.setItem('cookie-consent', 'essential-only');
});

// On page load, check existing consent
if (localStorage.getItem('cookie-consent') === 'essential-only') {
  window.BrainfishAnalytics('disableTracking');
}

Key Features

Seamless integration: The widget can be easily integrated into your existing frontend application or website.
Customisation options: The pluggable nature of the widget allows for easy customisation to align with your specific requirements.
User-friendly interface: The intuitive design and functionality of the widget ensure a smooth and effortless user experience.
Powerful search capabilities: The widget efficiently scans through the available resources and content within the help center, enabling users to quickly find relevant information.
Reduced time and effort: By providing quick access to relevant help content, the widget reduces the time and effort required for users to find solutions.
Widget Opened / Closed events (NEW): The widget now emits events the customers can listen to within their app, so they can for instance, call functions on their end to do whatever they need. A possible use case could be: tracking when their users open or close the widget.

Installation

To install the agent, it’s just a few lines of code to copy and paste within your product or website

To create a Brainfish agent:

Go to Agents > Create new agent
Choose Search or Sidebar agent style
Configure the Agent, you can preview and test it while doing this.
Save changes, and choose which coding framework you need before pressing Copy Config, which will give the engineers the specific code needed to put into the product.

Getting the Agent Installation Code

Once your agent is configured, you can retrieve the exact installation snippet for different frameworks directly from the agent configuration page:

From the desired agent's configuration page, click the </> Code button located in the top-right corner of the screen.
A side panel will appear, showing the installation code. By default, it will display the HTML version.
To get the code for a different framework, click the language dropdown menu (e.g., HTML) at the top of the panel.
Select your desired framework, such as React, from the list.
The displayed code will update to the selected format.
Click the Copy button to copy the code snippet to your clipboard.
You can also use the Send to Developer button to share the code directly with an engineer or teammate.

Allow Brainfish domains for CSP connection

If your application is using a Content Security Policy (CSP) directive, you will need to add these to your existing CSP:

For frame-src:, add https://app.brainfi.sh https://agent.brainfi.sh
For connect-src: add `wss://analytic.brainfi.sh

Example integration:

If your current CSP is:

<meta http-equiv="Content-Security-Policy" content="default-src 'self'; frame-src 'self' https://example.com; connect-src 'self' https://api.com;">

Update it to:

Here are the instructions for the 2 default types of implementations:

Implementation via `<script type="module">`

To integrate the Brainfish widget using a <script type="module">, follow these steps:

Add the Script to Your HTML: Insert the following <script> tag into the <head> section of your HTML file (preferred but not mandatory):

<head>
...
<script type="module">
  import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/web-widget@latest/dist/web.js";
  Brainfish.Widgets.init({ widgetKey: "bf_agent_YOUR_WIDGET_KEY" });
</script>
...
</head>

Implementation via NPM Package

To integrate the Brainfish widget using an NPM package, follow these steps:

Install the Package: Run the following command in your project directory:
```
npm install @brainfish-ai/web-widget
```
Initialize the Widget: Import and initialize the widget in your JavaScript code:

import Brainfish from '@brainfish-ai/web-widget';

Brainfish.Widgets.init({ 
  widgetKey: "bf_agent_SXHc8HshR9yV04ijBKR4Jt5o2zThaKN2VWGwq1" 
});

Final Step

Can I create multiple agents?

Yes you can - Navigate to Agents section to create a new agetn, and configure it, before copying it into your app/website.

Tracking for Guidance & Nudges

How to Identify a User with Brainfish Analytics

Use the identify method to uniquely identify a user and attach relevant properties to their profile. This allows you to track user-specific behavior and better understand their interactions.

Here’s how to identify a user:

Brainfish.Widgets.identify({
  userId: user.id,       // Required: A unique identifier for the user (e.g., their database ID).
  email: user.email,     // Optional: The user's email address for additional context.
  properties: {          // Optional: Custom attributes to enrich the user profile.
    teamId: user.teamId,           // The team or organization the user belongs to.
    subscription: user.subscription, // The user's subscription level or plan.
    isAdmin: user.isAdmin,         // A boolean indicating if the user is an admin.
  },
});

Example: If you want to identify a user named "John Doe" with an ID of 12345, an email of john.doe@example.com, and some additional properties, your code might look like this:

Brainfish.Widgets.identify({
  userId: "12345",
  email: "john.doe@example.com",
  properties: {
    teamId: "team_67890",
    subscription: "premium",
    isAdmin: true,
  },
});

Why Use These Methods?

Identify: Helps you understand who your users are by attaching user-specific information to their profiles.

Events

onBrainfishHelpWidgetClosed

This event is emitted after the widget close animation is finished

Your can listen to this event and handle it within your app with the following code.

<script>
  // Step 1: Create an AbortController instance if you haven't already
  const controller = new AbortController();
  const signal = controller.signal;

  const yourClosedHandlerFunction = () => {
    console.log('do something after widget is closed');
  }
  window.addEventListener('onBrainfishHelpWidgetClosed', yourClosedHandlerFunction, { signal });
</script>

onBrainfishHelpWidgetOpened

This event is emitted after the widget open animation is finished

You can listen to this event and handle it within your app with the following code.

<script>
  // Step 1: Create an AbortController instance if you haven't already
  const controller = new AbortController();
  const signal = controller.signal;

  const yourOpenedHandlerFunction = () => {
    console.log('do something after widget is opened');
  }
  window.addEventListener('onBrainfishHelpWidgetOpened', yourOpenedHandlerFunction, { signal });
</script>

When your page no longer needs the widget, you should remove these event listeners. You can do it like so.

<script>
  controller.abort(); // aborts all handlers registered against the controller.
</script>

Below is a matrix of the events you can subscribe to

	Description	Popup	Legacy
search	When the user submits a search	Coming soon	✅
onBrainfishWidgetOpen	When widget opens	✅
onBrainfishWidgetClose	When widget closes	✅
onBrainfishReady	When widget is loaded and ready	✅
BrainfishActionClick	When user clicks on an action button	Coming soon	✅
AskNewQuestionButtonClick	When user clicks on Ask new question button	Coming soon	✅

Customisations

Within Settings, you are able to configure custom Action buttons to display in either the Body, Footer, or after an answer appears as Next Best Actions.

eg:

<script type="module">
    import Brainfish from "https://cdn.jsdelivr.net/npm/@brainfish-ai/widgets-initiator@latest/dist/web.js"
    Brainfish.Widgets.init({
      widgetKey: "bf_search_widget_WIDGET_KEY", overrides: {
        nextBestActions: [
          {
            "type": "callback",
            "label": "Chat support",
            "value": ({ query, answer }) => {
              // Close the widget before opening the chat widget
              Brainfish.HelpWidget.close('brainfish-trigger-button');
              // Open chat widget and prepopulate with question asked
              window.openChat({ query })
            }
          }
        ]
      }
    });
  </script>

Pre-loading a question into a Brainfish agent widget

You can pre-ask a question by setting up a trigger event in your application. Below is an example where one is setup to act as a Help button on a unique feature

 <button class="brainfish-trigger-button" 
          onClick="Brainfish.Widgets.onContextHelp('How do I setup the Notion integration?')" >
    Notion Help
 </button>

Here’s a video overview of it working in practice:

Pre-loading a question into a Brainfish widget 2246x1214

Setting Up a DNT Tag for Brainfish AI Agent

By default, Brainfish agents do not use cookies to track users, we use a cookie-less approach to ensure GDPR compliance.

Setup

To disable tracking (stops recording, screenshots, etc.) when cookies are not accepted, use the following code within your cookie handler:

window.BrainfishAnalytics('disableTracking');

// To re-enable tracking (requires a page reload for full effect)
window.BrainfishAnalytics('enableTracking');

// To check if tracking is currently disabled
const isDisabled = window.BrainfishAnalytics('isTrackingDisabled');
console.log('Is tracking disabled?', isDisabled); // true or false

Real World Example of DNT handler set up to disable session recording

// When user clicks "Accept All" on cookie banner
document.getElementById('accept-all').addEventListener('click', () => {
  window.BrainfishAnalytics('enableTracking');
  // Store consent preference
  localStorage.setItem('cookie-consent', 'all');
  // Reload page to restart recording
  window.location.reload();
});

// When user clicks "Reject Optional" on cookie banner
document.getElementById('reject-optional').addEventListener('click', () => {
  window.BrainfishAnalytics('disableTracking');
  // Store consent preference
  localStorage.setItem('cookie-consent', 'essential-only');
});

// On page load, check existing consent
if (localStorage.getItem('cookie-consent') === 'essential-only') {
  window.BrainfishAnalytics('disableTracking');
}

Configuring Web Agents

Share

Key Features

Installation

Getting the Agent Installation Code

Allow Brainfish domains for CSP connection

Implementation via <script type="module">

Implementation via NPM Package

Final Step

Can I create multiple agents?

Tracking for Guidance & Nudges

How to Identify a User with Brainfish Analytics

Why Use These Methods?

Events

onBrainfishHelpWidgetClosed

onBrainfishHelpWidgetOpened

Below is a matrix of the events you can subscribe to

Customisations

Pre-loading a question into a Brainfish agent widget

Setting Up a DNT Tag for Brainfish AI Agent

Setup

Real World Example of DNT handler set up to disable session recording

Share

Configuring Web Agents

Share

Key Features

Installation

Getting the Agent Installation Code

Allow Brainfish domains for CSP connection

Implementation via <script type="module">

Implementation via NPM Package

Final Step

Can I create multiple agents?

Tracking for Guidance & Nudges

How to Identify a User with Brainfish Analytics

Why Use These Methods?

Events

onBrainfishHelpWidgetClosed

onBrainfishHelpWidgetOpened

Below is a matrix of the events you can subscribe to

Customisations

Pre-loading a question into a Brainfish agent widget

Setting Up a DNT Tag for Brainfish AI Agent

Setup

Real World Example of DNT handler set up to disable session recording

Share

Implementation via `<script type="module">`

Implementation via `<script type="module">`