Skip to main content

Use source groups

Once you have organized your sources into source groups, you can configure your integrations to use specific groups. This ensures that queries are answered only using sources from the specified groups (plus any global sources).

This configuration respects group hierarchies. If you specify a subgroup, it also includes sources from the parent group, and vice versa. This is useful for deploying widgets in different configurations on different sites or sub-sites, configured for different source groups to make answers more targeted. For example, you could have one website pinned to "Version 24" and another to "Version 25".

Finding group IDs​

To find the ID of a source group:

  1. Go to the Sources view in your project
  2. Click Manage groups
  3. Find your group in the list
  4. Copy the group ID to use in your configuration

The group ID is a unique identifier that remains constant even if you rename the group.

Website Widget​

For the Website Widget, add the data-source-group-ids-include attribute to your script tag with a comma-separated list of group IDs:

<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="your-website-id"
  data-project-name="Your Project"
  data-project-color="#6306B6"
  data-project-logo="your-logo.png"
  data-source-group-ids-include="group-id-1,group-id-2"
></script>

Example: Different widgets for different documentation versions​

You might deploy different widget configurations on different documentation sites:

<!-- On docs.example.com/v24/ -->
<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="your-website-id"
  data-project-name="Example v24"
  data-source-group-ids-include="b2c3d4e5-f6a7"
></script>

<!-- On docs.example.com/v25/ -->
<script
  async
  src="https://widget.kapa.ai/kapa-widget.bundle.js"
  data-website-id="your-website-id"
  data-project-name="Example v25"
  data-source-group-ids-include="c3d4e5f6-a7b8"
></script>

Example: Dynamic configuration based on URL​

You can dynamically configure the widget based on the current URL path:

<script>
  // Determine which source groups to use based on URL
  function getSourceGroups() {
    const path = window.location.pathname;

    if (path.includes("/v24/")) {
      return "b2c3d4e5-f6a7"; // Version 24 group
    } else if (path.includes("/v25/")) {
      return "c3d4e5f6-a7b8"; // Version 25 group
    } else if (path.includes("/enterprise/")) {
      return "d4e5f6a7-b8c9,e5f6a7b8-c9d0"; // Enterprise + Advanced groups
    }

    return ""; // Default: all available sources
  }

  // Create and append the widget script
  const script = document.createElement("script");
  script.async = true;
  script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";
  script.dataset.websiteId = "your-website-id";
  script.dataset.projectName = "Your Project";
  script.dataset.projectColor = "#6306B6";
  script.dataset.projectLogo = "your-logo.png";

  const sourceGroups = getSourceGroups();
  if (sourceGroups) {
    script.dataset.sourceGroupIdsInclude = sourceGroups;
  }

  document.head.appendChild(script);
</script>

You can also change the filtering at runtime without reinitializing the widget; see setSourceGroupIDs in the widget's JavaScript API.

Support Form Deflector​

For the Support Form Deflector, add the data-source-group-ids-include attribute to your deflector script tag with a comma-separated list of group IDs, alongside your existing configuration:

<script
  src="https://widget.kapa.ai/kapa-support-form-deflector.bundle.js"
  data-integration-id="YOUR_INTEGRATION_ID"
  ...
  data-source-group-ids-include="group-id-1,group-id-2"
></script>

See the deflector's behavior configuration for the full attribute list.

Slack Bot​

For the Slack Bot, source groups are selected in the platform rather than in code:

  1. In Kapa, go to Integrations and open your Slack integration.
  2. Under Source groups, select the groups to scope the bot to.
  3. Save the configuration.

Global sources are always also included. See the Slack Bot configuration for the other settings on the form.

Chat SDK​

For the Chat SDK, set the sourceGroupIDsInclude option on the KapaProvider component:

import { KapaProvider } from "@kapaai/react-sdk";

<KapaProvider
  integrationId="your-integration-id"
  sourceGroupIDsInclude={["group-id-1", "group-id-2"]}
>
  <YourApplication />
</KapaProvider>;

Agent SDK​

For the Agent SDK, pass sourceGroupIdsInclude to the Agent constructor (core) or AgentProvider (React). The agent's built-in search_knowledge_base tool is then restricted to the specified groups.

import { AgentProvider } from "@kapaai/agent-react";

<AgentProvider
  projectId="your-project-id"
  integrationId="your-integration-id"
  model="kapa-agent-1.0"
  getSessionToken={getSessionToken}
  sourceGroupIdsInclude={["group-id-1", "group-id-2"]}
>
  <YourApplication />
</AgentProvider>;

See Agent core options and AgentProvider props for full details.

Hosted MCP server​

For the hosted MCP server, configure source groups during setup:

  1. In Kapa, go to Integrations and select your hosted MCP server.
  2. Under Source groups, select one or more groups to restrict the server to.
  3. Save the configuration.

Once configured, the MCP server only returns results from sources in the specified groups (plus any global sources). Clients connecting to the server cannot access sources outside these groups.

If you also use the source_group_ids_include parameter in the _meta field (available for API key authenticated servers), the server takes the intersection of the two lists. This lets clients narrow results further within the server's allowed groups, but never broaden beyond them.

For more details, see the Hosted MCP server documentation.

HTTP API​

If you call the Kapa HTTP API directly, pass source_group_ids_include as an array of group UUIDs in the request body. It is supported across the chat and retrieval endpoints.

{
  "query": "How do I get started?",
  "source_group_ids_include": ["c3d4e5f6-a7b8-4c8a-9d1e-2f3a4b5c6d7e"]
}

When set, only sources in the specified groups (plus any global sources) are used for the request.

Integrations without source group support​

Source group filtering is not currently available on the following integrations:

If you need source group filtering on one of these, reach out to support@kapa.ai.