Skip to main content

Quickstart

In this quickstart, you install the Website Widget on your site and ask it your first question. It works on any website where you can add a script tag; if you use a documentation platform, the platform-specific guides at the end cover the same steps for your tooling.

By the end, you will have:

  • The Kapa agent live on your site, answering from your knowledge base with citations.
  • Your Integration ID, which every further configuration step builds on.

Before you start​

Before you start, you should have:

  • A Kapa project with indexed knowledge sources. If you have not done this yet, complete Index your first source first.
  • Permission to edit the project; if buttons in the platform are greyed out, contact a team admin.
  • Access to your website's <head> markup, directly or through your platform's configuration.

Create your widget integration​

  1. Open app.kapa.ai, navigate to Integrations (under Configuration in the sidebar), and click Add new integration.
  2. Choose Website Widget and give it a descriptive name.
  3. Enable your domains and set them live: your production domain (https://www.example.com) and any staging domains (https://staging.example.com). For dynamic subdomains, use a regex pattern such as ^https://\w+\.example\.com$. For local testing, http://localhost is enabled by default.

Only requests from enabled domains can submit questions through the widget. This restriction powers the bot protection and prevents others from using your integration on unauthorized sites.

Copy your Integration ID​

In the integration row's Actions column, click Copy integration ID.

note

The widget script calls this value the Website ID (data-website-id); it is the same value as the Integration ID you copy here.

Add the script tag​

Insert the following script tag into the <head> section of your website:

<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-project-name="YOUR_PROJECT_NAME"
  data-project-color="#YOUR_HEX_COLOR_CODE"
  data-project-logo="https://YOUR_LOGO_URL.com/logo.png"
></script>

Replace the placeholder values. Only the ID is strictly required; the other three are the branding basics, and without them the widget falls back to a neutral gray theme and a generic placeholder logo:

  • YOUR_WEBSITE_ID (required): the Integration ID you copied in the previous step.
  • YOUR_PROJECT_NAME: the name your users know your product by, shown in the widget header.
  • YOUR_HEX_COLOR_CODE: your brand color, inherited by several widget components.
  • https://YOUR_LOGO_URL.com/logo.png: a direct URL to your logo.

Verify the installation​

Refresh your website. The widget button appears in the bottom right corner; ask it a question about your product and you should get an answer grounded in your knowledge base, with citations.

If the widget does not load and your site has a Content Security Policy, whitelist the required domains; see How do I fix CSP errors?

note

The widget performs anonymous user tracking by default. Local privacy regulations may require you to collect consent before you anonymously identify users; see user tracking.

Summary​

You created the widget integration and enabled your domains, copied your Integration ID, added the widget script to your site, and verified that it answers from your knowledge base.

Next steps​