Behavior
Below is a detailed list of all configuration options that control the support form deflectors behavior. There are required and optional parameters.
Required parameters
The following parameters are required to configure the website widget:
| Parameter | Description |
|---|---|
data-integration-id | This id instructs the support form deflector which of your kapa instances to connect to. |
data-main-input-query-selector | CSS selector for the main input element where the user enters their issue description. The support form selector will generate an answer for the issue described here. |
data-submit-element-query-selector | CSS selector for the element that triggers the support form deflector to generate an answer. This is typically the button that the user clicks to submit the form, or the form itself. |
data-submit-element-event-type | The event type that triggers the widget to generate the query. This can be onClick or onSubmit. See this FAQ on how to best configure data-submit-element-query-selector and data-submit-element-event-type together. |
data-submit-button-query-selector | The query selector of the form submit button. This is used to disable the button element while the answer is being generated for visual feedback. This has to be specified seperately because data-submit-element-query-selector is not always the submit button. |
data-anchor-element-query-selector | CSS selector for the element that the widget will be anchored to. This lets you control where in the form the support form deflector will insert its answer after generation. |
data-anchor-element-position | The position of the widget relative to the anchor element. This can be beforebegin, afterbegin, beforeend, or afterend. See MDN documentation for more information. |
Here's an example of how to configure the widget with the required parameters
<script
src="https://example.com/kapa-widget.js"
data-integration-id="your-integration-id"
data-main-input-query-selector="#main-question-input"
data-extra-input-query-selectors=".additional-inputs"
data-submit-element-event-type="onClick"
data-submit-element-query-selector="#submit-button"
data-anchor-element-query-selector="#anchor-element"
data-anchor-element-position="afterend"
></script>
Optional parameters
You can use the following optional parameters to customize the behavior of your website widget:
| Parameter | Description | Default Value |
|---|---|---|
data-extra-input-query-selectors | CSS selector for additional input elements that the support form deflector should submit to kapa alongside the content of data-main-input-query-selector. For example many support forms will let the user select the topic of their issue from a dropdown which is valuable information for kapa when generating an answer. | Not defined |
data-extra-input-names | A list of descriptive names for the inputs specified by data-extra-input-query-selectors. If this is not specified the support form deflector will use the name attribute of each input field. Sometimes the name attributes are not present or are not meaningful in which case it makes sense to explicitly override them. data-extra-input-names must have the same number of items as data-extra-input-query-selectors and they are mapped together by the order of data-extra-input-names. In general the names are required to tell kapa what kind of information is contained in an input field. | Not defined |
data-submit-button-text-query-selector | Specifies the CSS selector for locating the submit button text or label. Used in conjunction with data-submit-button-text-override. This is seperate from data-submit-button-query-selector because the text element of the button can be nested inside of the button. | Not defined |
data-submit-button-text-override | Overrides the original button text prior to the AI answer generation. The original button text is restored post generation. | Not defined |
data-main-input-formats-html | Set this to "true" to format HTML-structured input values from your main input field to markdown. This is useful for WYSYWIG editors for example, that return the input string as HTML. | "false" |
data-render-timeout | The time in milliseconds to wait before rendering the deflector widget. This might be useful if you have React SSR enabled on your page. You might need to wait for React to hydrate the page before the support deflector makes any changes. Otherwise, you might run into hydration issues. By default, the widget will render immediately. We recommend a value of 500ms as a starting point if you encounter issues. | "0" |
data-debug-mode | Logs additional information for testing purposes. | "false" |
data-deflection-failure-trigger-element-query-selector | CSS selector monitored to detect deflection failures. Interaction with this element after answer generation is counted as a deflection failure. See this FAQ to understand how deflection statistics are calculated. Only required for multi step forms. | data-submit-element-query-selector |
data-deflection-failure-trigger-element-event-type | This event type is monitored on the data-deflection-failure-trigger-element-query-selector DOM element to detect deflection failures. Only required for multi step forms. | data-submit-element-event-type |
data-option-to-cancel-answer-delay | Specifies the time delay in milliseconds after which the user is allowed to cancel the answer generation. | "60000" |
Functions
The Support Form Deflector exposes the following functions through the KapaSFD attribute on the global window object, which you can call using JavaScript.
| Function Name | Description |
|---|---|
unmount | Unmounts the Support Form Deflector widget and disables its functionality. This is useful for example if you would like to disable the deflector based on certain form inputs. |
render | (Re-)renders the Support Form Deflector and attaches all the event listeners required for deflecting a new Ticket submission. This can be useful if you have previously unmounted the support form deflector based on custom logic and now want to render it again. |
The following is an example of unmounting the support form deflector based on custom JavaScript. Here the developer wants the support form deflector to not trigger in case users select the Live Incident category in the support form.
// Obtain the currently selected value from a form input field
const requestType = document.querySelector("input[name=request_type]")?.value
// Unmount the deflector for certain
if (requestType === "Live Incident") {
window.KapaSFD.unmount()
}