Knowledge Box Configuration

Overview

The ai12z Knowledge Box supports multiple configurations per agent, allowing you to customize the appearance, behavior, and functionality for different use cases. Each configuration can be independently managed and applied to specific Knowledge Box instances using a unique Config ID.

Managing Configurations

Creating a Configuration

Navigate to your agent's Knowledge Box configuration page where you can view and manage all available configurations. Each configuration includes:

Name: A descriptive identifier for the configuration
Config ID: A unique identifier used to reference this configuration in your code
Description: A brief explanation of the configuration's purpose
Modified Date: When the configuration was last updated
Default Status: One configuration can be marked as the default

kb configuration

Using a Configuration

When you have multiple configurations, specify which one to use by adding the config-id attribute to the Knowledge Box tag. If no config-id is specified, the default configuration will be used.

<!-- Using a specific configuration -->
<ai12z-knowledge-box data-key="<API_KEY>" config-id="69403a0b13dce28e2e1f84f2">
</ai12z-knowledge-box>

<!-- Using the default configuration -->
<ai12z-knowledge-box data-key="<API_KEY>"></ai12z-knowledge-box>

Configuration Tabs

Each configuration consists of three main tabs: Settings, Style, and Script. These tabs allow you to control different aspects of the Knowledge Box behavior and appearance.

Configuration Tabs

Each configuration consists of three main tabs: Settings, Style, and Script. These tabs allow you to control different aspects of the Knowledge Box behavior and appearance.

Settings Tab

The Settings tab controls the core functionality and appearance of your Knowledge Box.

kb settings

Basic Settings

Setting	Description	Example
Title	The heading displayed above the Knowledge Box content	"AI overview", "Smart Answers", etc.
Number of Lines	Controls how many lines of content are visible before the "Show More" button appears	Default: 10
Show More Button Label	Text displayed on the button to expand content	"Show more", "Read more", "See full answer"
Show Less Button Label	Text displayed on the button to collapse content	"Show less", "Collapse", "Hide details"

Question Type

The Question Type setting determines how questions are passed to the Knowledge Box. There are three options:

kb question type

1. Static

With Static mode, you can define a default question that loads automatically when the page loads. Users can still submit new questions via JavaScript or by interacting with the Knowledge Box.

kb static question

Use Case: Pre-populate a common question or show a default answer when the page loads.

<ai12z-knowledge-box
  data-key="<API_KEY>"
  question="What gear do I need for backcountry skiing?"
>
</ai12z-knowledge-box>

2. JavaScript

JavaScript mode requires you to programmatically set the question using JavaScript. The Knowledge Box will not display content until a question is provided via code.

Use Case: Integrate with your existing search functionality or trigger questions based on user interactions.

const knowledgeBox = document.querySelector("ai12z-knowledge-box")
knowledgeBox.setAttribute("question", "What are the best ski boots?")

3. Query String

Query String mode automatically reads the question from the URL parameter kbquery. This is useful for deep linking or sharing specific Knowledge Box queries.

Use Case: Enable bookmarkable or shareable Knowledge Box results.

Example URL: https://yoursite.com/search?kbquery=what+are+ski+boot+sizes

The Knowledge Box will automatically detect and load the question from the URL.

Options

kb options

Relevance Score: When enabled, displays confidence scores or relevance indicators with the AI-generated answers
Show Message Icons: When enabled, displays icons alongside messages or answer sections for better visual organization

Theme Color

Choose a theme color preset for your Knowledge Box:

Default: Standard ai12z branding colors
Custom: Create a custom theme with your brand colors (see Custom Theme section below)

Create Custom Theme

When you select "Custom" theme color, you can define specific CSS variables to match your brand:

:root {
  --ai12z-knowledge-box-font-family: ui-sans-serif, system-ui, sans-serif,
    "Apple Color Emoji", "Segoe UI Emoji";
  --ai12z-knowledge-box-font-size: 1rem;
  --ai12z-knowledge-box-bg-color: rgb(
    241 245 249
  ); /* background color of the AI response container */
  --ai12z-knowledge-box-button-bgcolor: #0076ff; /* AI response button background color */
  --ai12z-knowledge-box-button-color: #fff; /* AI response button text color */
  --ai12z-knowledge-box-privacy-color: #647480; /* AI response privacy text color */
  --ai12z-knowledge-box-privacy-font-size: 0.875rem; /* AI response privacy font size */
}

--ai12z-knowledge-box-privacy-font-size: 0.875rem; /_ AI response privacy font size _/ }

## Style Tab

The Style tab allows you to add custom CSS to further customize the appearance of your Knowledge Box beyond the theme settings.

![kb additional styles](/img/kb-style.jpg)

### Custom CSS

Use the Custom CSS editor to:
- Override default styles
- Add responsive design rules
- Customize specific elements within the Knowledge Box
- Match your site's design system

**Example Custom CSS**:
```css
/* Custom styling for Knowledge Box container */
ai12z-knowledge-box {
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  border-radius: 12px;
}

/* Customize the title */
.kb-title {
  font-weight: 600;
  color: #1e293b;
}

/* Responsive adjustments */
@media (max-width: 768px) {
  ai12z-knowledge-box {
    font-size: 0.9rem;
  }
}

History

The History tab within the Style section tracks all previous versions of your custom CSS, allowing you to:

Review past changes
Revert to previous versions if needed
Compare different styling approaches

Script Tab

The Script tab enables you to add custom JavaScript to enhance or modify the Knowledge Box behavior.

kb additional scripts

Custom JavaScript

Use the Custom JS editor to:

Add event listeners to Knowledge Box interactions
Integrate with analytics or tracking tools
Implement custom business logic
Extend functionality beyond default capabilities

Example Custom JavaScript:

// Track when users interact with the Knowledge Box
document.addEventListener("DOMContentLoaded", function () {
  const kb = document.querySelector("ai12z-knowledge-box")

  // Track when a question is answered
  kb.addEventListener("answer-loaded", function (event) {
    console.log("Answer loaded for question:", event.detail.question)

    // Send to analytics
    if (typeof gtag !== "undefined") {
      gtag("event", "kb_answer_loaded", {
        question: event.detail.question,
      })
    }
  })

  // Track show more clicks
  kb.addEventListener("show-more-clicked", function () {
    console.log("User expanded the answer")
  })
})

History

The History tab within the Script section tracks all previous versions of your custom JavaScript, providing version control and the ability to restore earlier implementations.

Best Practices

Configuration Management

Use Descriptive Names: Give each configuration a clear, descriptive name that indicates its purpose (e.g., "Homepage FAQ", "Product Support", "Search Integration")
Set a Default: Always designate one configuration as the default to ensure the Knowledge Box works even without a specified config-id
Test Before Deploying: Use the configuration preview to test your settings before deploying to production

Question Type Selection

Use Static when you want to showcase a specific answer on page load
Use JavaScript for dynamic integration with search or user interactions
Use Query String when you need shareable or bookmarkable answers

Styling Guidelines

Start with Theme Colors: Use the built-in theme options before adding custom CSS
Maintain Consistency: Ensure your Knowledge Box styling matches your site's overall design
Test Responsiveness: Always verify your custom styles work across different screen sizes
Use CSS Variables: Leverage the provided CSS variables for easier maintenance

Script Safety

Test Thoroughly: Always test custom JavaScript in a development environment first
Avoid Conflicts: Be careful not to override core Knowledge Box functionality
Performance: Keep custom scripts lightweight to maintain fast load times
Error Handling: Include proper error handling in your custom code

Example: Complete Configuration

Here's a complete example showing how to set up a Knowledge Box with a custom configuration for a search results page:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Search with AI Knowledge Box</title>

    <!-- ai12z web components -->
    <script
      type="module"
      src="https://cdn.ai12z.net/pkg/ai12z@latest/dist/esm/library.js"
    ></script>
    <link
      rel="stylesheet"
      href="https://cdn.ai12z.net/pkg/ai12z@latest/dist/library/library.css"
    />
  </head>

  <body>
    <div class="search-container">
      <input id="searchInput" type="search" placeholder="Ask a question..." />
      <button id="searchBtn">Search</button>

      <!-- Knowledge Box with specific configuration -->
      <ai12z-knowledge-box
        id="kb"
        data-key="YOUR_API_KEY"
        config-id="69403a0b13dce28e2e1f84f2"
      ></ai12z-knowledge-box>

      <!-- Your existing search results go here -->
      <div id="searchResults"></div>
    </div>

    <script>
      const searchInput = document.getElementById("searchInput")
      const searchBtn = document.getElementById("searchBtn")
      const kb = document.getElementById("kb")

      function handleSearch() {
        const query = searchInput.value.trim()
        if (!query) return

        // Update Knowledge Box with the query
        kb.setAttribute("question", query)

        // Your existing search logic here
        // fetchSearchResults(query);
      }

      searchBtn.addEventListener("click", handleSearch)
      searchInput.addEventListener("keydown", (e) => {
        if (e.key === "Enter") handleSearch()
      })
    </script>
  </body>
</html>

Troubleshooting

Configuration Not Loading

Problem: The Knowledge Box doesn't reflect your configuration changes.

Solutions:

Verify the config-id matches exactly (case-sensitive)
Clear your browser cache and reload
Check that the configuration is saved (not in draft mode)
Verify your API key is correct

Custom Styles Not Applied

Problem: Custom CSS doesn't appear to work.

Solutions:

Check for CSS specificity issues - you may need to use !important or more specific selectors
Verify there are no syntax errors in your CSS
Remember that Knowledge Box uses Shadow DOM - some styles may need to use CSS variables
Test with browser developer tools to see which styles are being applied

JavaScript Errors

Problem: Custom JavaScript causes errors or breaks functionality.

Solutions:

Check browser console for specific error messages
Ensure all event listeners are properly attached
Verify that DOM elements exist before accessing them
Use try-catch blocks for error handling

Knowledge Box Component - Main component documentation
Agent Settings - Managing your agent and API keys
AI Brand Creation - Customizing AI responses

Overview​

Managing Configurations​

Creating a Configuration​

Using a Configuration​

Configuration Tabs​

Configuration Tabs​

Settings Tab​

Basic Settings​

Question Type​

1. Static​

2. JavaScript​

3. Query String​

Options​

Theme Color​

Create Custom Theme​

History​

Script Tab​

Custom JavaScript​

History​

Best Practices​

Configuration Management​

Question Type Selection​

Styling Guidelines​

Script Safety​

Example: Complete Configuration​

Troubleshooting​

Configuration Not Loading​

Custom Styles Not Applied​

JavaScript Errors​

Related Documentation​

Overview

Managing Configurations

Creating a Configuration

Using a Configuration

Configuration Tabs

Configuration Tabs

Settings Tab

Basic Settings

Question Type

1. Static

2. JavaScript

3. Query String

Options

Theme Color

Create Custom Theme

History

Script Tab

Custom JavaScript

History

Best Practices

Configuration Management

Question Type Selection

Styling Guidelines

Script Safety

Example: Complete Configuration

Troubleshooting

Configuration Not Loading

Custom Styles Not Applied

JavaScript Errors

Related Documentation