Skip to main content

Widget FAQ

Why do I need to whitelist my domains?​

The Kapa Website Widget implements invisible reCAPTCHA to protect against bad actors connecting to your Kapa instance programmatically. This determines whether a person interacting with your widget is a real human or a bot. Only real humans are allowed to submit questions through the widget. The domain on which you are installing the Website Widget has to be whitelisted by the Kapa team. Simply share your target domain and any staging domains with the Kapa team and they will whitelist them for you immediately. If reCAPTCHA is not whitelisted you will see this error message in your widget:

reCAPTCHA token not yet configured.
Please reach out to the Kapa team at support@kapa.ai to complete the setup.

How do I enable search mode?​

By default, search mode is not enabled. To enable search mode you just need to set the data-search-mode-enabled parameter to "true" and it will appear on the widget. You can try the "Ask AI" Kapa widget on this page on the bottom right corner to see what this looks like.

Search Integration

If you want to have the Kapa search override your existing search you just need to set the data-modal-override-open-class parameter the class name of your existing search button (e.g., "my-search-bar-class") to override the modal open behavior. Alternatively, you can also set the data-modal-override-open-id parameter and assign the id of your existing HTML element. Assigning an id is more efficient than assigning a class name, as the latter requires iterating through the entire DOM tree.

There are more search configuration parameters listed above to e.g., specifcy sources returned and preferred order.

Can I listen to events?​

Yes, the Kapa widget exposes a set of events that can be listened to via the Kapa Web API, allowing any type of action to be triggered based on those events.

This is useful if you want to track Kapa usage in your analytics stack, such as tracking submitted questions in tools like Mixpanel, Amplitude, Segment, etc.

For more information on how to implement event listeners, refer to the Kapa Events API reference.

How can I attach the widget to a custom button?​

Instead of opening and closing the Kapa modal with the default floating widget, you can attach it to an existing element on your website.

To do this, first hide the default button using data-button-hide, and then use the following config options to select the element that should trigger the Kapa modal to open.

  • data-modal-override-open-class
  • data-modal-override-open-id
  • data-modal-override-open-class-search
  • data-modal-override-open-id-search
  • data-modal-override-open-class-ask-ai
  • data-modal-override-open-id-ask-ai

What are the default question rate limits?​

Per website:

  • Second: 10
  • Minute: 100
  • Hour: 500
  • Day: 2000

These limits are configurable. Reach out to the Kapa team and we will help you set up the limits that fit your needs.

What happens if I go over the set limit?​

The website rate limit is shared by all traffic to Kapa that goes through your website. If traffic from the website to your widget exceeds the limit, all users of the widget will see an error message until the usage is under the limit again:

System capacity reached, please wait a few minutes and try again.

How do I fix "Configuration issue detected" error?​

There are different scenarios where the Kapa website widget could display a Configuration issue detected error message. A common cause of this is a CORS error.

To debug this error and get the excact root cause, try opening the developer tools of your browser and check the network tab for the exact error code and error message.

The widget state does not reset between page reloads​

In Single-Page Applications (SPAs), the widget is loaded globally, outside the component tree, and its state persists between page transitions. This means that if you navigate to a new page, the widget might still be rendered or maintain its previous state, which may not be the desired behavior.

To address this, you can manually control the widget's lifecycle using the render() and unmount() functions. For example, you can unmount the widget when leaving a page and reinitialize it when entering a new page. For more details, see the Widget lifecycle management tutorial.