Use a customization

Customizations are never applied at the Project level. A customization takes effect in one of two ways, so the same Project can run different customizations across different integrations, or none at all:

1. Associated with an integration. You associate a customization with a kapa integration on app.kapa.ai and every request through that integration uses it automatically. See Associating a customization with an integration.
2. Passed per request. You programmatically supply a customization_id on an individual request (a widget attribute, an SDK prop, or the API body). This takes priority: if a request passes a customization_id, that request uses it, even when the integration is associated with a different customization, while every other request through the integration still uses the associated one.

Customizations are not available for the Retrieval API, the MCP server, or the Agent SDK (which is fully custom by design).

The Slack Bot and Discord Bot support customizations only through association, not per request.

You can find the customization ID on the Customizations page in app.kapa.ai.

Associating a customization with an integration

You can associate a customization with an integration directly in app.kapa.ai, without changing any code on the integration itself. Once associated, every request through that integration uses the customization automatically. A customization_id passed on an individual request still takes precedence for that request.

There are two ways to manage the association:

• From the Integrations screen. Open Integrations in your project, find the integration, and pick a customization in the Customization column.
• From the customization. Open the customization on the Customizations page and use the Integrations selector to choose which integrations use it. One customization can be associated with many integrations.

Each integration uses at most one customization at a time. Associating one with an integration that already has a different customization replaces it.

Association is available for the Website Widget, Support Form Deflector, Chat SDK, Custom (API), Slack Bot, and Discord Bot integrations. The Internal Technical Assistant is configured differently: end users pick a customization per conversation, so you enable customizations for it rather than associating a single one (see below).

Internal Technical Assistant

End users pick a customization per conversation from the Style dropdown in the Internal Technical Assistant chat input. It is also the recommended playground for building and testing new customizations before rolling them out to other integrations.

To make a customization available there:

1. Open the customization on the Customizations page in app.kapa.ai.
2. Turn on Enable in Internal Assistant and save.

The selection is reflected in the URL via a customization_id query parameter, so a shared link can open the assistant with a specific style applied. On a customization's detail page, Try in Internal Assistant does this for you, opening the assistant in a new tab with that customization preselected.

Website Widget

Associate a customization with the widget's integration from the Kapa platform (see Associating a customization with an integration) and it applies automatically. To override it for a specific deployment, add the data-customization-id attribute to your widget script tag:

<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="#YOUR_HEX_COLOR_CODE"
  data-project-logo="https://example.com/logo.png"
  data-customization-id="YOUR_CUSTOMIZATION_ID"
></script>

Support Form Deflector

Associate a customization with the deflector's integration from the Kapa platform (see Associating a customization with an integration) and it applies automatically. To override it for a specific deployment, add the data-customization-id attribute to your Support Form Deflector script tag:

<script
  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="#main-question-input"
  data-submit-element-event-type="onClick"
  data-submit-element-query-selector="#submit-button"
  data-submit-button-query-selector="#submit-button"
  data-anchor-element-query-selector="#anchor-element"
  data-anchor-element-position="afterend"
  data-customization-id="YOUR_CUSTOMIZATION_ID"
></script>

Chat SDK

Associate a customization with the SDK's integration from the Kapa platform (see Associating a customization with an integration) and it applies automatically. To set one in code instead, pass the customizationId prop to the KapaProvider component:

<KapaProvider
  integrationId="YOUR_INTEGRATION_ID"
  customizationId="YOUR_CUSTOMIZATION_ID"
  callbacks={{...}}
>
  <YourApplication />
</KapaProvider>

API

When a request includes an integration_id, that integration's associated customization applies automatically. To override it for a specific request, pass customization_id in the request body when calling the Chat endpoint:

{
  "query": "How do I get started?",
  "customization_id": "YOUR_CUSTOMIZATION_ID"
}