Skip to main content

Add AI Chat Widget to Salesforce Service Cloud - Kapa Integration

Integrate the Kapa Website Widget into your Salesforce Service Cloud to enable users to ask natural language questions about your product, significantly enhancing user experience by providing quick and accurate answers.

Prerequisites​

Before adding the widget to your Salesforce Service Cloud, you'll need to:

  1. Ensure you have a Kapa project set up with your knowledge sources added.
  2. Follow the general installation instructions to enable your domain and obtain your website ID.

Installation​

Why use a static resource in Salesforce?​

Salesforce blocks loading scripts directly from external CDNs by default as a security measure. To work around this limitation, you need to upload the widget script as a static resource in Salesforce and then reference it locally.

Step 1: Download and upload the widget script​

  1. Download the widget script from: https://widget.kapa.ai/kapa-widget.bundle.js
  2. Log in to your Salesforce Service Cloud account as an administrator.
  3. Navigate to the Setup section by clicking on the gear icon in the top right corner.
  4. In the Setup menu, search for Static Resources and select it.
  5. Click on New to create a new Static Resource.
  6. Fill in the details:
    • Name: KapaWidgetJS (this name is used in references to the resource)
    • Description: Kapa AI Widget Script
    • File: Upload the downloaded kapa-widget.bundle.js file
    • Cache Control: Select "Public" to enable caching
  7. Click Save.

Step 2: Create a Visualforce page​

Visualforce pages provide better DOM control and are more reliable for integrating external scripts in Salesforce compared to Aura components.

  1. In the Setup menu, search for Visualforce Pages and select it.

  2. Click on New to create a new Visualforce page.

  3. Fill in the details:

    • Label: KapaWidgetPage
    • Name: KapaWidgetPage
    • Available for Lightning Experience, Lightning Communities, and the mobile app: Check this box

  4. Replace the default code with the following:

    <apex:page sidebar="false" showHeader="false" lightningStylesheets="true">
      <script>
        var script = document.createElement("script");
        script.src = "{!URLFOR($Resource.KapaWidgetJS)}";
        script.setAttribute("data-website-id", "YOUR_WEBSITE_ID");
        script.setAttribute("data-project-name", "YOUR_PROJECT_NAME");
        script.setAttribute("data-project-color", "YOUR_HEX_COLOR_CODE");
        script.setAttribute("data-project-logo", "YOUR_LOGO_URL");
        script.async = true;
        document.head.appendChild(script);
      </script>
    </apex:page>

  5. Replace YOUR_WEBSITE_ID, YOUR_PROJECT_NAME, YOUR_HEX_COLOR_CODE, and YOUR_LOGO_URL with your specific project parameters.

  6. Click Save.

Step 3: Add the Visualforce page to your Salesforce layout​

  1. Navigate to the page or record where you want to add the Kapa Website Widget.
  2. Add a Visualforce component and select KapaWidgetPage.
  3. Click Save and activate the changes.

Step 4: Test the widget​

Navigate to the page where you added the widget to ensure it loads correctly and functions as expected.

Troubleshooting​

  • Widget Not Appearing: Ensure that you have set the correct height for the Visualforce component in your page layout.
  • Script Loading Error: Verify that the static resource name in your Visualforce page matches exactly what you created (KapaWidgetJS).
  • Functionality Issues: Check that all your widget parameters (website ID, project name, etc.) are correctly set in the Visualforce page.
  • CSP Restrictions: If you encounter Content Security Policy (CSP) issues, you may need to modify your Salesforce CSP settings to allow the widget to function properly. See FAQ: how do I fix Content Security Policy (CSP) errors?.