Base Settings

The base configuration provides core settings for all Inkeep widgets. These settings control authentication, branding, theming, and general behavior.

Basic Configuration

import { type InkeepBaseSettings } from "@inkeep/cxkit-types";
 
// Simple configuration
const baseSettings: InkeepBaseSettings = {
  // Core authentication and branding
  env: "production",
  apiKey: "YOUR_API_KEY",
  organizationDisplayName: "Your Organization",
  primaryBrandColor: "#26D6FF", // See "Theme Customization" section for advanced theming options
  shouldBypassCaptcha: false, // Only enable with server-side API keys
 
  // User identification - See "User Properties" section for all options
  userProperties: {
    id: "user-id",
    email: "user@example.com",
    name: "User Name",
  },
 
  // Optional: Analytics configuration - See "Analytics Configuration" section
  privacyPreferences: {
    optOutAnalyticalCookies: false,
    optOutAllAnalytics: false,
  },
 
  // Optional: Color mode sync - See "Color Mode" section for advanced options
  colorMode: {
    sync: {
      target: document.documentElement,
      attributes: ["data-theme"],
      isDarkMode: (attrs) => attrs["data-theme"] === "dark",
    },
  },
};
 
// Advanced configuration with enterprise features
const enterpriseSettings: InkeepBaseSettings = {
  env: process.env.NODE_ENV,
  apiKey: process.env.INKEEP_API_KEY,
  organizationDisplayName: "Enterprise Corp",
  primaryBrandColor: "#0A2463",
  aiApiBaseUrl: "https://api.enterprise.com/inkeep",
  analyticsApiBaseUrl: "https://analytics.enterprise.com",
  userProperties: {
    id: getUserId(),
    email: getUserEmail(),
    name: getUserName(),
    role: getUserRole(),
    team: getCurrentTeam(),
  },
  userAuthToken: getAuthToken(),
  tags: ["enterprise", "self-hosted", getCurrentRegion()],
};

Configuration Options

Core Settings

Essential configuration options for authentication, branding, and basic widget setup. These settings form the foundation of your Inkeep integration.

Each setting serves a specific purpose in customizing the widget behavior:

Option	Type	Required	Description
`env`	`'production' \| 'development'`	No	Environment setting (defaults to 'production')
`apiKey`	`string`	Yes	Your Inkeep API key
`organizationDisplayName`	`string`	No	Display name for your organization
`primaryBrandColor`	`string`	Yes	Primary brand color (hex code)
`aiApiBaseUrl`	`string`	No	Custom base URL for API endpoints
`analyticsApiBaseUrl`	`string`	No	Custom base URL for analytics endpoints
`shadowHost`	`HTMLElement \| null`	No	Reference to shadow DOM host element
`rootElement`	`HTMLElement \| null`	No	Reference to root mounting element
`shouldBypassCaptcha`	`boolean`	No	Bypass captcha challenge (server-side API only)
`tags`	`string[]`	No	Custom tags for widget identification
`prism`	`Prism`	No	Instance of Prism for syntax highlighting. You can add support for additional languages by importing them from `prismjs` and passing in the Prism instance

User Properties

Configure user-specific information for personalization, tracking, and authentication. This allows you to identify users and provide personalized experiences.

interface UserProperties {
  /**
   * The user ID.
   */
  id?: string;
  /**
   * The user email.
   */
  email?: string;
  /**
   * The user name.
   */
  name?: string;
  /**
   * The user cohorts.
   */
  cohorts?: string[];
}

Property	Type	Required	Description
`userProperties`	`UserProperties`	No	User identification and metadata
`userAuthToken`	`string`	No	Authentication token for the user

// Basic user configuration
const baseSettings: InkeepBaseSettings = {
  userProperties: {
    id: "user-123",
    email: "user@example.com",
    name: "John Doe",
  },
};
 
// Advanced user configuration
const enterpriseSettings: InkeepBaseSettings = {
  userProperties: {
    id: "user-456",
    email: "jane@enterprise.com",
    name: "Jane Smith",
    cohorts: ["admin", "engineering"],
  },
  userAuthToken: "jwt-token-here",
};

Privacy Preferences

Control analytics and cookie preferences for tracking user interactions with the widget.

interface PrivacyPreferences {
  /**
   * Whether to opt out of analytical cookies
   */
  optOutAnalyticalCookies?: boolean;
  /**
   * Whether to opt out of all analytics
   */
  optOutAllAnalytics?: boolean;
  /**
   * Whether to opt out of functional cookies
   */
  optOutFunctionalCookies?: boolean;
}

Property	Type	Required	Description
`privacyPreferences`	`PrivacyPreferences`	No	Privacy preferences configuration

// Basic analytics configuration
const baseSettings: InkeepBaseSettings = {
  // ...
  privacyPreferences: {
    optOutAnalyticalCookies: false,
    optOutAllAnalytics: false,
    optOutFunctionalCookies: false,
  },
};
 
// Privacy-focused configuration
const privacySettings: InkeepBaseSettings = {
  // ...
  privacyPreferences: {
    optOutAnalyticalCookies: true,
    optOutAllAnalytics: true,
    optOutFunctionalCookies: true,
  },
};

Event Handling

Configure callbacks for tracking and processing widget events. This allows you to integrate with your own analytics or monitoring systems.

type InkeepCallbackEvent = InkeepEventWithCommon & {
  userProperties: UserProperties;
  eventName: string;
  properties: {
    componentType?: any;
    tags?: string[];
    [key: string]: any;
  };
};

Property	Type	Required	Description
`onEvent`	`(event: InkeepCallbackEvent) => void`	No	Event processing callback function

// Basic event handling
const baseSettings: InkeepBaseSettings = {
  // ...
  onEvent: (event) => {
    console.log("Event:", event.eventName, event.properties);
    analytics.track(event.eventName, event.properties);
  },
};

You can see the Analytics guide for more information.

Color Mode

Synchronize the widget's appearance with your application's theme. This enables seamless dark/light mode integration.

interface ColorMode {
  // ...
  sync?: {
    target: HTMLElement | string;
    attributes: string[];
    isDarkMode: (attributes: Record<string, string | null>) => boolean;
    onChange?: (colorMode: string) => void;
  };
}

Property	Type	Required	Description
`colorMode`	`ColorMode`	No	Theme synchronization configuration

// Basic color mode configuration
const baseSettings: InkeepBaseSettings = {
  // ...
  colorMode: {
    sync: {
      target: document.documentElement,
      attributes: ["data-theme"],
      isDarkMode: (attrs) => attrs["data-theme"] === "dark",
    },
  },
};
 
// Advanced color mode configuration
const advancedSettings: InkeepBaseSettings = {
  // ...
  colorMode: {
    sync: {
      target: document.documentElement,
      attributes: ["data-theme", "class"],
      isDarkMode: (attrs) => {
        const preference = localStorage.getItem("theme");
        return (
          preference === "dark" ||
          attrs["data-theme"] === "dark" ||
          attrs["class"]?.includes("dark") ||
          window.matchMedia("(prefers-color-scheme: dark)").matches
        );
      },
      onChange: (mode) => {
        localStorage.setItem("theme", mode);
        updateThemeColor(mode);
      },
    },
  },
};

Theme Customization

Configure advanced styling and branding options for the widget. This includes colors, styles, and custom CSS.

interface UserTheme {
  // ...
  syntaxHighlighter?: {
    lightTheme?: any;
    darkTheme?: any;
  };
  primaryColors?: PrimaryColors;
  varsClassName?: string;
  styles?: Array<{
    key: string;
    type: "link" | "style";
    value: string;
  }>;
}

Property	Type	Required	Description
`theme`	`UserTheme`	No	Theme customization settings

// Basic theme configuration
const baseSettings: InkeepBaseSettings = {
  // ...
  theme: {
    primaryColors: {
      medium: "#26D6FF",
      light: "#60a5fa",
      strong: "#1d4ed8",
    },
    styles: [
      {
        key: "chat-container",
        type: "style",
        value: ".ikp-chat { border-radius: 8px; }",
      },
    ],
  },
};
 
// Advanced theme configuration
const enterpriseSettings: InkeepBaseSettings = {
  // ...
  theme: {
    primaryColors: {
      mediumSubtle: "rgba(38, 214, 255, 0.3)",
      strong: "#1d4ed8",
      stronger: "#1e40af",
    },
    syntaxHighlighter: {
      lightTheme: themes.github,
      darkTheme: themes.dracula,
    },
    styles: [
      {
        key: "google-fonts",
        type: "link",
        value:
          "https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap",
      },
      {
        key: "custom-theme",
        type: "style",
        value: `
          .ikp-chat {
            width: min(95vw, 600px);
            border-radius: clamp(8px, 2vw, 16px);
            background: var(--ikp-color-background);
            @media (max-width: 768px) {
              width: 100vw;
              border-radius: 0;
            }
          }
        `,
      },
    ],
  },
};

You can see the Theme Customization guide for more information.

Custom Icons

Configure custom icons for various widget elements. You can use built-in icons from popular icon libraries or provide custom SVG URLs.

type InkeepCustomIcon =
  | {
      builtIn: AvailableBuiltInIcons;
    }
  | {
      custom: string; // url of svg or png of icon
    };
 
type CustomIconMap = {
  [K in keyof CustomIcons]?: InkeepCustomIcon;
};

Property	Type	Required	Description
`customIcons`	`CustomIconMap`	No	Custom icon configurations

const baseSettings: InkeepBaseSettings = {
  env: "production",
  apiKey: "YOUR_API_KEY",
  organizationDisplayName: "Enterprise Corp",
  primaryBrandColor: "#26D6FF",
  customIcons: {
    search: {
      builtIn: "LuBookOpen",
    },
    close: {
      custom: "https://assets.enterprise.com/icons/close.svg",
    },
    chat: {
      builtIn: "LuMessageSquare",
    },
  },
};

You can see the Custom Icons guide for more information.

URL Parameters

Configure URL parameters that will be automatically appended to all links within the widget. This is useful for tracking and maintaining context across page navigations.

type URLParametersConfig = {
  urlQueryParamsToAppend?: {
    [key: string]: string | number | boolean;
  };
};

Property	Type	Required	Description
`urlQueryParamsToAppend`	`object`	No	URL parameters to append to links

// Basic URL parameters configuration
const baseSettings: InkeepBaseSettings = {
  urlQueryParamsToAppend: {
    utm_source: "widget",
    user_id: "123",
  },
};
 
// Advanced URL parameters configuration
const enterpriseSettings: InkeepBaseSettings = {
  urlQueryParamsToAppend: {
    utm_source: window.location.hostname,
    utm_medium: "widget",
    user_id: getUserId(),
    team_id: getTeamId(),
    features: getEnabledFeatures().join(","),
    session: getSessionId(),
  },
};

Source Transformation

See the Source Transformation guide for more information on how to customize how source information is displayed in the search and chat results.

Custom Filters

See the Search and Chat Filters guide for more information on how to use filters to dynamically filter search and chat results.

export interface SearchAndChatFilters {
  attributes?: {
    [key: string]: any;
  };
}

On this page