Skip to main content

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 founders@kapa.ai to complete the setup.”

Where do I find my data-website-id?​

Reach out to the kapa team by Slack or email to get your website id.

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 enable anonymous user tracking?​

By default, the kapa widget does not track or store any data besides the questions asked by users and answers provided by the AI model. However, you can enable anonymous user tracking to gain insights into user interactions without storing any personal data.

Configuration​

To enable anonymous user tracking, add the following attribute to your widget script tag:

  • data-user-analytics-fingerprint-enabled: Set to "true" to enable anonymous user tracking.

Note that the "true" value is a string, not a boolean as shown below:

<script async
src="https://widget.kapa.ai/kapa-widget.bundle.js"
data-website-id="XXX-XXX-XXX"
...
data-user-analytics-fingerprint-enabled="true"
></script>

This setting activates the device and browser fingerprinting feature, which tracks user interactions anonymously.

Benefits​

Enabling this feature provides several benefits:

  • User Engagement: Understand how many unique users interact with the widget.
  • User Retention: Track how frequently users return and interact with the widget.
  • Content Optimization: Analyze the types of questions users frequently ask, helping to optimize and tailor the content accordingly.

Technology​

The anonymous tracking is powered by the commercial version of Fingerprint, which provides a robust method for generating a consistent identifier for users based on their browser and device characteristics. See here for their privacy policy. kapa stores only the hash (the visitor ID) generated by Fingerprint and nothing else.

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

Instead of opening and closing the kapa widget with the default button you can attach it to any element in your UI.

To do this first hide the default button using data-button-hide and then make use of the following config options to trigger the widget from one or multiple different components.

  • 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:

I have some global CSS defined that is overriding the widget's styles. How can I fix this?​

If you have global CSS selectors with higher specificity than the Kapa widget styles, you can prevent those styles from affecting elements within the Kapa widget by using the :not() pseudo-class in combination with the following IDs:

  • kapa-widget-portal: ID that targets the outermost DOM element that contains the widget’s modal.
  • kapa-widget-container: ID that targets the outermost DOM element that contains the widget’s button.

For example, if you have a global CSS selector as shown below:

h3 {
  color: pink;
}

To prevent this style from applying to the <h3> elements within the widget, you can modify the selector using the :not() pseudo-class to exclude all descendants of the element with the ID kapa-widget-portal in the DOM like this:

h3:not(#kapa-widget-portal *) {
  color: pink;
}

What are the default question rate limits?​

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

You can configure all of these limits. Simply 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?​

  • Website rate limit
    • This rate limit is shared by all users to the website. When the website goes over the limit all users of the widget will see an error message until the usage is under the limit again:
    • i.e. "System capacity reached, please wait a few minutes and try again.”