Skip to main content

Setup

The Kapa Support Form Deflector can be embedded into any form that allows you to inject JavaScript.

note

You're welcome to reach out to support@kapa.ai and we'll help set up the Support Form Deflector on your behalf.

Prerequisites​

If your website has a Content Security Policy enabled, you'll need to whitelist the following domains in your CSP configuration to allow the support form deflector to function properly:

  • https://proxy.kapa.ai - Proxy for widget functionality
  • https://kapa-widget-proxy-la7dkmplpq-uc.a.run.app - A fallback for the main proxy
  • https://www.google.com/recaptcha - For reCAPTCHA functionality
  • http://metrics.kapa.ai - For optional analytics and metrics collection

1. Create new integration​

Before you start, you must create a new integration in the Kapa platform.

  1. Visit the Integrations tab on the Kapa platform.
  2. Click the Add new integration button.
  3. Create a new Support Form Deflector integration.

2. Enable your domains​

In the set up screen of the new integration enable the domain on which you want to embed the Support Form Deflector.

This includes both your production domain (e.g., https://www.example.com) and any staging domains (e.g., https://staging.example.com). For dynamic subdomains, you can use regex patterns (e.g., ^https://\w+.example.com$). For testing purposes, http://localhost is enabled by default.

3. Copy your Integration ID​

You will need the integration ID when embedding the Support Form Deflector in your website.

4. Insert the JavaScript​

The Support Form Deflector is a JavaScript bundle injected onto the website page(s) containing your support form.

The following example script is a reference implementation of the support form deflector. It defines values for some of the parameters most commonly set. Insert the script tag into the <head> section of your website to activate the deflector on your support form.

<script
  async
  src="https://widget.kapa.ai/kapa-support-form-deflector.bundle.js"
  data-integration-id="YOUR_INTEGRATION_ID"
  data-project-color="#YOUR_HEX_COLOR_CODE"
  data-main-input-query-selector="#request_description"
  data-extra-input-query-selectors="#request_subject,#request_product_family"
  data-extra-input-names="Subject, Product Family"
  data-submit-element-event-type="onSubmit"
  data-submit-element-query-selector="#new_request input[type=submit]"
  data-anchor-element-query-selector="#new_request input[type=submit]"
  data-anchor-element-position="beforebegin"
  data-submit-button-text-query-selector="#new_request input[type=submit]"
  data-submit-button-text-override="Next Step"
  data-pre-submit-info-text="Our AI assistant will check if we can help you right away. If you still need assistance afterwards, you can submit a ticket to our support team."
></script>

The exact set of parameters and values to configure depend on how your support form is implemented. Read the reference documentation for behavioral parameters and styling parameters to understand all of the available configuration parameters.

Parameter breakdown
  • data-integration-id: The unique identifier for your Support Form Deflector integration.
  • data-project-color: A HEX color code that sets the theme color for the widget.
  • data-main-input-query-selector: A CSS query selector targeting the primary input field in your support form.
  • data-extra-input-query-selectors: A comma-separated list of CSS query selectors for additional input fields in your support form.
  • data-extra-input-names: A comma-separated list of names corresponding to each extra input field defined by the selectors above.
  • data-submit-element-event-type: Specifies the event type to listen for on the submit element (onSubmit or onClick).
  • data-submit-element-query-selector: A CSS query selector for the form's submit element.
  • data-anchor-element-query-selector: A CSS query selector used to determine the element relative to which the deflector will be inserted.
  • data-anchor-element-position: Defines the placement of the deflector in relation to the anchor element.
  • data-submit-button-text-query-selector: A CSS query selector targeting the text element within the submit button.
  • data-submit-button-text-override: Overrides the default text on the submit button with custom text. We recommend changing the text to "Next Step" when the Support Form Deflector is active.
  • data-pre-submit-info-text: Informational text displayed to users before they click the button that generates an answer.
tip

Set data-debug-mode="true" to obtain more informative logs while testing the configuration.

5. Verify Installation​

After adding the script, open the page containing the support form in a browser, and verify that the Support Form Deflector works:

  1. Fill in the fields of the support form with some example values.
  2. Click the button to submit the form (labeled Next Step in the example configuration provided earlier).
  3. Verify that the Support Form Deflector intercepted the submission and generated a response.

Best practice checklist​

The following checklist outlines key best practices to ensure your Kapa Support Form Deflector is optimally configured.

  • Capture full context: Use data-extra-input-query-selectors and data-extra-input-names to include additional inputs (e.g., product category). This extra context helps generate more relevant AI responses.

  • Clarify button actions: Override the default submit button text (via data-submit-button-text-query-selector and data-submit-button-text-override) to display labels like "Next Step". This signals that clicking the button does not immediately submit a support request.

  • Add a pre-info text for extra transparency: Set data-pre-submit-info-text so that informative text appears near the button, informing users that an AI-generated response will be created before the issue can be submitted.

  • Display AI answers selectively: Ensure the AI-generated answer is only shown for appropriate cases. For example, if certain support topics (like billing changes) require human review, adjust your logic to avoid rendering the AI answer.

    Set data-render-on-load="false" to defer widget rendering. Use the global functions (see Render the Support Form Deflector manually) to re-render or unmount the widget based on custom logic.

  • Tweak styling to match your support form: Customize the deflector’s appearance using our extensive styling parameters. Refer to the Styling parameters documentation for guidance on aligning the widget with your support form's layout.

Further reading​

For more information about the available configuration parameters, see behavioral parameters and styling parameters.

For step-by-step instructions on how to implement the Support Form Deflector for specific platforms or use cases, refer to these tutorials: