); }; ``` ### With AI Chat Settings ```tsx const App = () => { const config: InkeepSidebarChatProps = { // ... other config aiChatSettings: { aiAssistantName: "Support Assistant", introMessage: "👋 Hi! How can I help you today?", }, }; return (

); }; ``` ### Controlled Open State ```tsx import { useState } from "react"; const App = () => { const [isOpen, setIsOpen] = useState(false); const config: InkeepSidebarChatProps = { // ... other config isOpen, onOpenChange: setIsOpen, }; return (

); }; ``` ### Accessing Component Methods The `aiChatSettings` config accepts a `chatFunctionsRef` prop that allows you to access the chat methods. ```tsx const App = () => { import type { AIChatFunctions } from "@inkeep/cxkit-types"; const chatFunctionsRef = useRef(null); const config: InkeepSidebarChatProps = { // ... other config aiChatSettings: { chatFunctionsRef, }, }; const clearChat = () => { chatFunctionsRef.current?.clearChat(); }; const submitMessage = () => { chatFunctionsRef.current?.submitMessage("Hello!"); }; return (

); }; ``` | Method | Description | | -------------------------------------- | ----------------------------------------------------------------------------------------------- | | `submitMessage(message?: string)` | Programmatically sends a message in chat. If message is omitted, sends the current input value. | | `updateInputMessage(message: string)` | Updates the text in chat input field | | `clearChat()` | Resets the chat to its initial state | | `openForm(formSettings: FormSettings)` | Displays a form overlay in chat interface | | `focusInput()` | Sets focus to the chat input field | Refer to the [Form Settings](/ui-components/common-settings/actions#formconfig-reference) reference docs for more details on the available properties for the `openForm` method. ## FAQ If you use a `webpack` build. You could come across this error. To fix this you need to create a custom loader for your webpack configuration to disable this behavior. > Since webpack 5.0.0-beta.30, you're required to specify extensions when > using imports in .mjs files or any .js files with a package.json with "type": > "module". You can still disable the behavior with resolve.fullySpecified set > to false if you see any related errors in your project. We can add a new rule to our webpack configuration to disable this behavior. ```js module.exports = { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; ``` Then add this to your `webpack.config.js` file. If you use docusaurus, you can add this to your `docusaurus.config.js` file as a `webpack` config override with plugins. ```js /** @type {import('@docusaurus/types').Config} */ const config = { // ... plugins: [ () => { return { name: "loader", configureWebpack() { return { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; }, }; }, ], // ... }; module.exports = config; ``` *** title: Embedded Chat (React) sidebarTitle: Embedded Chat description: Add a chat UI directly on a dedicated React powered page. keywords: embedded chat, React chat component, chat UI, chat implementation, React integration, chat functionality, component methods, chat configuration, UI customization, chat settings, chat interface, React hooks, chat automation, component props, chat features ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ## Overview An "embedded chat" is a chat UI that is directly incorporated into a page instead of within a pop-up modal. ## Scenarios You may want to add an embedded chat in places where you want to encourage the user to interact with the AI chat directly. For example, an embedded chat can be useful to: * Deflect questions in your help center site * Provide an AI chat experience if your documentation site doesn't allow third party components, like for GitBook and ReadMe. * Create a place for sharable chat sessions You can incorporate the embedded chat directly on an existing page like `help.domain.com` or create a dedicated one like `domain.com/ask-ai`. ## Quick Start ### Install the component library ```bash npm install @inkeep/cxkit-react ``` ```bash bun add @inkeep/cxkit-react ``` ```bash pnpm add @inkeep/cxkit-react ``` ```bash yarn add @inkeep/cxkit-react ``` ### Define the component ```tsx import { InkeepEmbeddedChat, type InkeepEmbeddedChatProps, } from "@inkeep/cxkit-react"; const config: InkeepEmbeddedChatProps = { baseSettings: { apiKey: "YOUR_API_KEY", }, aiChatSettings: { aiAssistantName: "Keepie", }, }; const App = () => { return ; }; ``` ## Embedded Chat Props This type represents the configuration for the Inkeep embedded chat widget. | Prop | Type | Required | Description | | ---------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `baseSettings` | `object` | Yes | Core configuration settings. See [Base Settings](/ui-components/common-settings/base) for details. | | `aiChatSettings` | `object` | No | AI chat configuration settings. See [AI Chat Settings](/ui-components/common-settings/ai-chat) for details. | | `isHidden` | `boolean` | No | Whether to hide the chat interface. Defaults to false. | | `shouldAutoFocusInput` | `boolean` | No | Whether to auto focus the input. Defaults to true. | ## Examples ### Auto Focus Input ```tsx const App = () => { const config: InkeepEmbeddedChatProps = { // ... other config shouldAutoFocusInput: true, }; return ; }; ``` ### With AI Chat Settings ```tsx const App = () => { const config: InkeepEmbeddedChatProps = { // ... other config aiChatSettings: { aiAssistantName: "Support Assistant", introMessage: "👋 Hi! How can I help you today?", }, }; return ; }; ``` ### Accessing Component Methods The `aiChatSettings` config accepts a `chatFunctionsRef` prop that allows you to access the chat methods. ```tsx const App = () => { import type { AIChatFunctions } from "@inkeep/cxkit-types"; const chatFunctionsRef = useRef(null); const config: InkeepEmbeddedChatProps = { // ... other config aiChatSettings: { chatFunctionsRef, }, }; const clearChat = () => { chatFunctionsRef.current?.clearChat(); }; const submitMessage = () => { chatFunctionsRef.current?.submitMessage("Hello!"); }; return ( <> ); }; ``` | Method | Description | | -------------------------------------- | ----------------------------------------------------------------------------------------------- | | `submitMessage(message?: string)` | Programmatically sends a message in chat. If message is omitted, sends the current input value. | | `updateInputMessage(message: string)` | Updates the text in chat input field | | `clearChat()` | Resets the chat to its initial state | | `openForm(formSettings: FormSettings)` | Displays a form overlay in chat interface | | `focusInput()` | Sets focus to the chat input field | Refer to the [Form Settings](/ui-components/common-settings/actions#formconfig-reference) reference docs for more details on the available properties for the `openForm` method. ## FAQ If you use a `webpack` build. You could come across this error. To fix this you need to create a custom loader for your webpack configuration to disable this behavior. > Since webpack 5.0.0-beta.30, you're required to specify extensions when > using imports in .mjs files or any .js files with a package.json with "type": > "module". You can still disable the behavior with resolve.fullySpecified set > to false if you see any related errors in your project. We can add a new rule to our webpack configuration to disable this behavior. ```js module.exports = { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; ``` Then add this to your `webpack.config.js` file. If you use docusaurus, you can add this to your `docusaurus.config.js` file as a `webpack` config override with plugins. ```js /** @type {import('@docusaurus/types').Config} */ const config = { // ... plugins: [ () => { return { name: "loader", configureWebpack() { return { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; }, }; }, ], // ... }; module.exports = config; ``` *** title: Embedded Search (React) sidebarTitle: Embedded Search description: Add a search UI directly on a dedicated React powered page. keywords: embedded search, React search component, search UI, search implementation, React integration, search functionality, component methods, search configuration, UI customization, search settings, search interface, React hooks, search automation, component props, search features -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Overview An "embedded search" is a search UI that is directly incorporated into a page instead of within a pop-up modal. ## Quick Start ### Install the component library ```bash npm install @inkeep/cxkit-react ``` ```bash bun add @inkeep/cxkit-react ``` ```bash pnpm add @inkeep/cxkit-react ``` ```bash yarn add @inkeep/cxkit-react ``` ### Define the component ```tsx import { InkeepEmbeddedSearch, type InkeepEmbeddedSearchProps, } from "@inkeep/cxkit-react"; const config: InkeepEmbeddedSearchProps = { baseSettings: { apiKey: "YOUR_API_KEY", }, searchSettings: { placeholder: "Search...", }, }; const App = () => { return ; }; ``` ## Embedded Search Props This type represents the configuration for the Inkeep embedded search widget. | Prop | Type | Required | Description | | ---------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- | | `baseSettings` | `object` | Yes | Core configuration settings. See [Base Settings](/ui-components/common-settings/base) for details. | | `searchSettings` | `object` | No | Search configuration settings. See [Search Settings](/ui-components/common-settings/search) for details. | | `isHidden` | `boolean` | No | Whether to hide the search interface. Defaults to false. | | `shouldAutoFocusInput` | `boolean` | No | Whether to auto focus the input. Defaults to true. | ## Examples ### Auto Focus Input ```tsx const App = () => { const config: InkeepEmbeddedSearchProps = { // ... other config shouldAutoFocusInput: true, }; return ; }; ``` ### With Search Settings ```tsx const App = () => { const config: InkeepEmbeddedSearchProps = { // ... other config searchSettings: { placeholder: "Search...", debounceTimeMs: 300, }, }; return ; }; ``` ### Accessing Component Methods The `searchSettings` config accepts a `searchFunctionsRef` prop that allows you to access the search methods. ```tsx const App = () => { import type { SearchFunctions } from "@inkeep/cxkit-types"; const searchFunctionsRef = useRef(null); const config: InkeepEmbeddedSearchProps = { // ... other config searchSettings: { searchFunctionsRef, }, }; const updateQuery = () => { searchFunctionsRef.current?.updateQuery("Hello!"); }; const focusInput = () => { searchFunctionsRef.current?.focusInput(); }; return ( <> ); }; ``` | Method | Description | | ---------------------------- | ------------------------------------------ | | `updateQuery(query: string)` | Programmatically updates the search query. | | `focusInput()` | Sets focus to the search input field | ## FAQ If you use a `webpack` build. You could come across this error. To fix this you need to create a custom loader for your webpack configuration to disable this behavior. > Since webpack 5.0.0-beta.30, you're required to specify extensions when > using imports in .mjs files or any .js files with a package.json with "type": > "module". You can still disable the behavior with resolve.fullySpecified set > to false if you see any related errors in your project. We can add a new rule to our webpack configuration to disable this behavior. ```js module.exports = { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; ``` Then add this to your `webpack.config.js` file. If you use docusaurus, you can add this to your `docusaurus.config.js` file as a `webpack` config override with plugins. ```js /** @type {import('@docusaurus/types').Config} */ const config = { // ... plugins: [ () => { return { name: "loader", configureWebpack() { return { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; }, }; }, ], // ... }; module.exports = config; ``` *** title: Embedded Search and Chat (React) sidebarTitle: Embedded Search and Chat description: Add a toggle-able search and chat UI directly on a dedicated page keywords: embedded search and chat, React components, combined UI, search functionality, chat interface, component integration, UI customization, React implementation, search settings, chat configuration, component methods, React hooks, UI toggling, search and chat features, component props --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Overview This is a toggleable chat / search UI that is directly incorporated into a page instead of within a pop-up modal. It's a combination of the [Embedded Chat](/ui-components/js-snippet/in-page/embedded-chat) and the [Embedded Search](/ui-components/js-snippet/in-page/embedded-search) components, allowing you to toggle between chat and search. ## Quick Start ### Install the component library ```bash npm install @inkeep/cxkit-react ``` ```bash bun add @inkeep/cxkit-react ``` ```bash pnpm add @inkeep/cxkit-react ``` ```bash yarn add @inkeep/cxkit-react ``` ### Define the component ```tsx import { InkeepEmbeddedSearchAndChat, type InkeepEmbeddedSearchAndChatProps, } from "@inkeep/cxkit-react"; const config: InkeepEmbeddedSearchAndChatProps = { baseSettings: { apiKey: "YOUR_API_KEY", }, aiChatSettings: { aiAssistantName: "Keepie", }, searchSettings: { placeholder: "Search...", }, }; const App = () => { return ; }; ``` ## Embedded Search Props This type represents the configuration for the Inkeep embedded search widget. | Prop | Type | Required | Description | | ---------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------- | | `baseSettings` | `object` | Yes | Core configuration settings. See [Base Settings](/ui-components/common-settings/base) for details. | | `searchSettings` | `object` | No | Search configuration settings. See [Search Settings](/ui-components/common-settings/search) for details. | | `isHidden` | `boolean` | No | Whether to hide the search interface. Defaults to false. | | `shouldAutoFocusInput` | `boolean` | No | Whether to auto focus the input. Defaults to true. | | `askAICardLabel` | `string` | No | The label for the Ask AI card in search results. Defaults to `Ask AI` or `askAILabel` if provided. | | `askAILabel` | `string` | No | The label for the Ask AI button in the search/chat toggle. Defaults to `Ask AI`. | | `searchLabel` | `string` | No | The label for the search button in the search/chat toggle. Defaults to `Search`. | ## Examples ### Set the default view ```tsx const App = () => { const config: InkeepEmbeddedSearchAndChatProps = { // ... other config defaultView: "chat", // or "search" }; return ; }; ``` ### Force the default view If you want to force the default view to be the search or the chat, you can use the `forceDefaultView` property. This is useful to ensure the widget always opens the defaultView instead of last used view. ```tsx const App = () => { const config: InkeepEmbeddedSearchAndChatProps = { // ... other config forceDefaultView: true, }; return ; }; ``` Refer to the [Search Settings](/ui-components/common-settings/search) and [Chat Settings](/ui-components/common-settings/chat) docs for more details on the available properties. ## Accessing Component Methods Exactly how you'd do it in the [Embedded Search](/ui-components/react/in-page/embedded-search#accessing-component-methods) and [Embedded Chat](/ui-components/react/in-page/embedded-chat#accessing-component-methods) components respectively. ```tsx const App = () => { import type { SearchFunctions } from "@inkeep/cxkit-types"; const searchFunctionsRef = useRef(null); const chatFunctionsRef = useRef(null); const config: InkeepEmbeddedSearchAndChatProps = { // ... other config searchSettings: { searchFunctionsRef, }, aiChatSettings: { chatFunctionsRef, }, }; const updateSearchQuery = () => { searchFunctionsRef.current?.updateQuery("Hello!"); }; const clearChat = () => { chatFunctionsRef.current?.clearChat(); }; return ( <> ); }; ``` ### Chat Methods | Method | Description | | -------------------------------------- | ----------------------------------------------------------------------------------------------- | | `submitMessage(message?: string)` | Programmatically sends a message in chat. If message is omitted, sends the current input value. | | `updateInputMessage(message: string)` | Updates the text in chat input field | | `clearChat()` | Resets the chat to its initial state | | `openForm(formSettings: FormSettings)` | Displays a form overlay in chat interface | | `focusInput()` | Sets focus to the chat input field | Refer to the [Form Settings](/ui-components/common-settings/actions#formconfig-reference) reference docs for more details on the available properties for the `openForm` method. ### Search methods | Method | Description | | ---------------------------- | ------------------------------------------ | | `updateQuery(query: string)` | Programmatically updates the search query. | | `focusInput()` | Sets focus to the search input field | ### Widget methods ```typescript type ModalViewTypes = "search" | "chat"; ``` | Method | Description | | ------------------------------- | --------------------------------------------------- | | `setView(view: ModalViewTypes)` | Set the view of the widget to either search or chat | ## FAQ If you use a `webpack` build. You could come across this error. To fix this you need to create a custom loader for your webpack configuration to disable this behavior. > Since webpack 5.0.0-beta.30, you're required to specify extensions when > using imports in .mjs files or any .js files with a package.json with "type": > "module". You can still disable the behavior with resolve.fullySpecified set > to false if you see any related errors in your project. We can add a new rule to our webpack configuration to disable this behavior. ```js module.exports = { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; ``` Then add this to your `webpack.config.js` file. If you use docusaurus, you can add this to your `docusaurus.config.js` file as a `webpack` config override with plugins. ```js /** @type {import('@docusaurus/types').Config} */ const config = { // ... plugins: [ () => { return { name: "loader", configureWebpack() { return { module: { rules: [ { test: /\.m?js/, resolve: { fullySpecified: false, }, }, ], }, }; }, }; }, ], // ... }; module.exports = config; ``` *** title: Base Settings sidebarTitle: Base description: Review the basic configuration settings for our widgets. keywords: base configuration, widget settings, core settings, user properties, privacy settings, event handling, widget customization, authentication settings, branding configuration, theme settings, analytics configuration, user identification, widget setup, configuration options ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The base configuration provides core settings for all Inkeep widgets. These settings control authentication, branding, theming, and general behavior. ## Basic Configuration ```typescript 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 baseSettings: 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(), analyticsProperties: { url: window.location.href, }, 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 that is logged to the Inkeep Analytics system. This allows you to filter chat sessions by these properties in the Inkeep Dashboard or export the analytics data using the [Analytics API](/analytics-api/add-analytics-to-any-chat). ```typescript 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 | ```typescript // Basic user configuration const baseSettings: InkeepBaseSettings = { userProperties: { id: "user-123", email: "user@example.com", name: "John Doe", }, }; // Advanced user configuration const baseSettings: 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. ```typescript 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 | ```typescript // Basic analytics configuration const baseSettings: InkeepBaseSettings = { // ... privacyPreferences: { optOutAnalyticalCookies: false, optOutAllAnalytics: false, optOutFunctionalCookies: false, }, }; // Privacy-focused configuration const baseSettings: 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. ```typescript 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 | | `analyticsProperties` | `Record` | No | Additional properties to send to analytics | ```typescript // 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](/ui-components/customization-guides/use-your-own-analytics) guide for more information. ### Color Mode Synchronize the widget's appearance with your application's theme. This enables seamless dark/light mode integration. ```typescript interface ColorMode { // ... sync?: { target: HTMLElement | string; attributes: string[]; isDarkMode: (attributes: Record) => boolean; onChange?: (colorMode: string) => void; }; } ``` | Property | Type | Required | Description | | ----------- | ----------- | -------- | ----------------------------------- | | `colorMode` | `ColorMode` | No | Theme synchronization configuration | ```typescript // 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. ```typescript interface UserTheme { // ... syntaxHighlighter?: { lightTheme?: any; darkTheme?: any; }; primaryColors?: PrimaryColors; varsClassName?: string; styles?: Array<{ key: string; type: "link" | "style"; value: string; }>; disableLoadingDefaultFont?: boolean; } ``` | Property | Type | Required | Description | | -------- | ----------- | -------- | ---------------------------- | | `theme` | `UserTheme` | No | Theme customization settings | ```typescript // 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 baseSettings: 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](/ui-components/customization-guides/style-components) 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. ```typescript 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 | ```typescript 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](/ui-components/customization-guides/style-components#available-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. ```typescript type URLParametersConfig = { urlQueryParamsToAppend?: { [key: string]: string | number | boolean; }; }; ``` | Property | Type | Required | Description | | ------------------------ | -------- | -------- | --------------------------------- | | `urlQueryParamsToAppend` | `object` | No | URL parameters to append to links | ```typescript // Basic URL parameters configuration const baseSettings: InkeepBaseSettings = { urlQueryParamsToAppend: { utm_source: "widget", user_id: "123", }, }; // Advanced URL parameters configuration const baseSettings: 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](/ui-components/customization-guides/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](/ui-components/customization-guides/filters) guide for more information on how to use filters to dynamically filter search and chat results. ```typescript export interface SearchAndChatFilters { attributes?: { [key: string]: any; }; } ``` *** title: Search Settings sidebarTitle: Search description: Customize search-related settings for the Inkeep widgets. keywords: search configuration, search settings, search customization, search behavior, search interface, search results, search tabs, search events, search functionality, search appearance, search parameters, search options, search implementation, search features ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The search configuration provides settings for all search-related components, including search behavior, appearance, and functionality. These settings allow you to customize how users interact with the search interface, how results are displayed, and how the search behavior works. ## Basic Configuration ```typescript // Basic search configuration const searchSettings: InkeepSearchSettings = { placeholder: "Search documentation...", defaultQuery: "", maxResults: 40, debounceTimeMs: 300, shouldOpenLinksInNewTab: true, }; // Advanced configuration with analytics and customization const searchSettings: InkeepSearchSettings = { placeholder: "Search our docs, GitHub, and community...", defaultQuery: new URLSearchParams(window.location.search).get("q") || "", maxResults: 50, debounceTimeMs: 250, shouldOpenLinksInNewTab: true, searchQueryParamKey: "search", onQueryChange: (query) => { analytics.track("search_query", { query }); updateURLParams(query); }, tabs: ["Publications", ["GitHub", { isAlwaysVisible: true }], "Forums"], }; ``` ## Core Settings Configure basic search behavior and appearance: | Option | Type | Default | Description | | ------------------------- | ------------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `placeholder` | `string` | `'Search anything...'` (desktop), `'Search'` (mobile) | Text shown in empty search input | | `defaultQuery` | `string` | `''` | Initial search query on load | | `maxResults` | `number` | `40` | Maximum number of results to show | | `debounceTimeMs` | `number` | `0` | Milliseconds to wait before searching | | `shouldOpenLinksInNewTab` | `boolean` | `false` | Open results in new tab | | `searchQueryParamKey` | `string` | `null` | URL parameter for search query; gets appended to the URL when a result is clicked | | `view` | `"single-pane" \| "dual-pane"` | `"single-pane"` | Whether to render the search results in a single list or a two pane view with a list of results on the left and a preview of the content on the right | ```typescript const searchSettings: InkeepSearchSettings = { // ... placeholder: "Search documentation...", defaultQuery: "", maxResults: 40, debounceTimeMs: 300, shouldOpenLinksInNewTab: true, searchQueryParamKey: "q", }; ``` ## Search Tabs Configure result categorization and organization: ```typescript interface SearchTab { [0]: string; [1]: { isAlwaysVisible?: boolean; }; } ``` | Option | Type | Required | Description | | ------ | ------------------------- | -------- | -------------------------- | | `tabs` | `(string \| SearchTab)[]` | No | Tabs to display in results | The tabs feature supports several configuration patterns: ```typescript const searchSettings: InkeepSearchSettings = { // Basic tabs tabs: ["All", "Publications", "GitHub", "Forums"], // With always visible option tabs: [ "All", "Publications", ["GitHub", { isAlwaysVisible: true }], "Forums", ], // Hide "All" tab, show only Publications and GitHub tabs: ["Publications", "GitHub"], // No tabs (just show all results) tabs: [], }; ``` Default tabs if none provided: * `All` * `Publications` * `PDFs` * `GitHub` * `Forums` * `Discord` * `Slack` * `StackOverflow` > The tabs are displayed in the order they are provided in the `tabs` array. ## Event Handling Configure search event callbacks: | Option | Type | Required | Description | | --------------- | ------------------------- | -------- | -------------------------------- | | `onQueryChange` | `(query: string) => void` | No | Called when search query changes | ```typescript const searchSettings: InkeepSearchSettings = { // ... onQueryChange: (query) => { // Maybe Update URL const url = new URL(window.location.href); url.searchParams.set("q", query); window.history.replaceState({}, "", url); }, }; ``` *** title: AI Assistant Settings sidebarTitle: AI Chat description: Customize the chat experience for the Inkeep widgets. keywords: AI chat settings, chat customization, AI assistant configuration, chat interface, chat features, example questions, chat sharing, chat disclaimers, help actions, chat appearance, chat personalization, chat UI, chat tools, chat workflows, chat integration, chat experience ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Settings for Inkeep's AI-powered chat features, including AI assistant's personality, workflows, tools, and UI customization. ## Basic Configuration ```typescript // Basic chat configuration const aiChatSettings: InkeepAIChatSettings = { // ... aiAssistantName: 'Keepie', chatSubjectName: 'Inkeep', placeholder: 'Ask me anything about our API...', introMessage: '👋 Hi! I'm here to help you with technical questions...', isShareButtonVisible: true, isCopyChatButtonVisible: true } // Advanced configuration with personalization const aiChatSettings: InkeepAIChatSettings = { // ... aiAssistantName: 'Atlas Assistant', chatSubjectName: 'MongoDB Atlas', placeholder: 'How do I get started?', introMessage: `How can I help you today?`, aiAssistantAvatar: '/assets/assistant-light.png', userAvatar: userProfile.avatarUrl, exampleQuestions: [ 'How do I connect to my cluster?', 'What are the instance sizes?', 'How do I enable backups?' ], disclaimerSettings: { isEnabled: true, label: 'AI Assistant', tooltip: 'Responses are AI-generated and may require verification.' }, toolbarButtonLabels: { clear: 'Start Over', share: 'Share Chat', getHelp: 'Get Help', stop: 'Stop', copyChat: 'Copy Chat' } } ``` ## AI Assistant Settings Configure the AI assistant's personality and appearance: | Option | Type | Required | Description | | ------------------- | ------------------------------------------- | -------- | --------------------------------------------------- | | `aiAssistantName` | `string` | No | Display name for the AI assistant | | `chatSubjectName` | `string` | No | Topic/product the assistant specializes in | | `placeholder` | `string` | No | Input field placeholder text | | `introMessage` | `string` | No | Welcome message (supports markdown) | | `aiAssistantAvatar` | `string \| { light: string, dark: string }` | No | URL for AI assistant's avatar (40x40px recommended) | | `userAvatar` | `string` | No | URL for user's avatar image | ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... aiAssistantName: "Atlas Assistant", chatSubjectName: "MongoDB Atlas", placeholder: "Ask me about MongoDB Atlas...", introMessage: `Welcome back ${userName}! How can I help you today?`, aiAssistantAvatar: { light: "/assets/assistant-light.png", dark: "/assets/assistant-dark.png", }, userAvatar: userProfile.avatarUrl, }; ``` ## Example Questions Configure suggested questions for users to quickly start conversations: | Option | Type | Required | Description | | ----------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------ | | `exampleQuestions` | `string[]` | No | Pre-defined questions for quick access | | `exampleQuestionsLabel` | `string` | No | Custom heading for example questions section | | `isFirstExampleQuestionHighlighted` | `boolean` | No | Emphasize the first question; useful for highlighting the most common question | ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... exampleQuestions: [ "How do I connect to my cluster?", "What are the instance sizes?", "How do I enable backups?", ], exampleQuestionsLabel: "Popular Questions", isFirstExampleQuestionHighlighted: true, }; ``` ## Chat Features Control chat sharing and interaction options: | Option | Type | Required | Description | | ------------------------- | --------- | -------- | --------------------------------- | | `isShareButtonVisible` | `boolean` | No | Enable chat sharing functionality | | `shareChatUrlBasePath` | `string` | No | Base URL for shared chats | | `isCopyChatButtonVisible` | `boolean` | No | Show copy chat button | | `shouldOpenLinksInNewTab` | `boolean` | No | Open links in new tab | | `isViewOnly` | `boolean` | No | Prevent sending new messages | | `chatId` | `string` | No | Load specific chat session | ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... isShareButtonVisible: true, shareChatUrlBasePath: "/shared-chats", isCopyChatButtonVisible: true, shouldOpenLinksInNewTab: true, }; ``` ## Disclaimer Settings Configure AI usage disclaimers: | Option | Type | Required | Description | | -------------------- | -------------------------- | -------- | --------------------------------- | | `disclaimerSettings` | `AIChatDisclaimerSettings` | No | AI usage disclaimer configuration | ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... disclaimerSettings: { isEnabled: true, label: "AI Assistant", tooltip: "Responses are AI-generated and may require verification.", }, }; ``` ## Help Actions You can display buttons or links that lead to your desired support channels at the bottom right of the chat experience:

These can be used to open a link, trigger a create ticket form, or transfer to live chat. | Option | Type | Required | Description | | ---------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `getHelpOptions` | `GetHelpOption[]` | No | Configuration for the possible support channels and the actions that they trigger when clicked by a user. | ### Open Link You can open a link by using the `open_link` action. ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... getHelpOptions: [ { icon: { builtIn: "FaEnvelope" }, name: "Contact Us", isPinnedToToolbar: true, action: { type: "open_link", url: "mailto:support@example.com?subject=Support Request", }, }, { icon: { builtIn: "FaDiscord" }, name: "Ask on Discord", action: { type: "open_link", url: "https://discord.gg/your-discord-invite", }, }, ], }; ``` ### Open Form You can also open a support form by using the `open_form` action. More details on how to create a form can be found on the [form settings page](/ui-components/customization-guides/embed-form-in-chat). ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... getHelpOptions: [ { icon: { builtIn: "FaDiscord" }, name: "Create Support Ticket", action: { type: "open_form", formSettings: { // ... form settings }, }, }, ], }; ``` ### Invoke Callback Use a javascript callback to trigger any other action like opening your own support form or opening your live chat. ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... getHelpOptions: [ { icon: { builtIn: "FaEnvelope" }, name: "Contact Us", type: "invoke_callback", callback: ({ conversation }) => { console.log("Chat conversation:", conversation); // Handle callback }, shouldCloseModal: true, // Optional: controls whether to close the modal after callback }, ], }; ``` See [Actions](/ui-components/common-settings/actions#support-actions) for complete examples. If you want to pin a certain getHelpOption to always display as a standalone button in the toolbar, set `isPinnedToToolbar` to `true`. ## Tools Configure custom tools for the AI assistant: | Option | Type | Required | Description | | ------------ | --------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------- | | `getTools` | `getTools: (ctx: ToolContext) => ToolFunction[]` | No | Custom tools for the AI assistant | | `onToolCall` | `(toolCall: FunctionToolCallArgumentsDoneEvent, ctx: ToolContext) => void \| unknown \| Promise` | No | Callback function triggered whenever the AI uses a tool. | See [Tools](/ui-components/tools/overview) for more details on tools ## Tool Bar Button Labels Customize the buttons displayed in the bottom right of the AI chat: | Option | Type | Required | Description | | --------------------- | --------------------------- | -------- | ------------------------ | | `toolbarButtonLabels` | `AIChatToolbarButtonLabels` | No | Custom button label text | ```typescript const aiChatSettings: InkeepAIChatSettings = { // ... toolbarButtonLabels: { clear: "Start Over", share: "Share Chat", getHelp: "Get Help", stop: "Stop", copyChat: "Copy Chat", }, }; ``` ## Prompts Provide additional context or instructions for the AI assistant. `prompts` apply to the entire chat session, not just the first message. | Option | Type | Required | Description | | --------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompts` | `string[]` | No | System-level instructions that guide the AI's behavior and responses. Use these to define the assistant's personality, knowledge boundaries, and response style. | ### Add user context Contextual prompts can be used to provide additional details about the user that might be helpful information for the AI assistant to consider while answering. Often, this is used to dynamically provide information about the user that can be inferred by their account (if authenticated to your application) or based on the page they are currently viewing. **Examples** For providing context based on the user: ``` `The user is currently viewing documentation page ${url}.` ``` ``` "The user is new to the platform." // (for user life cycle stages) ``` For providing context based on a product: ``` `The question is about ${product}.` // (for teams with multiple products) ``` ``` "The user is using the cloud hosted version of the application." // (for teams with multiple versions or pricing tiers) ``` ### Add custom rules Prompts can be used to customize or guide the behavior of the AI assistant using instructions in natural langauge. By default, the AI assistanth has sensible defaults for staying on topic, brand-protection, faithfulness to the source content, and other guardrails. However, prompts can be useful to further customizing tone, having the assistant ask more clarifying questions, adding topics it should refuse to answer, or otherwise customizing the exact experience to your scenario. See [Rules & Prompts](/projects/rules-and-prompts) for our recommendations and examples around how to prompt LLMs. *** title: Actions description: Use actions to add custom behavior to the UI Components. keywords: UI actions, custom behavior, action types, URL actions, callback actions, form actions, support actions, action implementation, UI interaction, form handling, action configuration, support integration, action examples, UI customization ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Actions allows you to define interactive flows in your chat interface, such as opening a link, opening an embeded form, or executing custom JavaScript. These actions can be triggered by users, when they click on buttons, or the AI assistant. ## Action Types ### Open URL Action Opens a URL in a new tab or the current window: ```typescript const urlAction: OpenUrlAction = { type: "open_link", url: "https://example.com/docs", }; ``` ### Invoke Callback Action Executes a callback function with optional modal control: ```typescript const callbackAction: InvokeCallbackAction = { type: "invoke_callback", callback: ({ conversation }) => { console.log("Chat conversation:", conversation); // Handle callback }, shouldCloseModal: true, // Optional: controls whether to close the modal after callback }; ``` ### Open Form Action Opens a form dialog with configurable fields and success view:

```typescript const formAction: OpenFormAction = { type: "open_form", formSettings: { heading: "Contact Support", description: "Please fill out the form below", fields: [ { name: "email", label: "Email Address", inputType: "email", isRequired: true, placeholder: "Enter your email", }, { name: "description", label: "Issue Description", inputType: "textarea", isRequired: true, placeholder: "Describe your issue", }, { name: "priority", label: "Priority Level", inputType: "select", items: [ { label: "Low", value: "low" }, { label: "Medium", value: "medium" }, { label: "High", value: "high" }, ], isRequired: true, }, ], buttons: { submit: { label: "Submit Ticket", onSubmit: async ({ values, conversation }) => { // Handle form submission await submitTicket(values); }, }, close: { action: "return_to_chat", }, }, successView: { heading: "Ticket Submitted", message: "We will get back to you shortly", doneButton: { label: "Back to Chat", action: "return_to_chat", }, }, }, }; ``` See [Form Settings](/ui-components/customization-guides/embed-form-in-chat) for a full reference on what can be configured in the form. ## Support Action Examples Below are some examples of common actions used to hand off to your support channels. ### Open Support Page ```typescript const supportPageAction = { icon: { builtIn: "FaQuestionCircle" }, name: "Contact Support", action: { type: "open_link", url: "/support", }, }; ``` ### Email Support ```typescript const emailSupportAction = { icon: { builtIn: "FaEnvelope" }, name: "Email", action: { type: "open_link", url: "mailto:support@example.com?subject=Support Request", }, }; ``` ### Open Support Ticket Form ```typescript const contactFormAction = { icon: { builtIn: "LuUsers" }, name: "Create Support Ticket", action: { type: "open_form", formSettings: { heading: "Contact Support", description: "We'll help you resolve your issue.", fields: [ { label: "Email", name: "email", inputType: "email", isRequired: true, }, { label: "Description", name: "description", inputType: "textarea", isRequired: true, }, { _type: "include_chat_session", label: "Include chat history", defaultValue: true, name: "include_chat_session", }, ], buttons: { submit: { label: "Submit Request", onSubmit: async ({ values, conversation }) => { // Submit support request await submitSupportRequest(values); }, }, }, successView: { heading: "Request Submitted", message: "We'll respond to your inquiry shortly.", doneButton: { label: "Continue Chatting", action: "return_to_chat", }, }, }, }, }; ``` ### Transfer to Live Chat ```typescript const liveChatAction = { icon: { builtIn: "FaComment" }, name: "Talk to support", action: { type: "invoke_callback", callback: ({ conversation }) => { // Switch to live chat. Implementation depends on your live chat provider. switchToLiveChat(conversation); }, }, }; ``` ### Slack Community ```typescript const SlackAction = { icon: { builtIn: "FaSlack" }, name: "Slack Community", action: { type: "open_link", url: "https://join.slack.com/t/your-workspace/shared_invite/your-invite-code", }, }; ``` ### Discord Community ```typescript const discordAction = { icon: { builtIn: "FaDiscord" }, name: "Discord Community", action: { type: "open_link", url: "https://discord.gg/your-invite-code", }, }; ``` *** title: Style Components description: Customize the appearance of Inkeep's UI components. keywords: UI styling, component customization, visual customization, theme configuration, CSS customization, design customization, UI appearance, style configuration, component theming, visual design, UI customization, component styling -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The style configuration provides comprehensive settings for customizing the appearance of Inkeep widgets. This includes theming, typography, spacing, and component-specific styles. ## Theme Configuration The theme configuration is defined through the `UserTheme` interface which extends `Partial`. This allows for deep customization of the widget's appearance. ```typescript import { type InkeepBaseSettings } from "@inkeep/cxkit-types"; const baseSettings: InkeepBaseSettings = { theme: { // Basic color customization primaryColors: { primary: "#26D6FF", secondary: "#6366F1", }, // Syntax highlighter themes syntaxHighlighter: { lightTheme: themes.github, darkTheme: themes.dracula, }, // Custom styles injection 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-ai-chat-message { border-radius: 8px; padding: 12px; } [data-theme='dark'] .ikp-ai-chat-message { background: #2D3748; } `, }, ], // CSS variables container class name varsClassName: "ikp-variables", // Disable loading the default font for the widgets disableLoadingDefaultFont: true, }, }; ``` ### Theme Properties #### Primary Colors The `primaryColors` property allows you to define the color variations used throughout the widget. It accepts the following color options: ```typescript primaryColors: { textBold?: string // Bold text color textSubtle?: string // Subtle text color lighter?: string // Lightest shade light?: string // Light shade lightSubtle?: string // Subtle light shade medium?: string // Medium shade mediumSubtle?: string // Subtle medium shade strong?: string // Strong shade stronger?: string // Stronger shade textColorOnPrimary?: string // Text color on primary background } ``` All colors should be provided as valid CSS color values (hex, rgb, hsl, etc). Each property is optional, allowing you to customize only the specific color variations you need. #### Syntax Highlighter Theme The `syntaxHighlighter` property lets you configure different themes for code blocks in light and dark modes. By default, the Prism syntax highlighting theme we use is [oneLight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/prism-react-renderer/src/themes/oneLight.ts) in light mode and [vsDark](https://github.com/FormidableLabs/prism-react-renderer/blob/master/packages/prism-react-renderer/src/themes/vsDark.ts) in dark mode. To use a different theme, you can provide it in the theme.syntaxHighlighter prop. ```typescript syntaxHighlighter: { lightTheme: themes.github, // Theme for light mode darkTheme: themes.dracula // Theme for dark mode } ``` You can use published Prism themes or [create your own](https://github.com/PrismJS/prism-themes). #### Custom Styles The `styles` property allows injection of custom styles through two methods: 1. External Resources (type: 'link'): ```typescript { key: 'google-fonts', type: 'link', value: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap' } ``` 2. Inline CSS (type: 'style'): ```typescript { key: 'custom-theme', type: 'style', value: ` .ikp-ai-chat-message { border-radius: 8px; padding: 12px; } ` } ``` Each style entry requires: * `key`: A unique identifier to prevent duplicates and enable updates * `type`: Either 'link' for external resources or 'style' for inline CSS * `value`: The style content (URL for links or CSS code for styles) #### Variables Class Name The `varsClassName` property specifies the class name for the container that holds CSS variables: ```typescript varsClassName: "ikp-variables"; // Default value ``` This class is added to a wrapper div that provides theming context. ## Color Mode Configuration The color mode configuration allows you to control how the widget handles light and dark modes. This is configured through the `colorMode` property in the base settings: ```typescript const baseSettings: InkeepBaseSettings = { colorMode: { // Force a specific color mode forcedColorMode?: string, // Enable system color mode detection enableSystem?: boolean, // Sync with external element sync?: { // Element to watch for color mode changes target: HTMLElement | string, // Attributes to monitor attributes: string[], // Function to determine dark mode isDarkMode: (attributes: Record) => boolean, // Optional callback for color mode changes onChange?: (colorMode: string) => void } } } ``` ### Color Mode Properties #### Forced Color Mode Use `forcedColorMode` to explicitly set the color mode for the current page: ```typescript colorMode: { forcedColorMode: "dark"; // Forces dark mode } ``` #### System Color Mode Enable `enableSystem` to automatically switch between dark and light modes based on the user's system preferences: ```typescript colorMode: { enableSystem: true; // Follows system preference } ``` #### Color Mode Sync The `sync` property allows you to synchronize the widget's color mode with your application's theme: ```typescript colorMode: { sync: { // Watch the document root for theme changes target: document.documentElement, // Monitor the data-theme attribute attributes: ['data-theme'], // Determine dark mode based on attribute value isDarkMode: (attrs) => attrs['data-theme'] === 'dark', // Optional: Handle color mode changes onChange: (mode) => console.log(`Color mode changed to: ${mode}`) } } ``` Common sync configurations: 1. **Data Attribute Sync**: ```typescript { target: document.documentElement, attributes: ['data-theme'], isDarkMode: (attrs) => attrs['data-theme'] === 'dark' } ``` 2. **Class-based Sync**: ```typescript { target: document.documentElement, attributes: ['class'], isDarkMode: (attrs) => attrs['class']?.includes('dark-mode') } ``` ## Using CSS Variables Inkeep provides a set of CSS variables that you can use to customize the widget's appearance. These variables are prefixed with `--ikp-` and are available within the scope of the widget. ### Basic Usage You can use Inkeep CSS variables within your stylesheets to customize elements. For example: ```css .ikp-chat-button__button { background: var(--ikp-colors-inkeep-primary-medium); } ``` ### Dark Mode Styling To apply specific styles for dark mode, use the `[data-theme='dark']` attribute selector: ```css [data-theme="dark"] .ikp-chat-button__button { background: #353e52; } ``` ## Style Recipes Here are some common style recipes to help you get started with customizing the Inkeep components. These styles can be added to your custom CSS file or injected directly into the widget using the `styles` property in the `theme` configuration. ### Responsive Search Bar When space is tight on small screens, this will turn your full search bar into a simple search icon — perfect for navigation bars.

```css @media (max-width: 33em) { .ikp-search-bar__button { padding-inline: 7px; } .ikp-search-bar__text { display: none; } .ikp-search-bar__kbd-wrapper { display: none; } } ``` ### Emphasized search bar Make your search bar stand out and feel more noticeable — perfect for when search is central to your app.

```css .ikp-search-bar__button { box-shadow: 0px 2px 4px rgba(23, 23, 23, 0.1); height: 3rem; padding-inline: 1rem; } .ikp-search-bar__kbd-wrapper { border-width: 1px; border-radius: 0.375rem; padding: 0.25rem 0.5rem; border-bottom-width: 3px; } ``` ### Non-floating chat button Places the chat button directly in your app's layout — like a navbar or sidebar — instead of fixed and floating.

```css /* make the chat button not floating */ .ikp-chat-button__container { position: relative; bottom: unset; right: unset; } /* make the button smaller / more subtle */ .ikp-chat-button__button { background: transparent; border-width: 1px; color: var(--ikp-color-gray-800); border-radius: 6px; box-shadow: none; padding: 6px 12px; font-size: 14px; flex-direction: row-reverse; } .ikp-chat-button__button:hover { transform: none !important; background: var(--ikp-color-gray-50); } .ikp-chat-button__avatar-content { margin-right: 6px !important; margin-left: 0 !important; } .ikp-chat-button__avatar-content > svg { width: 16px; height: 16px; --start-color: var(--ikp-color-inkeep-expanded-primary-300) !important; --end-color: var(--ikp-color-inkeep-expanded-primary-700) !important; } [data-theme="dark"] .ikp-chat-button__button { color: var(--ikp-color-gray-dark-50); background: transparent; } [data-theme="dark"] .ikp-chat-button__button:hover { background: var(--ikp-color-white-alpha-200); } [data-theme="dark"] .ikp-chat-button__avatar-content > svg { --start-color: var(--ikp-color-inkeep-expanded-primary-50) !important; --end-color: var(--ikp-color-inkeep-expanded-primary-300) !important; } ``` ### Changing the chat button background color ```css .ikp-chat-button__button { background: var(--ikp-color-inkeep-expanded-primary-600); } /* For dark mode */ [data-theme="dark"] .ikp-chat-button__button { background: var(--ikp-color-inkeep-expanded-primary-400); } ``` ### Subtle sources Make the sources less prominent and in row format.

```css .ikp-ai-chat-message-sources__list { flex-direction: row; gap: 0.5rem; flex-wrap: wrap; } .ikp-ai-chat-message-source-item { padding: 0rem 0.5rem; width: auto; display: flex; height: 1.5rem; border-radius: 6px; } .ikp-ai-chat-message-source-item__breadcrumbs { display: none; } .ikp-ai-chat-message-source-item__title { font-size: 12px; } .ikp-ai-chat-message-source-item__indicator { display: none !important; } .ikp-ai-chat-message-source-item__tag { display: none; } .ikp-ai-chat-message-source-item__icon { flex-shrink: 0; font-size: 12px; } ``` ### Chat Bubble Here is an example of how you can create a chat bubble like experience (similar to Zendesk or Intercom). #### Chat bubble without a header In this example, when the chat bubble is open, the chat button turns into a close button.

```tsx 'use client' import { InkeepEmbeddedChat, type InkeepEmbeddedChatProps } from '@inkeep/cxkit-react' import { useState } from 'react' import { Sparkles, X } from 'lucide-react' // these can be moved to a separate css file const styles = ` .chat-button { position: fixed; bottom: 20px; right: 20px; z-index: 10; background-color: #191919; color: white; border: none; padding: 12px; border-radius: 1000px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.25) 0px 25px 50px -12px; cursor: pointer; font-size: 16px; font-weight: 500; } .chat-button-text { display: flex; flex-direction: row; align-items: center; justify-content: center; gap: 8px; padding: 0 8px; } .chat-wrapper { position: fixed; bottom: 84px; right: 20px; height: 100%; z-index: 10; width: 400px; max-height: min(500px, calc(100% - 104px)); } /* mobile styles */ @media (max-width: 450px) { .chat-wrapper { width: 100vw; max-height: 100vh; top: 0px; left: 0px; bottom: 0px; right: 0px; border-radius: 0px; } } .chat-wrapper-close-button { position: absolute; top: 10px; right: 10px; z-index: 10; cursor: pointer; color: gray; background-color: #ffffffb8; border-radius: 8px; padding: 4px; display: none; @media (max-width: 450px){ display: block; } } ` const styleOverrides = ` .ikp-ai-chat-wrapper{ max-height: 100% !important; height: 100%; } ` const chatProps: InkeepEmbeddedChatProps = { baseSettings: { // rest of the base settings theme: { styles: [ { key: 'ikp-style-overrides', type: 'style', value: styleOverrides, }, ], }, }, // optional ai chat settings } export function ChatBubble() { const [isHidden, setIsHidden] = useState(true) const toggleChat = () => setIsHidden((h) => !h) return ( <> {/* you can move the styles to a separate css file instead of using an inline style tag */}

) } ``` #### Chat bubble with header In this example, the chat bubble includes a header with a close button and when the chat bubble is open, the chat button trigger is hidden

```tsx 'use client' import { InkeepEmbeddedChat, type InkeepEmbeddedChatProps } from '@inkeep/cxkit-react' import { useState } from 'react' import { Sparkles, X } from 'lucide-react' // these can be moved to a separate css file const styles = ` .chat-button { position: fixed; bottom: 20px; right: 20px; z-index: 10; background-color: #191919; color: white; border: none; padding: 12px; border-radius: 1000px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.25) 0px 25px 50px -12px; cursor: pointer; font-size: 16px; font-weight: 500; } .chat-button-text { display: flex; flex-direction: row; align-items: center; justify-content: center; gap: 8px; padding: 0 8px; } .chat-wrapper { position: fixed; bottom: 20px; right: 20px; height: 100%; z-index: 10; width: 400px; max-height: min(500px, calc(100% - 40px)); box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); border-radius: 6px; } /* mobile styles */ @media (max-width: 450px) { .chat-wrapper { width: 100vw; max-height: 100vh; height: 100%; top: 0px; left: 0px; bottom: 0px; right: 0px; border-radius: 0px; } } .chat-wrapper-header { display: flex; flex-direction: row; align-items: center; justify-content: space-between; padding: 8px 16px 8px 20px; background-color: white; color: gray; position: relative; font-size: 14px; border-top-left-radius: 6px; border-top-right-radius: 6px; } [data-theme="dark"] .chat-wrapper-header{ background-color: #191919; } .chat-wrapper-header::after{ content: ''; position: absolute; left: 0; background: linear-gradient(to bottom, white, transparent); width: 100%; bottom: 0px; height: 12px; transform: translateY(100%); z-index: 1; pointer-events: none; } [data-theme="dark"] .chat-wrapper-header::after{ background: linear-gradient(to bottom, #191919, transparent); } .chat-wrapper-close-button { cursor: pointer; color: gray; padding: 4px; background-color: transparent; } ` const styleOverrides = ` .ikp-ai-chat-wrapper{ max-height: 100% !important; height: calc(100% - 40px) !important; box-shadow: none !important; } ` const chatProps: InkeepEmbeddedChatProps = { baseSettings: { // rest of the base settings theme: { styles: [ { key: 'ikp-style-overrides', type: 'style', value: styleOverrides, }, ], }, }, // optional ai chat settings } export function ChatBubble() { const [isHidden, setIsHidden] = useState(true) const toggleChat = () => setIsHidden((h) => !h) return ( <> {/* you can move the styles to a separate css file */}

{isHidden ? ( ) : null}

Ask AI

) } ``` ## Customizing Icons ### AI Assistant Avatar The AI assistant avatar can be customized through the `aiChatSettings` using the `aiAssistantAvatar` property: it's either a string URL or an object to specify light and dark mode avatars: ```typescript aiAssistantAvatar: { light: string; dark?: string; } ``` ### User Avatar The user avatar can be customized using the `userAvatar` property in the `aiChatSettings`. ```typescript import { type InkeepAIChatSettings } from "@inkeep/cxkit-react"; export const aiChatSettings: InkeepAIChatSettings = { aiAssistantAvatar: "http://example.com/assistant-avatar.png", userAvatar: "http://example.com/user-avatar.png", // ...rest of aiChatSettings }; ``` ### Custom Icons You can customize various icons throughout the widget by providing a `customIcons` dictionary in the `baseSettings`. Each icon can be either a built-in icon or a custom SVG/image. #### Available Icons | Icon Name | Description | | ------------------- | -------------------------------------------------------------------------------------------- | | search | Search icon in search bar | | thumbsUp | Thumbs up icon | | thumbsDown | Thumbs down icon | | messageCopy | Copy message icon | | codeCopy | Copy code icon in code header | | openLinkInNewTab | Used on hover in chat citations and search results (when `shouldOpenLinksInNewTab` is true) | | openLinkInSameTab | Used on hover in chat citations and search results (when `shouldOpenLinksInNewTab` is false) | | breadcrumbSeparator | Breadcrumb separator icon | | switchToSearch | Switch to search icon | | switchToChat | Switch to chat icon | | chatSubmit | Chat submit icon | | close | Close icon | | info | Info icon next to the disclaimer and chat mode toggle | | command | Command icon in search bar | #### Example Configuration ```typescript import { type InkeepBaseSettings } from "@inkeep/cxkit-react"; export const baseSettings: InkeepBaseSettings = { customIcons: { // Using a built-in icon search: { builtIn: "IoSearch", }, // Using custom SVG/image URLs thumbsUp: { custom: "/path/to/thumbs-up.svg", }, thumbsDown: { custom: "/path/to/thumbs-down.svg", }, messageCopy: { custom: "/path/to/message-copy.svg", }, codeCopy: { custom: "/path/to/code-copy.svg", }, openLinkInNewTab: { custom: "path/to/open-link-in-new-tab.svg", }, openLinkInSameTab: { custom: "path/to/open-link-in-same-tab.svg", }, breadcrumbSeparator: { custom: "path/to/breadcrumb-separator.svg", }, switchToSearch: { custom: "/path/to/switch-to-search.svg", }, switchToChat: { custom: "/path/to/switch-to-chat.svg", }, chatSubmit: { custom: "/path/to/chat-submit.svg", }, close: { custom: "/path/to/close.svg", }, info: { custom: "/path/to/info.svg", }, command: { custom: "/path/to/command.svg", }, }, // ...rest of baseSettings }; ``` > If the url for a `custom` icon is a `.svg` file it will be rendered as an `` tag. ## Default Theme The default theme includes these core settings: ### Typography ```typescript fontFamily: { heading: "'Space Grotesk', system-ui, sans-serif", body: "'Inter', system-ui, sans-serif", mono: "'Fira Code', monospace", }, fontSize: { '3xs': '0.45rem', '2xs': '0.625rem', xs: '0.75rem', sm: '0.875rem', md: '1rem', lg: '1.125rem', xl: '1.25rem', '2xl': '1.5rem', '3xl': '1.875rem', '4xl': '2.25rem', '5xl': '3rem', '6xl': '3.75rem', '7xl': '4.5rem', '8xl': '6rem', '9xl': '8rem', } ``` ### Z-Index ```typescript zIndex: { hide: -1, auto: 'auto', base: 0, docked: 10, dropdown: 1000, sticky: 1100, banner: 1200, overlay: 1300, modal: 1400, popover: 1500, skipLink: 1600, toast: 1700, tooltip: 1800, } ``` ## Component Class Names All component class names are prefixed with `ikp-`. Here's the complete list of available class names: ### Search Components ```css ikp-ai-search-wrapper ikp-ai-search-root ikp-ai-search-content ikp-ai-search-input-group ikp-ai-search-input-icon ikp-ai-search-input ikp-ai-search-loading ikp-ai-ask-ai-trigger ikp-ai-ask-ai-trigger__icon ikp-ai-ask-ai-trigger__label ikp-ai-ask-ai-trigger__query ikp-ai-ask-ai-trigger__indicator ikp-ai-ask-ai-trigger__indicator-text ikp-ai-search-results ikp-ai-search-results__loading ikp-ai-search-results__empty ikp-ai-search-results__tab-list ikp-ai-search-results__tab ikp-ai-search-results__content ikp-ai-search-results__scroll-area ikp-ai-search-results__scroll-area-viewport ikp-ai-search-results__list ikp-ai-search-results__item ikp-ai-search-results__item-icon ikp-ai-search-results__item-breadcrumbs ikp-ai-search-results__item-breadcrumb-icon ikp-ai-search-results__item-title ikp-ai-search-results__item-tag ikp-ai-search-results__item-description ikp-ai-search-results__item-description-part ikp-ai-search-results__item-indicator ikp-ai-search-results__item-preview ikp-ai-search-results__item-preview__header ikp-ai-search-results__item-preview__heading ikp-ai-search-results__item-preview__title ikp-ai-search-results__item-preview__title__link-icon ikp-ai-search-results__item-preview__breadcrumbs ikp-ai-search-results__item-preview__breadcrumb-icon ikp-ai-search-results__item-preview__body ikp-ai-search-results__item-preview__outline ikp-ai-search-results__item-preview__outline__title ikp-ai-search-results__item-preview__outline__list ikp-ai-search-results__item-preview__outline__item ikp-ai-search-results__item-preview__outline__item-icon ikp-ai-search-results__item-preview__outline__item-text ikp-ai-search-results__item-preview__outline__item-link-icon ikp-ai-search-results__scroll-area-scrollbar ikp-ai-search-results__scroll-area-thumb ikp-ai-search-results__scroll-area-corner ikp-ai-search-footer ikp-ai-search-tagline__container ikp-ai-search-tagline__text ikp-ai-search-tagline__logo ikp-ai-search-tagline__brand-name ``` ### Chat Components ```css ikp-ai-chat-wrapper ikp-ai-chat-conversation-loading ikp-ai-chat-root ikp-ai-chat-header ikp-ai-chat-header__toolbar ikp-ai-chat-header__toolbar-header ikp-ai-chat-header__toolbar-header-wrapper ikp-ai-chat-content ikp-ai-chat-content-scroll-area ikp-ai-chat-content-scroll-area__viewport ikp-ai-chat-content-scroll-area__scrollbar ikp-ai-chat-content-scroll-area__thumb ikp-ai-chat-content-scroll-area__corner ikp-ai-chat-disclaimer ikp-ai-chat-disclaimer-label ikp-ai-chat-disclaimer-trigger ikp-ai-chat-disclaimer-content ikp-ai-chat-disclaimer-text ikp-ai-chat-disclaimer-arrow ikp-ai-chat-example-questions ikp-ai-chat-example-questions-label ikp-ai-chat-example-questions-list ikp-ai-chat-example-question ikp-ai-chat-example-question-button ikp-ai-chat-workflows ikp-ai-chat-workflows-label ikp-ai-chat-workflows-list ikp-ai-chat-workflow ikp-ai-chat-workflow__icon ikp-ai-chat-messages ikp-ai-chat-message-wrapper ikp-ai-chat-message-header ikp-ai-chat-message-loading ikp-ai-chat-message-avatar ikp-ai-chat-message-avatar-fallback ikp-ai-chat-message-avatar-image ikp-ai-chat-message-avatar-content ikp-ai-chat-message-name ikp-ai-chat-message-content-wrapper ikp-ai-chat-message-content ikp-ai-chat-message-attachments ikp-ai-chat-message-attachments__list ikp-ai-chat-message-attachments__item ikp-ai-chat-message-attachments__item-icon ikp-ai-chat-message-attachments__item-title ikp-ai-chat-message-attachments-preview ikp-ai-chat-message-attachments-preview__overlay ikp-ai-chat-message-attachments-preview__content ikp-ai-chat-message-attachments-preview__header ikp-ai-chat-message-attachments-preview__close ikp-ai-chat-message-attachments-preview__body ikp-ai-chat-message ikp-ai-chat-message-toolbar ikp-ai-chat-message-tool-actions ikp-ai-chat-message-tool-action ikp-ai-chat-message-action ikp-ai-chat-message-sources ikp-ai-chat-message-sources__header ikp-ai-chat-message-sources__list ikp-ai-chat-message-source-item ikp-ai-chat-message-source-item__icon ikp-ai-chat-message-source-item__breadcrumbs ikp-ai-chat-message-source-item__breadcrumb ikp-ai-chat-message-source-item__breadcrumb-icon ikp-ai-chat-message-source-item__title ikp-ai-chat-message-source-item__tag ikp-ai-chat-message-source-item__description ikp-ai-chat-message-source-item__description-part ikp-ai-chat-message-source-item__indicator ikp-ai-chat-footer ikp-ai-chat-input__fieldset ikp-ai-chat-input__group ikp-ai-chat-input ikp-ai-chat-input__send-button ikp-ai-chat-input__send-button-icon ikp-ai-chat-attachments-bar ikp-ai-chat-attachments-bar__list ikp-ai-chat-attachments-bar__attachment ikp-ai-chat-attachments-bar__attachment-icon ikp-ai-chat-attachments-bar__attachment-title ikp-ai-chat-attachments-bar__attachment-delete ikp-ai-chat-attachments-bar__actions ikp-ai-chat-attachments-bar__info-tip ikp-ai-chat-attachments-bar__info-tip-icon ikp-ai-chat-attachments-bar__info-tip-arrow ikp-ai-chat-attachments-bar__info-tip-text ikp-ai-chat-attachments-bar__inputs ikp-ai-chat-attachments-bar__input ikp-ai-chat-attachments-bar__input-icon ikp-ai-chat-attachments-bar__modal ikp-ai-chat-attachments-bar__modal-overlay ikp-ai-chat-attachments-bar__modal-content ikp-ai-chat-attachments-bar__modal-header ikp-ai-chat-attachments-bar__modal-close ikp-ai-chat-attachments-bar__modal-body ikp-ai-chat-attachments-bar__modal-heading ikp-ai-chat-attachments-bar__modal-description ikp-ai-chat-attachments-bar__modal-help ikp-ai-chat-attachments-bar__form ikp-ai-chat-attachments-bar__form-title ikp-ai-chat-attachments-bar__form-title-label ikp-ai-chat-attachments-bar__form-title-input ikp-ai-chat-attachments-bar__form-title-error ikp-ai-chat-attachments-bar__form-content ikp-ai-chat-attachments-bar__form-content-label ikp-ai-chat-attachments-bar__form-content-input ikp-ai-chat-attachments-bar__form-content-error ikp-ai-chat-attachments-bar__form-submit-button ikp-ai-chat-action-bar ikp-ai-chat__chat-actions ikp-ai-chat__chat-action ikp-ai-chat__chat-action-label ikp-ai-chat__chat-action-feeback ikp-ai-chat-help-actions ikp-ai-chat-help-action ikp-ai-chat-help-actions__trigger ikp-ai-chat-help-actions__menu ikp-ai-chat-help-actions__menu-arrow ikp-ai-chat-help-actions__menu-item ikp-ai-chat-help-actions_menu-item-icon ikp-ai-chat-tagline__container ikp-ai-chat-tagline__text ikp-ai-chat-tagline__logo ikp-ai-chat-tagline__brand-name ikp-ai-chat-feedback-modal ikp-ai-chat-feedback-modal__overlay ikp-ai-chat-feedback-modal__content ikp-ai-chat-feedback-modal__header ikp-ai-chat-feedback-modal__close ikp-ai-chat-feedback-modal__body ikp-ai-chat-feedback-form ikp-ai-chat-feedback-item ikp-ai-chat-feedback-item__checkbox ikp-ai-chat-feedback-item__checkbox-indicator ikp-ai-chat-feedback-item__label ikp-ai-chat-feedback-item__description ikp-ai-chat-feedback-form__submit-button ikp-ai-chat-form__wrapper ikp-ai-chat-form ikp-ai-chat-form__close ikp-ai-chat-form__header ikp-ai-chat-form__heading ikp-ai-chat-form__description ikp-ai-chat-form__content ikp-ai-chat-form__field ikp-ai-chat-form__field-label ikp-ai-chat-form__field-text ikp-ai-chat-form__field-email ikp-ai-chat-form__field-file ikp-ai-chat-form__field-text-area ikp-ai-chat-form__field-checkbox ikp-ai-chat-form__field-checkbox-indicator ikp-ai-chat-form__field-select ikp-ai-chat-form__field-select__trigger ikp-ai-chat-form__field-select__value ikp-ai-chat-form__field-select__icon ikp-ai-chat-form__field-select__content ikp-ai-chat-form__field-select__viewport ikp-ai-chat-form__field-select__item ikp-ai-chat-form__field-select__item-indicator ikp-ai-chat-form__field-select__item-text ikp-ai-chat-form__field-error ikp-ai-chat-form__error ikp-ai-chat-form__footer ikp-ai-chat-form__cancel ikp-ai-chat-form__submit ikp-ai-chat-form__success ikp-ai-chat-form__success-heading ikp-ai-chat-form__success-message ikp-ai-chat-form__success-button ikp-ai-chat-link ``` ### Markdown Components ```css ikp-codeblock-container ikp-codeblock-header ikp-codeblock-header-language ikp-codeblock-copy-button ikp-codeblock-highlighter-wrapper ikp-codeblock-highlighter ikp-codeblock-code ikp-markdown-h1 ikp-markdown-h2 ikp-markdown-p ikp-markdown-li ikp-markdown-ul ikp-markdown-ol ikp-markdown-link ikp-markdown-source-link ikp-markdown-table ikp-markdown-th ikp-markdown-td ikp-markdown-code ikp-markdown-input ``` ### Form Components ```css ikp-intelligent-form__root ikp-intelligent-form__heading ikp-intelligent-form__content ikp-intelligent-form__content__scroll-area ikp-intelligent-form__content__scroll-area-viewport ikp-intelligent-form__content__scroll-area-scrollbar ikp-intelligent-form__content__scroll-area-thumb ikp-intelligent-form__content__scroll-area-corner ikp-intelligent-form__success ikp-intelligent-form__success-icon ikp-intelligent-form__success-heading ikp-intelligent-form__success-message ikp-intelligent-form__primary-form ikp-intelligent-form__primary-form__description ikp-intelligent-form__primary-form-fields ikp-intelligent-form__primary-form-submit ikp-intelligent-form__field ikp-intelligent-form__field-label ikp-intelligent-form__field-text ikp-intelligent-form__field-email ikp-intelligent-form__field-file ikp-intelligent-form__field-text-area ikp-intelligent-form__field-checkbox ikp-intelligent-form__field-checkbox-indicator ikp-intelligent-form__field-select ikp-intelligent-form__field-select__trigger ikp-intelligent-form__field-select__value ikp-intelligent-form__field-select__icon ikp-intelligent-form__field-select__content ikp-intelligent-form__field-select__viewport ikp-intelligent-form__field-select__item ikp-intelligent-form__field-select__item-indicator ikp-intelligent-form__field-select__item-text ikp-intelligent-form__field-error ikp-intelligent-form__bot-heading ikp-intelligent-form__bot-heading__icon ikp-intelligent-form__bot-heading__name ikp-intelligent-form__loading ikp-intelligent-form__confident-response ikp-intelligent-form__confident-answer ikp-intelligent-form__confident-response-button ikp-intelligent-form__confident-response-button__icon ikp-intelligent-form__confident-response-button__label ikp-intelligent-form__secondary-form ikp-intelligent-form__secondary-form__description ikp-intelligent-form__secondary-form-fields ikp-intelligent-form__secondary-form-submit ikp-intelligent-form__error ikp-intelligent-form__sources ikp-intelligent-form__sources-caption ikp-intelligent-form__sources-list ikp-intelligent-form__source ikp-intelligent-form__source-icon ikp-intelligent-form__source-title ``` ### Search Bar Components ```css ikp-search-bar__container ikp-search-bar__button ikp-search-bar__content-wrapper ikp-search-bar__text ikp-search-bar__icon ikp-search-bar__kbd-wrapper ikp-search-bar__cmd-icon ikp-search-bar__ctrl ikp-search-bar__kbd-shortcut-key ``` ### Modal Components ```css ikp-modal ikp-modal__overlay ikp-modal__content ikp-modal__close ``` ### Chat Button Components ```css ikp-chat-button__text ikp-chat-button__button ikp-chat-button__container ikp-chat-button__avatar-image ikp-chat-button__avatar-content ``` ### Miscellaneous Components ```css ikp-icon ikp-loading-indicator__text ikp-loading-indicator__dots ikp-loading-indicator__dot ikp-view_toggle ikp-view_toggle_button ikp-view_toggle_icon ``` *** title: Add your own analytics description: Use our callback function to log events from the search and chat widgets to your own analytics tool. keywords: custom analytics, event tracking, analytics integration, user tracking, event logging, analytics implementation, callback functions, user properties, privacy settings, analytics configuration, event filtering, analytics tools, data tracking, analytics customization ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Scenario To understand how usage of the Inkeep search or chat affects your business, you may want to log events from the search and chat widgets to your own analytics tool. This could be Mixpanel, Posthog, Amplitude, Segment or other analytics or CDP tools. We expose all the events that we log to our own analytics suite through a callback function called `onEvent` that can be configured in the [baseSettings](/ui-components/common-settings/base) configuration. Below is an example of how to use `onEvent` to log events related to the `assistant_message_received` event to your analytics tool. You can check out the full reference of events by inspecting the `InkeepCallbackEvent` type in the npm package. We recommend you only log the events and properties on the events that you find relevant. ## Implementation Examples ### Basic Implementation ```typescript import { type InkeepCallbackEvent } from "@inkeep/cxkit-types"; const baseSettings = { onEvent: (event: InkeepCallbackEvent) => { // Check if the event type is 'assistant_message_received' if (event.eventName === "assistant_message_received") { const { conversation } = event.properties; // Log to your own analytics tool or CDP. console.log("Response: ", conversation.at(-1).content); } }, }; ``` Find the interface for conversation in the [Get Conversation API](/analytics-api/conversation/get-conversation) doc. ### Advanced Implementation with Event Filtering ```typescript const baseSettings = { onEvent: (event: InkeepCallbackEvent) => { const { eventName, properties, userProperties } = event; // Only track specific events const eventsToTrack = [ "assistant_message_received", "user_message_submitted", "search_query_submitted", ]; if (!eventsToTrack.includes(eventName)) { return; } // Add custom properties const enrichedProperties = { ...properties, environment: process.env.NODE_ENV, timestamp: new Date().toISOString(), // Add user context if available ...(userProperties?.id && { userId: userProperties.id }), ...(userProperties?.teamId && { teamId: userProperties.teamId }), }; // Track with your analytics tool analytics.track(eventName, enrichedProperties); }, }; ``` ### Implementation with Multiple Analytics Tools ```typescript const baseSettings = { onEvent: (event: InkeepCallbackEvent) => { const { eventName, properties } = event; // Track with Segment segment.track(eventName, properties); // Track with Mixpanel mixpanel.track(eventName, properties); }, }; ``` ## Common Properties Every event includes a set of common properties that provide context about the widget and the interaction. These properties are automatically included in the `properties` object of every event: | Property | Type | Description | | ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `widgetLibraryVersion` | `string` | The version of the Inkeep widget library being used | | `componentType` | `string` | The type of widget interaction. Possible values: `'ChatButton'`, `'CustomTrigger'`, `'SearchBar'`, `'EmbeddedChat'`, `'EmbeddedSearch'`, `'EmbeddedSearchAndChat'`, `'IntelligentForm'` | | `tags` | `string[]` | Custom tags passed in the `baseSettings`. These can be used to categorize or filter events | You can also pass additional properties to the analytics api by passing the `analyticsProperties` object in the `baseSettings`. These properties will be merged with the event properties. ### Example with Tags ```typescript const baseSettings = { tags: ["production", "docs-site"], // These tags will be included in all events analyticsProperties: { // Additional properties to send to analytics, these will be merged with the event properties url: window.location.href, }, onEvent: (event: InkeepCallbackEvent) => { const { eventName, properties } = event; console.log(properties.tags); // ['production', 'docs-site'] console.log(properties.widgetLibraryVersion); // e.g., '1.2.3' console.log(properties.componentType); // e.g., 'EmbeddedChat' console.log(properties.url); // e.g., 'https://docs.inkeep.com' analytics.track(eventName, properties); }, }; ``` ### User Properties User properties are exactly what you pass to the `userProperties` in baseSettings. These properties can be used to associate events with specific users or teams. ```typescript const baseSettings = { userProperties: { id: "user-123", teamId: "team-456", role: "admin", // Any other custom user properties }, onEvent: (event: InkeepCallbackEvent) => { const { eventName, properties, userProperties } = event; analytics.track(eventName, { ...properties, user: userProperties, }); }, }; ``` ## Configuration Options ### Privacy Preferences These settings are used to configure the analytics tracking for the widget; passed in the `baseSettings` configuration. | Option | Type | Default | Description | | ------------------------- | --------- | ------- | --------------------------------- | | `optOutAnalyticalCookies` | `boolean` | `false` | Opt out of analytical cookies | | `optOutAllAnalytics` | `boolean` | `false` | Opt out of all analytics tracking | | `optOutFunctionalCookies` | `boolean` | `false` | Opt out of functional cookies | ## Events Reference ### Chat Events | Event Name | Description | Properties | | --------------------------------------- | --------------------------- | --------------------------------------------------------------------------------- | | `assistant_message_received` | Assistant response received | `conversation` | | `user_message_submitted` | User message submitted | `conversation` | | `shared_chat_loaded` | Shared chat loaded | `conversation` | | `assistant_positive_feedback_submitted` | Positive feedback given | `conversation`, `reasons` | | `assistant_negative_feedback_submitted` | Negative feedback given | `conversation`, `reasons` | | `get_help_option_clicked` | Help option selected | `getHelpOption`, `conversation` | | `chat_clear_button_clicked` | Chat cleared | `conversation` | | `chat_share_button_clicked` | Share button clicked | `sharedChatUrl`, `sharedConversationId`, `originalConversationId`, `conversation` | | `assistant_message_copied` | Message copied | `conversation` | | `assistant_code_block_copied` | Code block copied | `conversation`, `language`, `code` | | `assistant_source_item_clicked` | Source item clicked | `conversation`, `link` | | `assistant_message_inline_link_opened` | Message link opened | `title`, `url` | ### Search Events | Event Name | Description | Properties | | -------------------------------- | ----------------------- | ----------------------------- | | `search_result_clicked` | Result clicked | `searchQuery`, `title`, `url` | | `search_query_submitted` | Query submitted | `searchQuery` | | `search_query_response_received` | Search results received | `searchQuery`, `totalResults` | ### Intelligent Form Events | Event Name | Description | Properties | | -------------------------------------------- | ------------------------- | ----------------------------------- | | `intelligent_form_submitted` | Form submitted | `conversation`, `values` | | `intelligent_form_primary_section_submitted` | Primary section submitted | `conversation` | | `intelligent_form_ai_response_provided` | AI response provided | `conversation`, `recordsConsidered` | ### UI Component Events | Event Name | Description | Properties | | -------------- | ------------ | ---------- | | `modal_opened` | Modal opened | | | `modal_closed` | Modal closed | | ## Alternatives Instead of logging events on the client, you can associate Inkeep usage to specific user IDs by providing user identifiers in the `baseSettings.userProperties` [properties](/ui-components/common-settings/base#user-properties). These identifiers can come from an authentication token if you have one, or a distinct ID from your analytics provider. You can then use these IDs to query analytics data using the `query-conversations` endpoint in the [Analytics API](/analytics-api/query/query-conversations). You can then set up a CDC pipeline to export this data into your analytics system and join the information there. This is the recommended approach if you have many integrations across many touchpoints that you want to log to your analytics system. *** title: Embed a form in chat description: Add a form to collect information from users in the chat experience. keywords: form embedding, chat forms, user input forms, form integration, chat customization, form implementation, user data collection, chat interface, form configuration, user interaction, form design, chat forms, interactive forms ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can embed a form directly within the Inkeep AI assistant chat UI. It can be triggered from a ["Contact support" button](/ui-components/common-settings/ai-chat#help-actions) in the bottom right of the chat or as a [dynamic button](/ui-components/tools/escalate-to-support#support-ticket-form) that appears when the AI assistant is not confident in its answer. Use this to create a support ticket in your ticketing platform via a custom callback. The history of the conversation can be included. An example `open_form` action looks like this: ```typescript const formAction: OpenFormAction = { type: "open_form", formSettings: { heading: "Contact Support", description: "Please fill out the form below", fields: [ { name: "email", label: "Email Address", inputType: "email", isRequired: true, placeholder: "Enter your email", }, { name: "description", label: "Issue Description", inputType: "textarea", isRequired: true, placeholder: "Describe your issue", }, { name: "priority", label: "Priority Level", inputType: "select", items: [ { label: "Low", value: "low" }, { label: "Medium", value: "medium" }, { label: "High", value: "high" }, ], isRequired: true, }, ], buttons: { submit: { label: "Submit Ticket", onSubmit: async ({ values, conversation }) => { // Handle form submission await submitTicket(values); }, }, close: { action: "return_to_chat", }, }, successView: { heading: "Ticket Submitted", message: "We will get back to you shortly", doneButton: { label: "Back to Chat", action: "return_to_chat", }, }, }, }; ``` ## FormSettings Reference The `FormSettings` interface provides a comprehensive way to configure forms in your chat interface, through the `open_form` action type. Here's a detailed breakdown of all available options: ### Basic Properties | Property | Type | Required | Description | | ----------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------- | | heading | string | No | The form's title displayed at the top | | description | string | No | Explanatory text shown below the heading | | fields | FormField\[] | Yes | Array of form field configurations | | buttons | FormButtons | Yes | Configuration for form action buttons | | successView | SuccessView | No | Configuration for the success confirmation page. If not provided, the form will close after submission. | ### Field Types Forms support various field types through the `FormField` union type: #### Base Field Properties All field types inherit these base properties: | Property | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------- | | name | string | Yes | Unique identifier for the field | | label | string | Yes | Display label for the field | | isRequired | boolean | No | Whether the field is required | | isHidden | boolean | No | Whether to hide the field | | description | string | No | Help text shown below the field | #### Text Field ```typescript { name: 'name', label: 'Full Name', inputType: 'text', defaultValue?: string, placeholder?: string } ``` #### Email Field ```typescript { name: 'email', label: 'Email Address', inputType: 'email', defaultValue?: string, placeholder?: string } ``` #### Textarea Field ```typescript { name: 'description', label: 'Description', inputType: 'textarea', defaultValue?: string, placeholder?: string } ``` #### Checkbox Field ```typescript { name: 'subscribe', label: 'Subscribe to newsletter', inputType: 'checkbox', defaultValue?: boolean } ``` #### Select Field ```typescript { name: 'category', label: 'Category', inputType: 'select', items: [ { label: 'Option 1', value: 'opt1' }, { label: 'Option 2', value: 'opt2' } ], defaultValue?: string, placeholder?: string } ``` #### File Field ```typescript { name: 'attachment', label: 'Attach File', inputType: 'file' } ``` When using a `file` field in your form, you may need to convert the files to Base64 before sending to your backend or an external API, this can be done by using the following snippet. ```typescript function convertFilesToBase64(files: FileList) { const filesArray = Array.from(files); return Promise.all( filesArray.map((file) => { return new Promise((resolve, reject) => { const reader = new FileReader(); reader.onload = (event) => { const result = (event.target as FileReader).result; const base64Data = result.replace(/^data:.+;base64,/, ""); resolve({ data: base64Data, fileName: file.name, mimeType: file.type, }); }; reader.onerror = (error) => reject(error); reader.readAsDataURL(file); }); }) ); } ``` #### Include Chat Session Field Special field type to include chat history: ```typescript { _type: 'include_chat_session', label?: string, // Defaults to "Include chat history" defaultValue?: boolean, isHidden?: boolean, name: 'include_chat_session', } ``` ### Button Configuration The `buttons` property requires configuration for submit and optional close buttons: ```typescript { buttons: { submit: { label?: string, // Optional custom label onSubmit: async ({ values, conversation }) => { // Handle form submission // values: Record - form field values // conversation: ConversationResponse | null } }, close?: { action: 'return_to_chat' | 'close_modal' } } } ``` ### Success View Configuration The `successView` property configures what's shown after successful submission, if not provided, the form will close after submission. ```typescript { successView: { heading: string, // Success message heading message: string, // Detailed success message doneButton: { label: string, // Button text icon?: InkeepCustomIcon, // Optional icon action: 'return_to_chat' | 'close_modal' } } } ``` ### Complete Example Here's a comprehensive example showing all available configurations: ```typescript const formSettings: FormSettings = { heading: "Submit Support Request", description: "Please provide details about your issue", fields: [ { name: "name", label: "Full Name", inputType: "text", isRequired: true, placeholder: "John Doe", description: "Enter your full name as it appears on your account", }, { name: "email", label: "Email Address", inputType: "email", isRequired: true, placeholder: "john@example.com", }, { name: "priority", label: "Priority Level", inputType: "select", isRequired: true, items: [ { label: "Low", value: "low" }, { label: "Medium", value: "medium" }, { label: "High", value: "high" }, ], description: "Select the urgency of your request", }, { name: "description", label: "Issue Description", inputType: "textarea", isRequired: true, placeholder: "Please describe your issue in detail...", }, { name: "terms", label: "I agree to the terms of service", inputType: "checkbox", isRequired: true, }, { name: "attachments", label: "Attachments", inputType: "file", description: "Attach any relevant screenshots or files", }, { _type: "include_chat_session", name: "include_chat_session", label: "Include our conversation history", defaultValue: true, }, ], buttons: { submit: { label: "Submit Request", onSubmit: async ({ values, conversation }) => { try { // Handle file conversion if needed if (values.attachments) { values.attachments = await convertFilesToBase64(values.attachments); } // Submit the form data await submitSupportRequest({ ...values, chat_history: conversation?.messages, }); } catch (error) { throw new Error("Failed to submit support request"); } }, }, close: { action: "return_to_chat", }, }, successView: { heading: "Request Submitted Successfully", message: "We have received your support request and will respond within 24 hours.", doneButton: { label: "Return to Chat", icon: { builtIn: "FaArrowLeft" }, action: "return_to_chat", }, }, }; ``` *** title: Custom Instructions description: Add custom instructions to guide the AI assistant's responses. keywords: AI instructions, response customization, AI guidance, custom prompts, AI behavior, instruction configuration, response patterns, AI customization, conversation guidance, instruction implementation -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Sometimes, you want to pass in user information for the AI assistant to consider or provide instructions for the AI assistant to follow. When using the `@inkeep/cxkit-react` components, you can pass this information using `prompts` as part of the [aiChatSettings](/ui-components/common-settings/ai-chat) configuration. You can make these prompts dynamic based on user specific information (e.g. for logged in users) or based on the information from your CRM, application logic, or other sources. `prompts` apply to the entire chat session, not just the first message. ### Add user context Contextual prompts can be used to provide additional details about the user that might be helpful information for the AI assistant to consider while answering. Often, this is used to dynamically provide information about the user that can be inferred by their account (if authenticated to your application) or based on the page they are currently viewing. **Examples** For providing context based on the user: ``` `The user is currently viewing documentation page ${url}.` ``` ``` "The user is new to the platform." // (for user life cycle stages) ``` For providing context based on a product: ``` `The question is about ${product}.` // (for teams with multiple products) ``` ``` "The user is using the cloud hosted version of the application." // (for teams with multiple versions or pricing tiers) ``` ### Add custom rules Prompts can be used to customize or guide the behavior of the AI assistant using instructions in natural langauge. By default, the AI assistanth has sensible defaults for staying on topic, brand-protection, faithfulness to the source content, and other guardrails. However, prompts can be useful to further customizing tone, having the assistant ask more clarifying questions, adding topics it should refuse to answer, or otherwise customizing the exact experience to your scenario. See [Rules & Prompts](/projects/rules-and-prompts) for our recommendations and examples around how to prompt LLMs. *** title: Authenticate Users and add Permissions sidebarTitle: Authenticate Users keywords: user authentication, access control, authentication implementation, security setup, user verification, auth configuration, authentication methods, user access, security implementation, authentication flow, user validation --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Sometimes, you may want to authenticate users accessing your search or chat service. This is typically applicable if you'd like to: * Restrict answers of the assistant to content that a user has access to. Typically applicable for products with private, gated documentation that is only available to users with certain permissions. * Provide context (information) about the user or apply source filters in a way that cannot be tampered with by the end-user. * Implement your own CAPTCHA, throttling, or anti-bot security measures and use a JWT to verify that the user has passed it. ## Generate verification keys Generate a private and public key pair using `openssl` or the method of your choice. ```bash openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048 openssl rsa -pubout -in private_key.pem -out public_key.pem ``` The *private* key will be used by your backend service to mint JWT tokens that are sent to the Inkeep search and chat service. It should not be shared with any other service or third party. ## Configure the integration In your Inkeep Integration, configure the following under **Advanced Settings**: * **Require user authentication**: set to `true` * **Public key**: provide the value of `public_key.pem` * **Issuer**: the value we should ensure matches the `iss` claim in the authentication token. Example: `https://auth.mydomain.com`. This is just a string URI so can be arbitrary. It just needs to uniquely identify your service. We will use the public key to validate the token that is provided to our service was created ('minted') by your service. We check the signature of the token and the `iss`, `exp`, `aud` and other standard claims. ## Generating a token in your backend You need a Microservice to create a JWT token every time a user is looking to make a search or chat. Here is an example of how to generate a token in Node.js: ```typescript import fs from "fs"; import jwt from "jsonwebtoken"; interface TokenConfiguration { iss: string; aud: string; filters?: { // optional attributes: { $and: Array<{ [key: string]: string | { $in: string[] }; }>; }; }; userAttributes?: { // optional [key: string]: string | number | string[]; }; expirationOffsetHours?: number; } const generateToken = ({ iss, aud, integrationId, filters, userAttributes, expirationOffsetHours = 24, }: TokenConfiguration): string => { const privateKey = fs.readFileSync("private_key.pem", "utf8"); // your private key const payload = { iss, aud: "https://api.inkeep.com", integrationId, filters, userAttributes, exp: Math.floor(Date.now() / 1000) + expirationOffsetHours * 60 * 60, }; const token = jwt.sign(payload, privateKey, { algorithm: "RS256" }); return token; }; const exampleConfiguration: TokenConfiguration = { iss: "https://auth.mydomain.com", filters: { attributes: { $and: [ { env: "dev", }, { modules: { $in: ["module1", "module2"], }, }, ], }, }, userAttributes: { userId: "123456789", userEmail: "me@inkeep.com", userCohorts: [`group1`, `group2`], }, expirationOffsetHours: 24, }; const token = generateToken(exampleConfiguration); ``` The token should include the following claims: * `iss`: The issuer of the token. Example `https://auth.mydomain.com`. * `aud`: The audience of the token. It should always be `https://api.inkeep.com`. * `integrationId`: The ID of the integration. This must match the integration ID in the body of the request. * `filters` (optional): Same as documented in the (Filters)\[/ui-components/customization-guides/filters] guide. You can use filters as a way to dynamically scope down the sources that are considered specifically to the sources that the users have permission to access. * `userAttributes` (optional): Same as documented in the [Start new chat](/inkeep-api/create-new-chat-session#newsessionchatresultinput) request body. Takes precedence over the `userAttributes` value provided in the request body. * `exp`: The expiration time of the token, in seconds since the epoch. ## Add the token to chat or search requests ### When using the Inkeep widgets Pass in the token you mint to the widget configuration as `baseSettings.userToken`. See [here](/ui-components/common-settings/base). ### When using the Inkeep API Make sure to include these two headers: * `Authorization` : `Bearer {integrationApiKey}` (must still be present in all requests) * `User-Token`: `{JWT_TOKEN_SIGNED_BY_YOUR_BACKEND}` *** title: Sharable Chats description: Enable users to share their chat conversations. keywords: chat sharing, conversation sharing, share functionality, chat links, conversation links, share implementation, chat features, user collaboration, chat history, share configuration, chat accessibility ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Enable the **Share** button in your Inkeep components.

When clicked, it generates a link to a chat so a user can share with other users. We first need to create a page where the share links will lead to (e.g. `https://inkeep.com/ask-ai`). This should be a page in your documentation, app, or marketing site that contains the Inkeep Embedded Chat component. Reference: * [React](/ui-components/react/in-page/embedded-chat) * [JavaScript](/ui-components/js-snippet/in-page/embedded-chat) Examples: * [Next.js](/integrations/nextjs/embedded-chat) * [Webflow](/integrations/webflow/embedded-chat) The Embedded Chat automatically displays any conversation based on if a `?chatId=` query parameter is present in the URL of the loading the page it's embedded in. Set the value of `aiChatSettings.shareChatUrlBasePath` to the URL from the previous step for all Inkeep components you want to enable the **Share** button for. This can include any Search Bar, Chat Button, or Custom Trigger you use in any site or application. When clicked, it'll copy a link to the user's clipboard in the format of `https://{shareChatUrlBasePath}?chatId={sharedChatId}`. Also set `aiChatSettings.isShareButtonVisible` to `true`. ## Example ```typescript import { type InkeepAIChatSettings } from "@inkeep/cxkit-react"; const inkeepAIChatSettings: InkeepAIChatSettings = { //... rest of inkeepAIChatSettings isShareButtonVisible: true, shareChatUrlBasePath: "https://mydomain.com/ask-ai", }; ``` *** title: Source Transformation description: Transform source content before it's used by the AI assistant. keywords: content transformation, source modification, content processing, data transformation, content formatting, source handling, content preparation, data processing, content adaptation, source customization, content optimization ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Scenario In this guide, we'll explore how to customize the display of source information. This includes modifying source icons, titles, URLs, breadcrumbs, the tabs where search results appear, and other metadata for search results and chat references. ## Type Signature The `transformSource` function is defined in the `InkeepBaseSettings` interface and allows you to modify how source information appears in different contexts: | Parameter | Type | Description | | --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ | | `source` | `SourceItem` | The original source data containing title, URL, description, etc. | | `type` | `'chatSourceItem' \| 'searchResultItem' \| 'intelligentFormSource'` | Context where the source is being displayed | | `opts` | `{ organizationDisplayName?: string; tabs?: (string \| SearchTab)[] }` | Additional options including organization name and configured tabs | The function should return a `TransformedSource` object that defines how the source should be displayed. This gives you control over: * Title and description formatting * URL modifications and parameters * Breadcrumb trails * Tab categorization * Icons and visual elements * Link behavior (new tab vs same window) * Additional metadata and tags Common use cases include: * Adding organization branding to titles * Truncating long descriptions * Categorizing content into tabs * Adding tracking parameters to URLs * Customizing navigation behavior * Setting context-specific icons ```typescript type TransformSource = ( source: SourceItem, type: TransformSourceType, opts?: TransformSourceOptions ) => TransformedSource; interface SourceItem { id?: string; title: string | undefined; url: string; description: string | undefined; breadcrumbs: string[]; type: `${SourceItemType}`; contentType?: string; tag?: string; tabs?: (SourceTab | string)[]; } interface TransformedSource { id?: string; title: string; url: string; description?: string; breadcrumbs?: string[]; tabs?: (string | [string, { breadcrumbs: string[] }])[]; icon: InkeepCustomIcon; shouldOpenInNewTab?: boolean; appendToUrl?: object; type: string; tag?: string; } ``` ## Examples ### Basic source transformation This example sets the title of all sources to include the organization name, and uses the book icon for all sources. ```typescript // Basic source transformation const baseSettings: InkeepBaseSettings = { // ... transformSource: (source, type) => ({ ...source, title: `${source.title} - My Site`, icon: { builtIn: "LuBookOpen" }, }), }; ``` ### Advanced source transformation This example shows how to transform the source data based on whether the source is a search result or a chat source. ```typescript // Advanced source transformation const enterpriseSettings: InkeepBaseSettings = { // ... transformSource: (source, type, opts) => { // Transform based on source type if (type === "searchResultItem") { return { ...source, title: `${opts?.organizationDisplayName} - ${source.title}`, description: source.description?.slice(0, 150) + "...", breadcrumbs: [...(source.breadcrumbs || []), "Documentation"], tabs: ["Docs", ["API", { breadcrumbs: ["API", "Reference"] }]], icon: { builtIn: "LuBookOpen" }, shouldOpenInNewTab: true, appendToUrl: { source: type }, }; } // Different transformation for chat sources if (type === "chatSourceItem") { return { ...source, icon: { custom: "https://assets.example.com/chat-icon.svg" }, shouldOpenInNewTab: false, }; } return source; }, }; ``` ### Add a documentation tab Let's have a "Documentation" tab that shows the sources that come from your docs. Assuming you have other sources aside docs. You'd first one to define a `Documentation` tab: ```typescript const searchSettings: InkeepSearchSettings = { // ... tabs: ["Documentation", ...otherTabs], }; ``` More info on tabs can be found in the [Search and Chat](/ui-components/common-settings/search#search-tabs) guide. Then you'd need to update the `transformSource` function to add qualifying sources to the `Documentation` tab: ```typescript // Basic source transformation const baseSettings: InkeepBaseSettings = { // ... transformSource: (source, type) => { const tabs = source.tabs || []; // Do desired check here if (source.type === "documentation" || source.url.includes("mydocs.com")) { tabs.push("Documentation"); } return { ...source, tabs, }; }, }; ``` ### Hide breadcrumb in matching tab. Say you're in a Blog tab, and a blog post has a breadcrumb of `Blog > Announcement > My Post`. You may want to hide the `Blog` breadcrumb when the user is in the `Blog` tab. Well when setting a tab for a source, you can also decide the breadcrumbs to show in that tab for that source. ```typescript // Basic source transformation const baseSettings: InkeepBaseSettings = { // ... transformSource: (source, type) => ({ ...source, tabs: [ [ "Blog", { breadcrumbs: source.breadcrumbs[0] === "Blog" ? source.breadcrumbs.slice(1) : source.breadcrumbs, }, ], ...otherTabs, ], }), }; ``` *** title: Filter or scope down sources available to the assistant sidebarTitle: Filters & Permissions description: Filter content based on user context. keywords: content filtering, user context, filter implementation, content customization, dynamic filtering, context-based filtering, filter configuration, content scoping, user-specific content, filtering options, content relevance --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Scenario In this guide, we'll explore how to filter the search and chat results using custom tags and attributes. This allows you to tailor the search experience based on specific criteria, such as product versions or SDKs. By using filters, you can ensure that users only see relevant results based on their current context or preferences. ## Filters Filters can be defined using the `filters` property of the `InkeepBaseSettings` interface. These filters will apply to both the search and chat experiences. Alternatively you can also define filters in the `InkeepSearchSettings` and `InkeepChatSettings` interfaces to apply them only to the search or chat experience respectively. ```typescript export interface SearchAndChatFilters { attributes?: { [key: string]: any; }; } ``` ### Supported Operators Comparison Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`\ Array Operators: `$in`, `$nin`\ Boolean Operators: `$exists`\ Logical Operators: `$and`, `$or` ### Filter by custom tags and attributes A common filter scenario is you have docs that covers many products, versions, and SDKs. The first part to setting up filters is to add `` tags prefixed with `inkeep:` to each page. For example: ```html ``` Then to filter the search and chat with your custom tags `version` and `sdk`: ```typescript const baseSettings: InkeepBaseSettings = { // ... filters: { attributes: { $and: [ { version: { $in: ["latest"] } }, { sdk: { $in: ["react", "vue"] } }, ], }, }, }; ``` Filters can be dynamically generated based on the page the user is on, giving full control over the search and chat experience. ### Filter by source id You can also filter by source id. This is useful if you want to show only specific sources in the search and chat results. You can find the source id in the [Inkeep Dashboard](https://portal.inkeep.com/) by going to the **Sources** tab, then selecting the particular source you would like to get the id for. ```typescript const baseSettings: InkeepBaseSettings = { // ... filters: { attributes: { source_id: sourceId, }, }, }; ``` To filter by multiple source ids, you can use the `$or` operator like so: ```typescript const baseSettings: InkeepBaseSettings = { // ... filters: { attributes: { $or: [ { source_id: sourceId1, }, { source_id: sourceId2, }, ], }, }, }; ``` *** title: Content Security Policy description: Configure CSP for Inkeep's UI components. keywords: content security policy, CSP configuration, security settings, web security, script security, CSP directives, security implementation, security headers, CSP setup, security configuration, web application security ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### Allowlisting request endpoints If your app or website has a strict Content Security Policy, you may need to allowlist the following domains: * `https://api.inkeep.com` * `https://api.io.inkeep.com` Alternatively, you can set up a proxy instead using the `chatApiProxyDomain` and `analyticsApiProxyDomain`, see [here](/ui-components/common-settings/base) for more details. ### Allowlisting the script source If you are loading the widget via a [JS Snippet](/ui-components/js-snippet/chat-button) you may also need to allowlist: * `https://cdn.jsdelivr.net` or `https://uikit.inkeep.com` ### Self hosting the JS file If you would like to host the JS file yourself, you can do so by downloading the file from [here](https://cdn.jsdelivr.net/npm/@inkeep/cxkit-js@0.5/dist/embed.js) and hosting it on your own server. 1. Navigate [here](https://cdn.jsdelivr.net/npm/@inkeep/cxkit-js@0.5/dist/embed.js) 2. Right click and save as `inkeep-cxkit-{version}.js`, you can find the version of the package [here](https://cdn.jsdelivr.net/npm/@inkeep/cxkit-js@0.5/dist/) 3. Add the file to your project 4. Replace the url in the script tag with the path to your file: ```html ``` 5. Note that if you need to update the package version, you will need to download the new version and replace the file in your project and update the script tag accordingly. *** title: API keys for Public Assistants sidebarTitle: Public API Keys keywords: API key security, public clients, web security, API authentication, security best practices, referrer URL validation, development environments, staging environments, proxy configuration, rate limiting, security measures, API protection, client security, API key management, security configuration ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ## Public clients When you embed your AI assistant in websites where the user is not authenticated, like in your public docs, help center, or marketing site, the web browser is considered a "public client". Since many of these clients often don't have a backend, the most practical way to use the AI assistant is for UI components to talk directly to the Inkeep service. While it is up to your company's own policies and best practices, in these scenarios, the Inkeep API key is generally ok to be included in the source code of your web page that is exposed in the browser. This is similar to how [Algolia's search service](https://support.algolia.com/hc/en-us/articles/18966776061329-Can-the-search-API-key-be-public) or [Sentry's error logging](https://forum.sentry.io/t/how-does-sentry-prevent-spammers/8188) works. ## Default security To prevent misuse of your public API key, Inkeep by default: * Implements IP and client level throttling and monitoring * Monitors for abusive or spam-like behavior * Uses other security mechanisms * Blocks access to malicious clients Additionally, the API key is tied to the Inkeep chat service, so it's only useful for answering questions about your product. It's *not* a general purpose API key like an API key to OpenAI or general LLM provider would be. ## Content security We recommend **not** using private content like support tickets or internal Slack conversations in your customer-facing assistants. They are typically only used in employee-facing AI [Inkeep Copilot](/support-tools/agent-copilot/overview) or internal [Slack bot](/integrations/slack/internal-team). Private vs public projects and sources are labeled in the Inkeep dashboard to help make it clear. Check the **Sources** tab in a project to see what sources are enabled for a project. ## Referrer URL For **Web** integration types, we recommend: 1. Specifying the root URL of your webpage in the **URL** field 2. Ensuring the **Enforce referrer URL** option is enabled for your production API keys 3. Registering a different integration for at minimum every domain/site you add Inkeep to. As one of many security measures, this enables our chat service to check that API requests are coming from browsers navigating your website. ### Local development For local environments, we recommend *creating a separate Web integration* so you can have a different API key than your production one. You can disable **Enforce referrer URL** for this purpose. Keep this API key secure. ### Staging environments Similarly, we recommend creating another **Web** integration for your staging environments with a different URL and API key. You can leave **Enforce referrer URL** enabled. Creating separate API keys also helps keep real vs test usage separated in your analytics. ## Advanced security If you would like to implement your own protection mechanisms or keep the API key private, you can have traffic routed through a private proxy. Your proxy is then responsible for rate limiting mechanisms or other security measures like CAPTCHA services. In this scenario, you can use an **API** integration type instead of a **Web** type and have your proxy insert the API key in the forwarded requests. This is because the communication now happens between your proxy server and Inkeep's server. Alternatively, you can require a user to authenticate with your application before accessing the assistant. You can optionally have the Inkeep chat service validate a JWT token to check that the user should have access. Contact [support](mailto:support@inkeep.com?subject=Implement%20protection%20mechanisms) for details on either of these approaches. *** title: Overview description: Add custom behavior to the Inkeep Assistant UI keywords: AI tools, custom functions, tool integration, chat interactions, message buttons, action triggers, tool schemas, function definitions, UI customization, tool callbacks, tool implementation, chat automation, tool configuration, custom actions, tool events ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Tools allow you to define custom functions that can be called by the AI assistant during chat interactions. These tools enable the AI to trigger actions in your application or the chat experience. For example, you can use tools to escalate the conversation to a support channel or embed a sales call to action from within the experience. {" "} Tools are available for the Enterprise tier. Please contact [sales@inkeep.com](mailto:sales@inkeep.com?subject=Enterprise%20Plan%20-%20Tools%20Access) for details.{" "} ## Overview Tools are defined in the `getTools` function of the [AI chat settings](/ui-components/common-settings/ai-chat#tools). Each tool has a `type`, `function` definition, and a `renderMessageButtons` callback which determines which **Message Buttons** to display. Message Buttons, if displayed, are shown in the bottom left of the assistant message and can trigger a variety of different [actions](/ui-components/common-settings/actions) when clicked by the user. | Action Type | Description | Use Case | | ----------------- | ------------------------------------------ | ---------------------------------------------------------------- | | `open_link` | Opens a URL in a new tab or current window | Link to documentation, external resources, or contact pages | | `invoke_callback` | Executes a JavaScript callback function | Trigger custom logic in your application, like showing a modal | | `open_form` | Displays a configurable form dialog | Collect user information for support tickets or contact requests | Currently, tools are invoked after the AI assistant has responded with its main message. You can define tool schemas using `zod` and `zod-to-json-schema` or directly with a JSON Object Schema. ```ts const aiChatSettings: InkeepAIChatSettings = { // ... other chat settings getTools: (ctx: ToolContext) => { return [ { type: "function", function: { name: "callme", description: "Call this function every time", parameters: { // JSON Object Schema }, }, renderMessageButtons: ({ args }) => { return [ { label: "My Button", action: { type: "open_link", url: "https://mydomain.com/page", }, }, ]; }, }, ]; }, }; ``` ## `onToolCall` The `onToolCall` callback function is triggered whenever the AI uses a tool. ```ts const aiChatSettings: InkeepAIChatSettings = { // ... other chat settings onToolCall: ( toolCall: FunctionToolCallArgumentsDoneEvent, ctx: ToolContext ) => { console.log(toolCall.name); console.log(toolCall.arguments); console.log(ctx.conversation); }, }; ``` ## Common Tool Use Cases Here are a few common use cases: * [Escalate to Support](/ui-components/tools/escalate-to-support) - Show a button that allows a user to escalate to support or hand off to other support channels. * [Detect Sales Intent](/ui-components/tools/detect-sales-signals) - Identify when a user is expressing buying intent and have a sales call to action. * [Label Answers](/ui-components/tools/label-answers) - Log question-answer data and annotations to your analytics system. For common tool schema definitions, see [Common Tools](/ui-components/tools/common-tool-schemas). *** title: Escalate to Support description: Dynamically direct users to support as needed icon: LuHeartHandshake keywords: support escalation, customer support, support automation, support workflow, ticket creation, live chat integration, support form, support routing, AI confidence, support options, support tools, support integration, support handoff, support automation tools -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Overview You can use tools to identify when the AI assistant can't fully address a user's question and provide appropriate support options. A button can be shown in the assistant message that can use actions to: * Link to a support page * Have the user fill out a support form * Transfer to live chat {" "} Tools are available for the Enterprise tier. Please contact [sales@inkeep.com](mailto:sales@inkeep.com?subject=Enterprise%20Plan%20-%20Tools%20Access) for details.{" "} Example of the escalate to support tool

## Answer Confidence Tool This example uses the `provideAnswerConfidenceSchema` from [Common Tools](/ui-components/tools/common-tool-schemas) to determine the AI assistant's confidence level. You can define your own classifications or logic for the escelation paths you prefer. When the answer is not confident, we can show a dynamic button to escalate to support. ## Link to Support Page ```typescript import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import type { ToolFunction } from "@inkeep/cxkit-react"; import { provideAnswerConfidenceSchema } from "./common-tool-schemas.ts"; const aiChatSettings = { getTools: () => [ { type: "function", function: { name: "provideAnswerConfidence", description: "Determine how confident the AI assistant was and whether or not to escalate to humans.", parameters: zodToJsonSchema(provideAnswerConfidenceSchema), }, renderMessageButtons: ({ args }) => { const confidence = args.answerConfidence; if (["not_confident", "no_sources", "other"].includes(confidence)) { return [ { label: "Contact Support", icon: { builtIn: "IoHelpBuoyOutline" }, action: { type: "open_link", url: "/support", }, }, ]; } return []; }, } as ToolFunction<{ answerConfidence: string; explanation: string; }>, ], }; ``` ### Support Ticket Form This example embeds a form for creating support tickets directly within the chat interface: ```typescript import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import { provideAnswerConfidenceSchema } from "./common-tool-schemas.ts"; const aiChatSettings = { getTools: () => [ { type: "function", function: { name: "provideAnswerConfidence", description: "Determine how confident the AI assistant was and whether or not to escalate to humans.", parameters: zodToJsonSchema(provideAnswerConfidenceSchema), }, renderMessageButtons: ({ args }) => { const confidence = args.answerConfidence; if (["not_confident", "no_sources", "other"].includes(confidence)) { return [ { label: "Create Ticket", icon: { builtIn: "LuUsers" }, action: { type: "open_form", formSettings: { heading: "Contact Support", description: "We'll help you resolve your issue.", fields: [ { label: "Email", name: "email", inputType: "email", isRequired: true, }, { label: "Description", name: "description", inputType: "textarea", isRequired: true, }, { _type: "include_chat_session", name: "include_chat_session", label: "Include chat history", defaultValue: true, }, ], buttons: { submit: { label: "Submit Request", onSubmit: async ({ values, conversation }) => { // Create support ticket in your support platform await submitSupportRequest(values); }, }, close: { action: "return_to_chat", }, }, successView: { heading: "Request Submitted", message: "We'll get back to you shortly.", doneButton: { label: "Close", action: "return_to_chat", }, }, }, }, }, ]; } return []; }, }, ], }; ``` ### Transfer to Live Chat ```typescript import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import { provideAnswerConfidenceSchema } from "./common-tool-schemas.ts"; const aiChatSettings = { getTools: () => [ { type: "function", function: { name: "provideAnswerConfidence", description: "Determine how confident the AI assistant was and whether or not to escalate to humans.", parameters: zodToJsonSchema(provideAnswerConfidenceSchema), }, renderMessageButtons: ({ args }) => { const confidence = args.answerConfidence; if (["not_confident", "no_sources", "other"].includes(confidence)) { return [ { label: "Talk to Support", icon: { builtIn: "IoChatbubblesOutline" }, action: { type: "invoke_callback", callback: ({ conversation }) => { // Switch to live chat. Implementation depends on your live chat provider. switchToLiveChat(conversation); }, }, }, ]; } return []; }, }, ], }; ``` *** title: Detect Sales Signals description: Identify and respond to purchasing signals in user questions icon: LuLightbulb keywords: sales detection, purchasing signals, sales automation, sales tools, sales integration, sales workflow, sales triggers, sales response, sales actions, sales routing, sales opportunities, sales conversion, sales automation tools, sales implementation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ## Overview The "Detect Sales Signals" tool pattern helps identify when users express potential interest in making a purchasing or action related to sales. This is useful for embedding call to actions to: * Schedule a sales meeting * Triggering in-app logic to make an upgrade * Guiding users to relevant pricing or sales content {" "} Tools are available for the Enterprise tier. Please contact [sales@inkeep.com](mailto:sales@inkeep.com?subject=Enterprise%20Plan%20-%20Tools%20Access) for details.{" "} ## Book a meeting This example provides a demo scheduling link when a sales signal is detected. ```typescript import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import type { ToolFunction } from "@inkeep/cxkit-react"; import { salesSignalType, detectedSalesSignal } from "./common-tool-schemas.ts"; const validSalesSignalTypes: string[] = salesSignalType.options.map( (option) => option.value ); const aiChatSettings = { getTools: () => [ { type: "function", function: { name: "detectSalesSignal", description: "Identify when users express interest in potentially purchasing a product.", parameters: zodToJsonSchema(detectedSalesSignal), }, renderMessageButtons: ({ args }) => { // If any valid sales signal is detected, show a demo scheduling option if (args.type && validSalesSignalTypes.includes(args.type)) { return [ { label: "Schedule a Demo", icon: { builtIn: "LuCalendar" }, action: { type: "open_link", url: "/schedule-demo", }, }, ]; } return []; }, } as ToolFunction<{ type: string }>, ], }; ``` Use the following styles if you would like to make the button larger and on it's own line:

```typescript import type { InkeepBaseSettings } from "@inkeep/cxkit-react"; const baseSettings: InkeepBaseSettings = { // ...rest of baseSettings theme: { styles: [ { key: "custom-style", type: "style", value: ` .ikp-ai-chat-message-toolbar { flex-wrap: wrap; justify-content: flex-end; } .ikp-ai-chat-message-tool-actions { width: 100%; } .ikp-ai-chat-message-tool-action { background: var(--ikp-color-gray-950); color: white; font-size: 15px; border: none; margin: 0px auto; margin-bottom: 8px; padding: 12px 24px; gap: 12px; display: flex; height: auto; } .ikp-ai-chat-message-tool-action > .ikp-icon { font-size: 18px; } .ikp-ai-chat-message-tool-action:hover:not([disabled]) { background: var(--ikp-color-gray-800); color: white; } [data-theme="dark"] .ikp-ai-chat-message-tool-action { background: var(--ikp-color-inkeep-expanded-primary-400); color: var(--ikp-color-gray-950); } [data-theme="dark"] .ikp-ai-chat-message-tool-action:hover:not([disabled]) { background: var(--ikp-color-inkeep-expanded-primary-200); color: var(--ikp-color-gray-950); } `, }, ], }, }; ``` ## Signal-Based Actions This example provides different actions based on the specific type of sales signal detected. Example of the escalate to sales tool

```typescript import { z } from "zod"; import type { InkeepAIChatSettings, ToolFunction } from "@inkeep/cxkit-react"; import { zodToJsonSchema } from "zod-to-json-schema"; import { detectedSalesSignal } from "./common-tool-schemas.ts"; const aiChatSettings: InkeepAIChatSettings = { getTools: () => [ { type: "function", function: { name: "detectSalesSignal", description: "Identify when users express interest in potentially purchasing a product.", parameters: zodToJsonSchema(detectedSalesSignal), }, renderMessageButtons: ({ args }) => { const signalType = args.type; // Different actions based on specific signal type if ( [ "requested_sales_contact", "enterprise_features", "implementation_services", ].includes(signalType) ) { return [ { label: "Talk to Sales", icon: { builtIn: "FaUserTie" }, action: { type: "open_link", url: "/contact-sales", }, }, ]; } if (signalType === "pricing_inquiry") { return [ { label: "View Pricing", icon: { builtIn: "FaTag" }, action: { type: "open_link", url: "/pricing", }, }, ]; } if (signalType === "upgrade_inquiry") { return [ { label: "Upgrade Account", icon: { builtIn: "LuSparkles" }, action: { type: "invoke_callback", callback: ({ conversation }) => { // Custom logic to show an upgrade modal in your application showUpgradeModal(); }, }, }, ]; } return []; }, } as ToolFunction<{ type: string }>, ], }; ``` *** title: Label answers and add to your own analytics system sidebarTitle: Label answers description: Log question-answer data and annotations to your analytics system icon: LuTag keywords: answer labeling, analytics integration, data logging, question-answer pairs, conversation tracking, data annotation, analytics tools, conversation analytics, answer quality, content analysis, data collection, conversation metrics, analytics implementation, data tracking ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Overview The "Label Answers" tool pattern allows you to annotate question-answer pairs and log the data to your own analytics system. This is useful for: * Building a labeled dataset of user questions and AI responses * Tracking conversation quality metrics * Identifying content gaps in your knowledge base * Analyzing user sentiment and question patterns {" "} Tools are available for the Enterprise tier. Please contact [sales@inkeep.com](mailto:sales@inkeep.com?subject=Enterprise%20Plan%20-%20Tools%20Access) for details.{" "} ## Basic Implementation This example uses the `annotationSchema` from [Common Tools](/ui-components/tools/common-tool-schemas) to classify and log information about each question-answer pair to your analytics system. ```typescript import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import { annotationSchema } from "./common-tool-schemas.ts"; import myAnalyticsSdk from "./my-analytics-sdk"; const aiChatSettings = { getTools: () => [ { type: "function", function: { name: "annotateQuestion", description: "Analyze and annotate this question-answer pair for quality tracking and analytics.", parameters: zodToJsonSchema(annotationSchema), }, // No buttons needed as this is just for logging renderMessageButtons: () => [], }, ], // Log the tool call data to your analytics system onToolCall: (toolCall, ctx) => { if (toolCall.name === "annotateQuestion") { const annotations = toolCall.arguments; const { conversation } = ctx; // Get the latest user question and AI response const userQuestion = conversation.messages .filter((msg) => msg.role === "user") .pop(); const aiResponse = conversation.messages .filter((msg) => msg.role === "assistant" && !msg.tool_calls) .pop(); // Log to your analytics system myAnalyticsSdk.logEvent("question_answer_annotated", { questionText: userQuestion?.content, answerText: aiResponse?.content, annotations, conversationId: conversation.id, timestamp: new Date().toISOString(), }); } }, }; ``` *** sidebarTitle: Common Tools title: Common Tool Schema Definitions icon: LuShapes keywords: tool schemas, schema definitions, TypeScript schemas, Zod schemas, tool configuration, answer confidence, sales detection, data annotation, schema implementation, tool parameters, schema examples, tool definitions, schema patterns, tool customization -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Custom tool definitions can be passed into the [AI API](/ai-api/chat-completions-api) or [`cxkit` UI components](/ui-components/tools/overview). The below are examples for a few common scenarios. You can adjust the exact descriptions, possible values, and exact schemas to adhere to your own business logic. These examples use `zod` TypeScript library, but these can be defined using other serialization libraries or a plain JSON Object Schema. To covert these Zod definitions to a JSON schema, use: ```ts import { zodToJsonSchema } from "zod-to-json-schema"; const jsonSchema = zodToJsonSchema(yourZodSchema); ``` If using Webflow or other app platforms, ask Claude or ChatGPT to give you the JSON Object Schema equivalent of the below. ### Answer Confidence Tool Use this schema as the parameters for a `provideAnswerConfidence` tool to determine how confident the AI assistant was and whether or not to escelate to humans. ```ts common-tool-schemas.ts.ts /* example classifiers for answer confidence */ const answerConfidence = z .union([ z.literal("very_confident").describe(` The AI Assistant provided a complete and direct answer to all parts of the User Question. The answer fully resolved the issue without requiring any further action from the User. Every part of the answer was cited from the information sources. The assistant did not ask for more information or provide options requiring User action. This is the highest Answer Confidence level and should be used sparingly. `), z.literal("somewhat_confident").describe(` The AI Assistant provided a complete and direct answer to the User Question, but the answer contained minor caveats or uncertainties. Examples: • The AI Assistant asked follow-up questions to the User • The AI Assistant requested additional information from the User • The AI Assistant suggested uncertainty in the answer • The AI Assistant answered the question but mentioned potential exceptions `), z.literal("not_confident").describe(` The AI Assistant tried to answer the User Question but did not fully resolve it. The assistant provided options requiring further action from the User, asked for more information, showed uncertainty, suggested the user contact support or provided contact information, or provided an indirect or incomplete answer. This is the most common Answer Confidence level. Examples: • The AI Assistant provided a general answer not directly related to the User Question • The AI Assistant said to reach out to support or provided an email address or contact information • The AI Assistant provided options that require further action from the User to resolve the issue `), z.literal("no_sources").describe(` The AI Assistant did not use or cite any sources from the information sources to answer the User Question. `), z.literal("other").describe(` The User Question is unclear or unrelated to the subject matter. `), ]) .describe( "A measure of how confidently the AI Assistant completely and directly answered the User Question." ); const provideAnswerConfidenceSchema = z.object({ explanation: z .string() .describe( "A brief few word justification of why a specific confidence level was chosen." ), answerConfidence, }); ``` ### Sales Signals Tool Use this schema as the parameters for a `detectSalesSignal` tool to identify sales signals. Leverage this to link them to a sign up flow, talk to sales, or perform an upgrade. ```ts common-tool-schemas.ts.ts const salesSignalType = z .union([ z.literal("requested_sales_contact").describe(` The user has explicitly asked to speak with a sales representative or sales team. Examples: • "Can I talk to someone from sales?" • "How do I contact your sales team?" • "I'd like to schedule a call with a sales rep" • "Is there someone I can talk to about purchasing?" `), z.literal("pricing_inquiry").describe(` The user has asked about pricing, costs, billing, or payment options. Examples: • "How much does this service cost?" • "What's the pricing for the enterprise plan?" • "Do you offer annual billing discounts?" • "What would it cost for our team of 50 people?" `), z.literal("enterprise_features").describe(` The user has inquired about enterprise-specific features, capabilities, or requirements. Examples: • "Do you support SSO integration?" • "What security certifications do you have?" • "Is there an on-premise deployment option?" • "Do you have custom SLAs for enterprise customers?" `), z.literal("upgrade_inquiry").describe(` The user has asked about upgrading their current plan or moving to a higher tier. Examples: • "How do I upgrade to the Pro plan?" • "What's involved in moving from Basic to Enterprise?" • "I'm hitting limits on my current plan and need to upgrade" • "What additional features do I get if I upgrade?" `), z.literal("implementation_services").describe(` The user has asked about professional services, implementation support, or consulting. Examples: • "Do you offer implementation services?" • "Can you help us migrate our data?" • "Do you have consultants who can help us set this up?" • "What kind of onboarding support do you provide?" `), z.literal("comparison_competitive").describe(` The user is comparing the product with competitors or alternatives. Examples: • "How do you compare to [Competitor]?" • "What makes your solution better than [Alternative]?" • "Why should we choose you instead of [Competitor]?" • "What's your advantage over other solutions?" `), z.literal("trial_demo_request").describe(` The user has requested a product demo or trial. Examples: • "Can I get a demo of your product?" • "How do I sign up for a trial?" • "I'd like to see the product in action" • "Do you offer proof of concept engagements?" `), ]) .describe("Specific type of sales signal detected in the user's question"); const detectedSalesSignal = z.object({ explanation: z .string() .describe( "A brief few word justification of why a specific sales signal was chosen." ), type: salesSignalType, }); ``` ### Annotation Tool Use this schema as the parameters for an `annotateQuestion` tool to classify user questions and analyze AI responses. These annotations can help improve your AI system by identifying content gaps, sentiment patterns, and question types. ```ts custom-annotations-schema.ts /* Basic sentiment classification */ const sentimentEnum = z .enum(["positive", "negative", "neutral"]) .describe( "The user's expressed sentiment in their question or message. Keep to neutral unless clearly negative or positive. A user factually stating their bug or issue is not negative." ); /* Enhanced question type classification */ const questionTypeEnum = z .enum([ "how_to", "troubleshooting", "feature_request", "comparison", "pricing", "billing", "support_request", "account_issue", "other", ]) .describe( "The general category or intent of the user's question. Consider whether the question relates to your product or third-party integrations." ); /* Content gap classification using yes/no/not applicable */ const yesNoNaEnum = z .enum(["yes", "no", "n/a"]) .describe( "Use n/a if it doesn't seem like the classifier is applicable or relevant to the question-answer pair." ); /* Main annotation schema combining all classifiers */ const annotationSchema = z.object({ /* Sentiment analysis */ sentiment: sentimentEnum, /* Question classification */ questionType: questionTypeEnum, /* Content gap analysis */ isDocumented: yesNoNaEnum.describe( "Whether an answer to the user's question is fully and explicitly documented in available sources. Use 'yes' only if complete information was found in documentation." ), isFeatureSupported: yesNoNaEnum.describe( "Whether a feature or capability the user is asking about is directly supported. Use 'no' if it's only partially supported or requires workarounds." ), }); /* Example usage in a tool definition */ const annotateQuestionSchema = z.object({ annotation: annotationSchema, }); ``` *** title: UI Components Release Notes sidebarTitle: Release notes keywords: UI components changelog, release history, version updates, bug fixes, feature releases, npm packages, JavaScript components, React components, UI updates, component library, integration updates, SDK versions, UI improvements, component versioning, package updates --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Release notes ### Version 0.5.91 * Add prop to theme to disable loading the default font `disableLoadingDefaultFont`. ```bash npm install @inkeep/cxkit-react@0.5.91 ``` ```html ``` ```html ``` *** ### Version 0.5.90 * Improve Mintlify integration. ```bash npm install @inkeep/cxkit-react@0.5.90 ``` ```html ``` ```html ``` *** ### Version 0.5.89 * Add missing alt tag to chat button icon image. * Support markdown in the form description. * Make `successView` prop optional in `FormSettings`. * Bug fix for button label not being applied to the submit button. ```bash npm install @inkeep/cxkit-react@0.5.89 ``` ```html ``` ```html ``` *** ### Version 0.5.88 * Bug fix for Fern integration. ```bash npm install @inkeep/cxkit-react@0.5.88 ``` ```html ``` ```html ``` *** ### Version 0.5.87 ```bash npm install @inkeep/cxkit-react@0.5.87 ``` ```html ``` ```html ``` *** ### Version 0.5.86 * Add close button to the [Sidebar Chat](/ui-components/js-snippet/sidebar-chat) component. ```bash npm install @inkeep/cxkit-react@0.5.86 ``` ```html ``` ```html ``` *** ### Version 0.5.83 * Add the ability to control the open state of the new [Sidebar Chat](/ui-components/js-snippet/sidebar-chat) component. ```bash npm install @inkeep/cxkit-react@0.5.83 ``` ```html ``` ```html ``` *** ### Version 0.5.82 * Add a `triggerSelector` prop to the `modalSettings`, this allows you to specify a custom selector to trigger the modal without needing to implement your own `onOpenChange` handler or keep track of the open state. ```bash npm install @inkeep/cxkit-react@0.5.82 ``` ```html ``` ```html ``` *** ### Version 0.5.81 * New `SidebarChat` component, see [Sidebar Chat](/ui-components/js-snippet/sidebar-chat) or [Sidebar Chat (React)](/ui-components/react/sidebar-chat) for more details. ```bash npm install @inkeep/cxkit-react@0.5.81 ``` ```html ``` ```html ``` *** ### Version 0.5.80 * Pin `react-remove-scroll` to version `2.6.3` to fix an uncaught error in the latest version. ```bash npm install @inkeep/cxkit-react@0.5.80 ``` ```html ``` ```html ``` *** ### Version 0.5.79 * Add global error boundary to all components * Prevent errors from propagating to the parent ```bash npm install @inkeep/cxkit-react@0.5.79 ``` ```html ``` ```html ``` *** ### Version 0.5.78 * Small style fix for conflict with Tailwind version 4 ```bash npm install @inkeep/cxkit-react@0.5.78 ``` ```html ``` ```html ``` *** ### Version 0.5.77 * Fix bug with events in shared chats ```bash npm install @inkeep/cxkit-react@0.5.77 ``` ```html ``` ```html ``` *** ### Version 0.5.76 * Add `analyticsProperties` to `baseSettings` to allow for custom properties to be sent to analytics * Update `UserProperties` type to allow for custom properties ```bash npm install @inkeep/cxkit-react@0.5.76 ``` ```html ``` ```html ``` *** ### Version 0.5.75 * Remove `react-icons` dependency * Add `data-has-message-buttons` attribute to the message container when message buttons are rendered as a result of a tool call ```bash npm install @inkeep/cxkit-react@0.5.75 ``` ```html ``` ```html ``` *** ### Version 0.5.73 * Add prop `askAICardLabel` to customize the label of the ask AI card separately from the ask AI toggle label ```bash npm install @inkeep/cxkit-react@0.5.73 ``` ```html ``` ```html ``` *** ### Version 0.5.72 * Minor UI adjustments ```bash npm install @inkeep/cxkit-react@0.5.72 ``` ```html ``` ```html ``` *** ### Version 0.5.71 * Ask ai query animation ```bash npm install @inkeep/cxkit-react@0.5.71 ``` ```html ``` ```html ``` *** ### Version 0.5.70 * Add toolcalls to events ```bash npm install @inkeep/cxkit-react@0.5.70 ``` ```html ``` ```html ``` *** ### Version 0.5.69 * Support copying as html ```bash npm install @inkeep/cxkit-react@0.5.69 ``` ```html ``` ```html ``` *** ### Version 0.5.66 * Fix bug with `shouldAutoFocusInput` prop not working as expected * Release new Fern integration package `@inkeep/cxkit-fern`, see [here](/integrations/fern) for details ```bash npm install @inkeep/cxkit-react@0.5.66 ``` ```html ``` ```html ``` *** ### Version 0.5.64 * Add events for `modal_opened` and `modal_closed` * Tweak dual pane search ui spacing ```bash npm install @inkeep/cxkit-react@0.5.64 ``` ```html ``` ```html ``` *** ### Version 0.5.63 * Add styles to collapse the search bar for small screens to the docusaurus package ```bash npm install @inkeep/cxkit-react@0.5.63 ``` ```html ``` ```html ``` *** ### Version 0.5.62 * Fix incompatible deps * Decrease animation time when opening modal ```bash npm install @inkeep/cxkit-react@0.5.62 ``` ```html ``` ```html ``` *** ### Version 0.5.59 * Improve prompting for the intelligent form * Small bug fix ```bash npm install @inkeep/cxkit-react@0.5.59 ``` ```html ``` ```html ``` *** ### Version 0.5.58 * Fix prefilling in the intelligent form ```bash npm install @inkeep/cxkit-react@0.5.58 ``` ```html ``` ```html ``` *** ### Version 0.5.57 * Small bug fix search breadcrumbs casing ```bash npm install @inkeep/cxkit-react@0.5.57 ``` ```html ``` ```html ``` *** ### Version 0.5.56 * Add default z-index to chat button ```bash npm install @inkeep/cxkit-react@0.5.56 ``` ```html ``` ```html ``` *** ### Version 0.5.55 * Accessibility improvements ```bash npm install @inkeep/cxkit-react@0.5.55 ``` ```html ``` ```html ``` *** ### Version 0.5.52 * Small style bug fix ```bash npm install @inkeep/cxkit-react@0.5.52 ``` ```html ``` ```html ``` *** ### Version 0.5.51 * Add more built-in icons ```bash npm install @inkeep/cxkit-react@0.5.51 ``` ```html ``` ```html ``` *** ### Version 0.5.50 * Bug fix for event logging ```bash npm install @inkeep/cxkit-react@0.5.50 ``` ```html ``` ```html ``` *** ### Version 0.5.49 * Implement focus trap for modal ```bash npm install @inkeep/cxkit-react@0.5.49 ``` ```html ``` ```html ``` *** ### Version 0.5.48 * Bug fix ```bash npm install @inkeep/cxkit-react@0.5.48 ``` ```html ``` ```html ``` *** ### Version 0.5.47 * Bug fix ```bash npm install @inkeep/cxkit-react@0.5.47 ``` ```html ``` ```html ``` *** ### Version 0.5.46 * Fix for disclaimer tooltip on mobile ```bash npm install @inkeep/cxkit-react@0.5.46 ``` ```html ``` ```html ``` *** ### Version 0.5.45 * Bug fix ```bash npm install @inkeep/cxkit-react@0.5.45 ``` ```html ``` ```html ``` *** ### Version 0.5.44 * Add conversation context to onToolCall ```bash npm install @inkeep/cxkit-react@0.5.44 ``` ```html ``` ```html ``` *** ### Version 0.5.43 * Add `onToolCall` callback ```bash npm install @inkeep/cxkit-react@0.5.43 ``` ```html ``` ```html ``` *** ### Version 0.5.42 * Bundle cxkit-js package into cxkit-mintlify ```bash npm install @inkeep/cxkit-react@0.5.42 ``` ```html ``` ```html ``` *** ### Version 0.5.40 * Add new Mintlify integration package `@inkeep/cxkit-mintlify`, see [here](/integrations/mintlify) for details ```bash npm install @inkeep/cxkit-react@0.5.40 ``` ```html ``` *** ### Version 0.5.39 * Improve search result rendering ```bash npm install @inkeep/cxkit-react@0.5.39 ``` ```html ``` *** ### Version 0.5.37 * Add support for tool calls see [here](/ui-components/tools/overview) for details ```bash npm install @inkeep/cxkit-react@0.5.37 ``` ```html ``` *** ### Version 0.5.36 * Small bug fix ```bash npm install @inkeep/cxkit-react@0.5.36 ``` ```html ``` *** ### Version 0.5.35 * Small bug fix ```bash npm install @inkeep/cxkit-react@0.5.35 ``` ```html ``` *** ### Version 0.5.34 * Add js package types to `@inkeep/cxkit-types` ```bash npm install @inkeep/cxkit-react@0.5.34 ``` ```html ``` *** ### Version 0.5.33 * Tweak dual pane search styles ```bash npm install @inkeep/cxkit-react@0.5.33 ``` ```html ``` *** ### Version 0.5.32 * Fix search result item previews in dual-pane search ```bash npm install @inkeep/cxkit-react@0.5.32 ``` ```html ``` *** ### Version 0.5.31 * Add a new prop to search settings called `view` which can be `single-pane` (default) or `dual-pane`, this prop determines whether to render the search results in a single list or a two pane view with a list of results on the left and a preview of the content on the right ```bash npm install @inkeep/cxkit-react@0.5.31 ``` ```html ``` *** ### Version 0.5.30 * Small bug fix for message id generation ```bash npm install @inkeep/cxkit-react@0.5.30 ``` ```html ``` *** ### Version 0.5.20 * Bug fix for duplicate breadcrumb keys ```bash npm install @inkeep/cxkit-react@0.5.20 ``` ```html ``` *** ### Version 0.5.18 * Fix id collision in the js package ```bash npm install @inkeep/cxkit-react@0.5.18 ``` ```html ``` *** ### Version 0.5.17 * Use first tab as default tab ```bash npm install @inkeep/cxkit-react@0.5.17 ``` ```html ``` *** ### Version 0.5.16 * Bundle types ```bash npm install @inkeep/cxkit-react@0.5.16 ``` ```html ``` *** ### Version 0.5.15 * Configure Webpack to resolve JavaScript modules ```bash npm install @inkeep/cxkit-react@0.5.15 ``` ```html ``` *** ### Version 0.5.11 `@inkeep/cxkit-react` #### Breaking changes #### [Base Settings](/ui-components/common-settings/base) **Removed:** * `integrationId` * `organizationId` * `userType` * `remoteErrorLogsLevel` * `consoleDebugLevel` * `customCardSettings` (use [transformSource](/ui-components/common-settings/base#source-transformation) instead) * `breadcrumbRules` (use [transformSource](/ui-components/common-settings/base#source-transformation) instead) * `stringReplacementRules` (use [transformSource](/ui-components/common-settings/base#source-transformation) instead) **Changed:** * `userId`, `userEmail`, `userName` were renamed and are now under `userProperties`: ```ts userProperties: { id: "user-456", email: "jane@enterprise.com", name: "Jane Smith", cohorts: ["admin", "engineering"], } ``` * `userToken` -> `userAuthToken` * The `logEventCallback` was renamed to `onEvent` and the `InkeepCallbackEvent` type has changed, see [here](/ui-components/common-settings/base#event-handling) for details * The event names and structure have also changed, see [here](/ui-components/customization-guides/use-your-own-analytics#events-reference) for details * `optOutAnalyticalCookies`, `optOutAllAnalytics`, `optOutFunctionalCookies` are now under `privacyPreferences`: ```ts privacyPreferences: { optOutAnalyticalCookies: false, optOutAllAnalytics: false, optOutFunctionalCookies: false, } ``` * `chatApiProxyDomain` -> `aiApiBaseUrl` * `analyticsApiProxyDomain` -> `analyticsApiBaseUrl` * `env` options are now lower case: `"development" | "production"` * `appendQueryParamsToUrls` -> `urlQueryParamsToAppend` * `colorMode` now allows for more robust synchronization, see [here](/ui-components/common-settings/base#color-mode) for details * `stylesheets` and `stylesheetUrls` were renamed to `styles` see [here](/ui-components/customization-guides/style-components#custom-styles) for details * Updated classnames can be found [here](/ui-components/customization-guides/style-components#component-class-names) #### [AI Chat Settings](/ui-components/common-settings/ai-chat) **Removed:** * `isControlledMessage` * `includeAIAnnotations` (equivalent functionality coming soon) * `aiAnnotationPolicies` (equivalent functionality coming soon) **Changed:** * `botName` -> `aiAssistantName` * `botAvatarSrcUrl` -> `aiAssistantAvatar` * `botAvatarDarkSrcUrl` -> can be configured by passing an object with `light` and `dark` URLs for different theme modes: ```typescript // Single URL aiAssistantAvatar: "/assets/assistant.png" // Or light/dark mode URLs aiAssistantAvatar: { light: "/assets/assistant-light.png", dark: "/assets/assistant-dark.png" } ``` * `userAvatarSrcUrl` -> `userAvatar` * `quickQuestions` -> `exampleQuestions` * `quickQuestionsLabel` -> `exampleQuestionsLabel` * `shouldHighlightFirstQuickQuestion` -> `isFirstExampleQuestionHighlighted` * `disclaimerSettings` properties were renamed: ```ts disclaimerSettings: { isEnabled: true, label: "AI Assistant", tooltip: "Responses are AI-generated and may require verification.", }, ``` * `handleMessageChange` -> `onInputMessageChange` * `getHelpCallToActions` -> `getHelpOptions` types and form configurations have changed, see [here](/ui-components/common-settings/actions) for details * The `FormConfig` type was renamed to `AIChatFormSettings` has and the configuration has changed, see [here](/ui-components/common-settings/actions#formconfig-reference) for details. * `isChatSharingEnabled` -> `isShareButtonVisible` * `shouldShowCopyChatButton` -> `isCopyChatButtonVisible` * `actionButtonLabels` -> `toolbarButtonLabels` * Within `toolbarButtonLabels`: * `clearButtonLabel` -> `clear` * `shareButtonLabel` -> `share` * `getHelpButtonLabel` -> `getHelp` * `stopButtonLabel` -> `stop` * `copyChatButtonLabel` -> `copyChat` * `context` use `prompts` instead, see [here](/ui-components/customization-guides/custom-instructions) for details * `guidance` use `prompts` instead, see [here](/ui-components/customization-guides/custom-instructions) for details #### [Search Settings](/ui-components/common-settings/search) **Removed:** * `isControlledSearchQuery` **Changed:** * `prefilledQuery` -> `defaultQuery` * `handleSearchQueryChange` -> `onQueryChange` * `tabSettings` -> `tabs` and type has changed, see [here](/ui-components/common-settings/search#search-tabs) for details * `shouldShowAskAICard` was moved to be a top level prop * `maximumHitsLimit` -> `maxResults` * `debounceTime` -> `debounceTimeMs` #### Modal Settings **Removed:** * `isShortcutKeyEnabled` pass `shortcutKey` as `null` to disable the shortcut key or pass a key to enable it * `isAlignedToTop` * `isAlignedToRight` * `onShortcutKeyPressed` **Changed:** * `openShortcutKey` -> `shortcutKey` * `askAILabel` was moved to be a top level prop * `switchToSearchMessage` -> `searchLabel` and was moved to be a top level prop * `isModeSwitchingEnabled` -> `canToggleView` and was moved to be a top level prop * `forceInitialDefaultView` -> `forceDefaultView` and was moved to be a top level prop #### Chat Button **Removed:** * `chatButtonType` * `chatButtonBgColor` can be change via css using this className `.ikp-chat-button__button` * `chatButtonBgColorDarkMode` can be change via css using this className `[data-theme='dark'] .ikp-chat-button__button` * `isPositionFixed` can be change via css by setting `position: relative;` on this className `.ikp-chat-button__container` * `fixedPositionXOffset` can be change via css by setting `right: 0;` on this className `.ikp-chat-button__container` * `fixedPositionYOffset` can be change via css by setting `bottom: 0;` on this className `.ikp-chat-button__container` **Changed:** * `chatButtonText` -> `label` #### Custom Trigger **Changed:** * This component was renamed to `ModalSearchAndChat` for both search and chat functionality or `ModalSearch` for just search functionality or `ModalChat` for just chat functionality see [here](/ui-components/react/custom-modal-trigger) for details. * `isOpen` was moved inside `modalSettings` * `onOpen` -> `onOpenChange` (moved inside `modalSettings`) * `onClose` -> can utilize `onOpenChange` (moved inside `modalSettings`) #### JS Snippet * The interface for using the js snippet has changed, see [here](/ui-components/js-snippet) for details #### Docusaurus * The interface for adding and configuring the Docusaurus plugin has changed, see [here](/integrations/docusaurus/chat-button-and-search-bar) for details. ### API keys * Production API keys for web integrations are now required to have `Enforce referrer URL` enabled for additional security, see [here](/ui-components/public-api-keys#referrer-url) for details. API keys without this setting will be severely rate limited. #### New * Intelligent form component see [here](/ui-components/common-settings/form) for details * Embedded search component see [here](/ui-components/react/in-page/embedded-search) for details * Embedded search and chat component see [here](/ui-components/react/in-page/embedded-search-and-chat) for details ```bash npm install @inkeep/cxkit-react@0.5.11 ``` ```html ``` *** ### Version 0.3.19 * Minor bug fix for search result titles. ```bash npm install @inkeep/uikit@0.3.19 ``` ```html ``` *** ### Version 0.3.18 * Minor bug fixes. ```bash npm install @inkeep/uikit@0.3.18 ``` ```html ``` *** ### Version 0.3.17 * Fix bug with modal closing unexpectedly in mobile view. ```bash npm install @inkeep/uikit@0.3.17 ``` ```html ``` *** ### Version 0.3.16 * Added `name` property to `get_help_option_clicked` event. ```bash npm install @inkeep/uikit@0.3.16 ``` ```html ``` *** ### Version 0.3.15 * Added `pinToToolbar` prop on `GetHelpCallToAction`. See [here](/ui-components/common-settings/ai-chat#gethelpcalltoaction) for more details. * Minor bug fixes. ```bash npm install @inkeep/uikit@0.3.15 ``` ```html ``` *** ### Version 0.3.14 * Fix list style bug. ```bash npm install @inkeep/uikit@0.3.14 ``` ```html ``` *** ### Version 0.3.13 * Added a prop `forceInitialDefaultView` to `modalSettings` to allow modal to open in a certain view, regardless of which view was last opened. See [modalSettings](/ui-components/common-settings/modal#inkeepmodalsettings) for more details. ```bash npm install @inkeep/uikit@0.3.13 ``` ```html ``` *** ### Version 0.3.12 * Fix export for `InkeepEvent` types. ```bash npm install @inkeep/uikit@0.3.12 ``` ```html ``` *** ### Version 0.3.11 * Added optional `searchQueryParamKey` prop to `searchSettings`. * Added event logging for search result clicks. * Made the default placeholder text 'Search...' for small screens. ```bash npm install @inkeep/uikit@0.3.11 ``` ```html ``` *** ### Version 0.3.10 * Exposed the `SearchFunctions` in the embed js package. * Fixed `targetElement` being marked as required for `ChatButton` and `CustomTrigger` component types in the embed js package. ```bash npm install @inkeep/uikit@0.3.10 ``` ```html ``` *** ### Version 0.3.9 * Added a prop called `shouldShowCopyChatButton` to `aiChatSettings`, when enabled this will show a button to allow users to copy their entire conversation as markdown. * Added `messages` and `chatSessionId` as arguments to the `InvokeCallbackAction` for `GetHelpCallToAction` and `ShowEscalateToSupportButtonAction`. * Added analytics events for when a user clicks a get help menu item or support button. * Minor UI / bug fixes. ```bash npm install @inkeep/uikit@0.3.9 ``` ```html ``` *** ### Version 0.3.8 * Added `SELECT` field type to support form. See [here](/ui-components/customization-guides/embedded-support-form#formfield) for details. * Added support for markdown strings in the `message` prop of the `SuccessConfirmationPageProps`. See [here](/ui-components/customization-guides/embedded-support-form#successconfirmationpageprops) for details. ```bash npm install @inkeep/uikit@0.3.8 ``` ```html ``` *** ### Version 0.3.7 * Small bug fix. ```bash npm install @inkeep/uikit@0.3.7 ``` ```html ``` *** ### Version 0.3.6 * Small style fix. ```bash npm install @inkeep/uikit@0.3.6 ``` ```html ``` *** ### Version 0.3.5 * Update license field. * Small style tweak. ```bash npm install @inkeep/uikit@0.3.5 ``` ```html ``` *** ### Version 0.3.4 * Minor UI improvements. ```bash npm install @inkeep/uikit@0.3.4 ``` ```html ``` *** ### Version 0.3.1 * Minor UI improvements. ```bash npm install @inkeep/uikit@0.3.1 ``` ```html ``` *** ### Version 0.3.0 `@inkeep/uikit` * We have renamed the `@inkeep/widgets` and `@inkeep/widgets-embed` packages to `@inkeep/uikit` and `@inkeep/uikit-js` respectively. Links to new packages can be found here: [uikit](https://www.npmjs.com/package/@inkeep/uikit) / [uikit-js](https://www.npmjs.com/package/@inkeep/uikit-js). * This new package contains a significant change to the search ui, moving from a two pane search result view to a single pane view with support for keyboard navigation.

**Additions** * New prop in `searchSettings` `shouldShowAskAICard` to control whether or not to show the `Ask AI ""` card in the search results. Default `true`. #### Breaking changes * Renamed the following options for `chatButtonType`: `ICON_TEXT` is now `PILL` and `ICON_TEXT_SHORTCUT` is now `RECTANGLE_SHORTCUT`. * Renamed the type `InkeepWidgetBaseSettings` to `InkeepBaseSettings`. * Consolidated `chatButtonPillText` and `chatButtonCommandText` into a single prop `chatButtonText`. * Moved `stylesheets` and `stylesheetUrls` props into `theme` (within `baseSettings`). * `switchToChatMessage` is now `askAILabel` and will apply to both the `Ask AI ""` card in the search results and to the toggle to switch to chat. * `submitOnEnterOnly` prop was removed from `searchSettings`. * Removed support for passing `colorMode` in the `theme` (which was deprecated in version `0.2.247`), `colorMode` will only be supported in `baseSettings`. * Removed support for passing `highlighterTheme` in `baseSettings` (which was deprecated in version `0.2.247`), `syntaxHighlighter` will only be supported in the `theme`. * Removed no longer used `CustomIcons`: `linkIndicator`, `newLine`, and `enter`. * Removed `shouldAnimateSwitchToChatButton` prop, the animation was removed since button was changed to a toggle. * Updated and removed some classnames to match ui changes. **Added**: * `.ikp-ask-ai-card` * `.ikp-search-result-line__first` * `.ikp-search-result-line__second` **Removed**: * `.ikp-switch-to-chat-button` * `.ikp-switch-to-chat-button__shortcut` * `.ikp-enter-icon` * `.ikp-heading-tree__title` * `.ikp-heading-tree__list` * `.ikp-heading-tree__item` * `.ikp-heading-tree__heading` * `.ikp-new-line-icon` * `.ikp-preview-content-header__heading` * `.ikp-preview-content-header__title` * `.ikp-link-indicator-icon` ```bash npm install @inkeep/uikit@0.3.0 ``` ```html ``` *** ### Version 0.2.289 * Update license. * Fix bug with duplicate titles in mobile view. ```bash npm i @inkeep/widgets@0.2.289 ``` ```html ``` *** ### Version 0.2.286 * Allow users to pass in query params to append to documentation links. See `appendQueryParamsToUrls` in [baseSettings](/ui-components/common-settings/base) for more details. *** ### Version 0.2.285 * Fix small style bug. *** ### Version 0.2.284 * Allow users to pass in their own instance of Prism js to avoid conflicts in the global namespace. *** ### Version 0.2.282 * Fix being able to style the switch to chat button with custom css. *** ### Version 0.2.281 * Fixes to support for react 19. *** ### Version 0.2.280 * Remove apollo dev tools console message. *** ### Version 0.2.279 * Bug fix to improve multi language support. *** ### Version 0.2.278 * Bug fixes. *** ### Version 0.2.276 * Fallback to default bot avatar if user provided bot avatar doesn't load. * Improve styling for docs search preview. *** ### Version 0.2.275 * Added a file input type to the support form. *** ### Version 0.2.274 * Added a prop to change the chat button color. See [here](/ui-components/react/chat-button#properties) for more details. *** ### Version 0.2.272 * Add workflowId to `chat_message_submitted` and `chat_message_bot_response_received` events. *** ### Version 0.2.271 * Add info tooltip for workflow attachments. *** ### Version 0.2.270 * Minor style tweak. *** ### Version 0.2.269 * Exposed the `AIChatFunctions` in the embed js package. * Added `openForm` to `AIChatFunctions` so it can be triggered from outside the widget. See [here](/ui-components/common-settings/ai-chat#aichatfunctions) for more details. * Added `closeFormAction` to `FormConfig`. See [here](/ui-components/customization-guides/embedded-support-form#formconfig) for more details. #### Breaking changes * Removed `backToChatButtonLabel` from `SuccessConfirmationPageProps` and replaced with `SuccessConfirmationButton`. See [here](/ui-components/customization-guides/embedded-support-form#successconfirmationbutton) for more details. *** ### Version 0.2.268 * Add switch to chat and submit hot key (cmd + enter) * Fix bug with prefilled query not showing in search bar * Fix low chroma primary color derivatives calculations * Use filled sparkles for default icon in chat component *** ### Version 0.2.267 * Adding additional class names for stylization. *** ### Version 0.2.266 * Minor bug fixes *** ### Version 0.2.265 * Edit default disclaimer copy. *** ### Version 0.2.264 * Added support for `CustomIcons`. Refer to [custom icons](/ui-components/customization-guides/style-components#custom-icons) for details. *** ### Version 0.2.263 * Added support for a new `GetHelpCallToAction` and `ShowEscalateToSupportButtonAction`. Refer to [get help call to actions](/ui-components/common-settings/ai-chat#gethelpcalltoactioninvokecallback) and [support workflows](/ui-components/customization-guides/embedded-support-form#invokecallbackaction) for details. * Fix for highlighting search text in dark mode. *** ### Version 0.2.262 * Minor UI improvements. *** ### Version 0.2.261 * Added support workflows feature. Refer to [Support workflows](/ui-components/customization-guides/workflows) for details. * Minor UI improvements. *** ### Version 0.2.260 * Minor bug fixes. *** ### Version 0.2.259 * Adding `context` and `guidance` to `AIChatSettings` for providing dynamic information and instructions to the bot. *** ### Version 0.2.258 * Fix copy button tooltip. * Add default targetElement for the `ChatButton` and `CustomTrigger` in the js snippet. * Add `colorModeSync` logic to the js snippet. *** ### Version 0.2.256 * Fix to close modal if clicking on a search result link within the same page and `shouldOpenLinksInNewTab` is `false`. *** ### Version 0.2.254 * Fix bug with loading stylesheets. *** ### Version 0.2.253 * Deep merge properties in the `widgets-embed` package to improve devx. * Add fallback targetEl in the `widgets-embed` package. *** ### Version 0.2.252 * Update default AI assistant avatar. *** ### Version 0.2.250 * Add `data-state="active"` to the thumbs up and thumbs down buttons after the relative feedback has been submitted, by default they will have `data-state="inactive"`. This can be used to style the buttons differently after feedback submission. *** ### Version 0.2.249 * Fix bug with chat button `fixedPositionXOffset` and `fixedPositionYOffset` props not being applied. * Add `shrink` size variant for the `SearchBarTrigger` component, this variant will shrink the search bar to just the search icon for the smallest screen sizes. *** ### Version 0.2.248 #### Breaking changes * Changed the prop `areOpenHotKeysDisabled` to `isShortcutKeyEnabled` in `modalSettings` * By default `isShortcutKeyEnabled` is `false` for all `InkeepChatButton` variants except `ICON_TEXT_SHORTCUT`, (it is `true` by default for the `InkeepSearchBar` and `InkeepCustomTrigger` components). * By default the `openShortcutKey` is `/` for the `InkeepChatButton` component (it is still `k` for the `InkeepSearchBar` and `InkeepCustomTrigger` components). *** ### Version 0.2.247 * Added support for passing `colorMode` in `baseSettings`, passing in `colorMode` in `theme` is still supported but is deprecated. * Added support for passing `syntaxHighlighter` in `theme`, passing in `baseSettings` (as `highlighterTheme`) is still supported but is deprecated. * Changed the default `chatButtonType` to `ICON_TEXT`. *** ### Version 0.2.246 * Added loading state for AI chat when passing in the chatId prop. *** ### Version 0.2.245 * Added support for customizing the chat action button labels and switch to search button label. *** ### Version 0.2.244 * Added a prop to `SearchSettings` called `submitOnEnterOnly` which will submit search query on enter instead of onChange. Default is `false`. *** ### Version 0.2.243 * Added a prop to `AIChatSettings` called `chatId` which will load the chat corresponding to the id. *** ### Version 0.2.242 * Bumped dependencies to address vulnerability in `vite@4.4.11`. *** ### Version 0.2.241 * Fixed a bug where chat actions were only shown for most recent message. *** ### Version 0.2.238 * Added a prop to `ModalSettings` called `shouldAnimateSwitchToChatButton` which determines whether to animate the switch to chat button on first load. Default is `true`. * Added a variant to the theme for the `SwitchToChat` button, example: ```js const inkeepBaseSettings: InkeepBaseSettings = { theme: { components: { SwitchToChat: { defaultProps: { variant: "subtle", // options are 'primary' or 'subtle' }, }, }, }, }; ``` *** title: Migrating to @inkeep/cxkit Overview sidebarTitle: Overview keywords: migration guide, cxkit migration, package migration, React migration, JavaScript migration, UI toolkit, customer experience toolkit, version upgrade, package update, migration process, component migration, SDK migration, library migration, package transition ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- With version 0.5.x, we've renamed our packages from `@inkeep/uikit` to `@inkeep/cxkit` to better reflect their purpose as customer experience toolkits. ## Choose Your Migration Path Depending on how you're currently using Inkeep, you'll need to follow one of these migration guides: ### [React Migration Guide](/ui-components/migrate-to-cxkit/react) If you're using React components from `@inkeep/uikit`, follow this guide to migrate to `@inkeep/cxkit-react`. ### [JavaScript Migration Guide](/ui-components/migrate-to-cxkit/javascript) If you're using JavaScript snippets from `@inkeep/uikit-js`, follow this guide to migrate to `@inkeep/cxkit-js`. ## Need Help? If you encounter any issues during migration, please [contact our support team](https://inkeep.com/contact) for assistance. *** title: Migrating from @inkeep/uikit-js to @inkeep/cxkit-js sidebarTitle: To @inkeep/cxkit-js keywords: JavaScript migration, cxkit migration, JavaScript SDK, package migration, breaking changes, API updates, configuration changes, component initialization, JavaScript integration, migration guide, code updates, SDK migration, JavaScript toolkit, package transition, API migration ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This guide will help you migrate your JavaScript snippets from using `@inkeep/uikit-js` to the new `@inkeep/cxkit-js` package. The new package includes several breaking changes but offers improved functionality and a more consistent API. ## Overview With version 0.5.x, we've renamed our package from `@inkeep/uikit-js` to `@inkeep/cxkit-js` to better reflect its purpose as a customer experience toolkit. This change comes with several API improvements and breaking changes that require updates to your code. ## Installation Update your script tag to use the new package: ```html ``` ## Breaking Changes ### Component Initialization Changes The way components are initialized has changed: ```javascript // Old const inkeepWidget = Inkeep().embed({ componentType: "ChatButton", // ... }); // New const inkeepWidget = Inkeep.ChatButton({ // ... }); ``` ### Configuration Structure Changes The configuration structure has been simplified: ```javascript // Old const config = { componentType: "ChatButton", properties: { chatButtonType: "PILL", baseSettings: { // ... }, aiChatSettings: { // ... }, // ... }, }; // New const config = { // Top-level properties baseSettings: { // ... }, aiChatSettings: { // ... }, // ... }; ``` ### Base Settings Changes #### Removed Properties ##### `integrationId` The `integrationId` property has been removed as it's no longer required for authentication. The API key now contains all the necessary information to identify your integration. ```javascript // Old baseSettings: { apiKey: "your-api-key", integrationId: "your-integration-id", // ... } // New baseSettings: { apiKey: "your-api-key", // No integrationId needed } ``` ##### `organizationId` The `organizationId` property has been removed as it's no longer required for authentication. The API key now contains all the necessary information to identify your organization. ```javascript // Old baseSettings: { apiKey: "your-api-key", organizationId: "your-organization-id", // ... } // New baseSettings: { apiKey: "your-api-key", // No organizationId needed } ``` ##### `userType` The `userType` property has been removed in favor of the more flexible `userProperties.cohorts` array, which allows you to specify multiple user types or roles. ```javascript // Old baseSettings: { userType: "admin", // ... } // New baseSettings: { userProperties: { cohorts: ["admin", "engineering"], // ... }, // ... } ``` ##### `remoteErrorLogsLevel` The `remoteErrorLogsLevel` property has been removed as error logging is now handled internally with improved defaults. If you need custom error handling, use the `onError` callback. ##### `consoleDebugLevel` The `consoleDebugLevel` property has been removed as debugging is now handled internally with improved defaults. For development debugging, use the browser's developer tools. ##### `customCardSettings` The `customCardSettings` property has been removed in favor of the more powerful and flexible `transformSource` function, which allows for more comprehensive customization of search results. ```javascript // Old baseSettings: { customCardSettings: { // Custom card settings }, // ... } // New baseSettings: { transformSource: (source) => { // Transform source data return { ...source, tabs: [] // Transform tabs }; }, // ... } ``` See [Source Transformation](/ui-components/customization-guides/source-transformation) for more details. ##### `breadcrumbRules` The `breadcrumbRules` property has been removed in favor of the more powerful and flexible `transformSource` function, which allows for more comprehensive customization of breadcrumbs. ```javascript // Old baseSettings: { breadcrumbRules: [ // Breadcrumb rules ], // ... } // New baseSettings: { transformSource: (source) => { // Transform breadcrumbs return { ...source, breadcrumbs: [] }; }, // ... } ``` See [Source Transformation](/ui-components/customization-guides/source-transformation) for more details. ##### `stringReplacementRules` The `stringReplacementRules` property has been removed in favor of the more powerful and flexible `transformSource` function, which allows for more comprehensive string transformations. ```javascript // Old baseSettings: { stringReplacementRules: [ // String replacement rules ], // ... } // New baseSettings: { transformSource: (source) => { // Transform source data return { ...source, breadcrumbs: [] }; }, // ... } ``` See [Source Transformation](/ui-components/customization-guides/source-transformation) for more details. #### Renamed Properties ##### User Properties User properties are now grouped under `userProperties`: ```javascript // Old baseSettings: { userId: "user-456", userEmail: "jane@enterprise.com", userName: "Jane Smith", // ... } // New baseSettings: { userProperties: { id: "user-456", email: "jane@enterprise.com", name: "Jane Smith", cohorts: ["admin", "engineering"], }, // ... } ``` ##### Authentication Token `userToken` → `userAuthToken` ```javascript // Old baseSettings: { userToken: "jwt-token-for-user-authentication", // ... } // New baseSettings: { userAuthToken: "jwt-token-for-user-authentication", // ... } ``` ##### Event Handling `logEventCallback` → `onEvent` (with updated event structure) ```javascript // Old baseSettings: { logEventCallback: (event) => { // Handle event console.log(event); }, // ... } // New baseSettings: { onEvent: (event) => { // Handle event console.log(event); }, // ... } ``` ##### Privacy Preferences Privacy preferences are now grouped: ```javascript // Old baseSettings: { optOutAnalyticalCookies: false, optOutAllAnalytics: false, optOutFunctionalCookies: false, // ... } // New baseSettings: { privacyPreferences: { optOutAnalyticalCookies: false, optOutAllAnalytics: false, optOutFunctionalCookies: false, }, // ... } ``` ##### API Endpoints * `chatApiProxyDomain` → `aiApiBaseUrl` * `analyticsApiProxyDomain` → `analyticsApiBaseUrl` ```javascript // Old baseSettings: { chatApiProxyDomain: "https://api.inkeep.com/chat", analyticsApiProxyDomain: "https://api.example.com/analytics", // ... } // New baseSettings: { aiApiBaseUrl: "https://api.inkeep.com/chat", analyticsApiBaseUrl: "https://api.example.com/analytics", // ... } ``` ##### Environment Configuration `env` options are now lowercase: `"development" | "production"` ```javascript // Old baseSettings: { env: "DEVELOPMENT", // ... } // New baseSettings: { env: "development", // ... } ``` ##### URL Parameters `appendQueryParamsToUrls` → `urlQueryParamsToAppend` ```javascript // Old baseSettings: { appendQueryParamsToUrls: { utm_source: "docs" }, // ... } // New baseSettings: { urlQueryParamsToAppend: { utm_source: "docs" }, // ... } ``` ##### Styling `stylesheets` and `stylesheetUrls` → `styles` ```javascript // Old baseSettings: { stylesheets: ["custom-styles.css"], stylesheetUrls: ["https://example.com/styles.css"], // ... } // New baseSettings: { 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-ai-chat-message { border-radius: 8px; padding: 12px; } [data-theme='dark'] .ikp-ai-chat-message { background: #2D3748; } `, }, ], // ... } ``` ### Color Mode Synchronization The color mode synchronization has been updated: ```javascript // Old colorModeSync: { observedElement: document.documentElement, isDarkModeCallback: (el) => { return el.classList.contains("dark"); }, colorModeAttribute: "class", } // New baseSettings: { colorMode: { sync: { target: document.documentElement, attributes: ["data-theme"], isDarkMode: (attributes) => attributes["data-theme"] === "dark", } } } ``` ### AI Chat Settings Changes #### Removed Properties ##### `isControlledMessage` The `isControlledMessage` property has been removed as the component now uses a more intuitive controlled/uncontrolled pattern. Use the `defaultMessage` prop for uncontrolled behavior or the `message` and `onInputMessageChange` props for controlled behavior. ##### `includeAIAnnotations` The `includeAIAnnotations` property has been removed as annotations are now handled internally with improved defaults. Equivalent functionality will be available in a future release. ##### `aiAnnotationPolicies` The `aiAnnotationPolicies` property has been removed as annotation policies are now handled internally with improved defaults. Equivalent functionality will be available in a future release. #### Renamed Properties ##### Assistant Name and Avatar * `botName` → `aiAssistantName` * `botAvatarSrcUrl` → `aiAssistantAvatar` * `botAvatarDarkSrcUrl` → can be configured by changing `aiAssistantAvatar` to an object: ```javascript // Old aiChatSettings: { botAvatarSrcUrl: "/assets/assistant.png", botAvatarDarkSrcUrl: "/assets/assistant-dark.png", // ... } // New aiChatSettings: { aiAssistantAvatar: { light: "/assets/assistant-light.png", dark: "/assets/assistant-dark.png" }, // ... } ``` ##### User Avatar * `userAvatarSrcUrl` → `userAvatar` ```javascript // Old aiChatSettings: { userAvatarSrcUrl: userProfile.avatarUrl, // ... } // New aiChatSettings: { userAvatar: userProfile.avatarUrl, // ... } ``` ##### Example Questions * `quickQuestions` → `exampleQuestions` * `quickQuestionsLabel` → `exampleQuestionsTitle` * `shouldHighlightFirstQuickQuestion` → `isFirstExampleQuestionHighlighted` ```javascript // Old aiChatSettings: { quickQuestions: ["What is the capital of France?", "What is the capital of Germany?"], quickQuestionsLabel: "Example Questions", shouldHighlightFirstQuickQuestion: true, // ... } // New aiChatSettings: { exampleQuestions: ["What is the capital of France?", "What is the capital of Germany?"], exampleQuestionsTitle: "Example Questions", isFirstExampleQuestionHighlighted: true, // ... } ``` ##### Disclaimer Settings Disclaimer settings properties have been renamed: ```javascript // Old aiChatSettings: { disclaimerSettings: { isDisclaimerEnabled: true, disclaimerLabel: "Usage policy", disclaimerTooltip: "Information provided by AI is not guaranteed to be accurate.", }, // ... } // New aiChatSettings: { disclaimerSettings: { isEnabled: true, label: "Usage policy", tooltip: "Information provided by AI is not guaranteed to be accurate.", }, // ... } ``` ##### Input Handling * `handleMessageChange` → `onInputMessageChange` ```javascript // Old aiChatSettings: { handleMessageChange: (message) => { // Handle message change console.log(message); }, // ... } // New aiChatSettings: { onInputMessageChange: (message) => { // Handle message change console.log(message); }, // ... } ``` ##### Help Options * `getHelpCallToActions` → `getHelpOptions` ```javascript // Old aiChatSettings: { getHelpCallToActions: () => { // Get help call to actions return [ { icon: { builtIn: 'FaDiscord' }, name: 'Discord', url: 'https://inkeep.com/', }, ]; }, // ... } // New aiChatSettings: { getHelpOptions: () => { // Get help options return [ { name: 'Discord', icon: { builtIn: 'FaDiscord', }, action: { type: 'open_link', url: 'https://inkeep.com/', }, }, ]; }, // ... } ``` ##### Form Configuration Form configuration has been updated with improved structuring. See [Form Settings](/ui-components/common-settings/form) for details: ```javascript // Old aiChatSettings: { formConfig: { // Basic form configuration fields: [ { type: "text", name: "name", label: "Name", }, ], }, // ... } // New aiChatSettings: { formSettings: { // Improved form settings structure fields: [ { type: "text", name: "name", label: "Name", validation: { required: true, minLength: 2, }, }, ], submitButton: { label: "Submit", }, onSubmit: (data) => { console.log("Form submitted:", data); }, }, // ... } ``` ##### Sharing and Toolbar * `isChatSharingEnabled` → `isShareButtonVisible` * `shouldShowCopyChatButton` → `isCopyChatButtonVisible` * `actionButtonLabels` → `toolbarButtonLabels` ```javascript // Old aiChatSettings: { isChatSharingEnabled: true, shouldShowCopyChatButton: true, actionButtonLabels: { copy: "Copy Chat", share: "Share Chat", // ... }, // ... } // New aiChatSettings: { isShareButtonVisible: true, isCopyChatButtonVisible: true, toolbarButtonLabels: { copy: "Copy Chat", share: "Share Chat", // ... }, // ... } ``` ##### Prompts * `context` and `guidance` → use `prompts` instead ```javascript // Old aiChatSettings: { context: "The user is new to the product.", guidance: "Be concise.", // ... } // New aiChatSettings: { prompts: [ "The user is new to the product.", "Be concise." ], // ... } ``` ### Search Settings Changes #### Removed Properties ##### `isControlledSearchQuery` The `isControlledSearchQuery` property has been removed as the component now uses a more intuitive controlled/uncontrolled pattern. Use the `defaultQuery` prop for uncontrolled behavior or the `query` and `onQueryChange` props for controlled behavior. #### Renamed Properties ##### `prefilledQuery` The `prefilledQuery` property has been renamed to `defaultQuery` for improved clarity and consistency: ```javascript // Old searchSettings: { prefilledQuery: "How to get started", // ... } // New searchSettings: { defaultQuery: "How to get started", // ... } ``` ##### `handleSearchQueryChange` The `handleSearchQueryChange` property has been renamed to `onQueryChange` for improved clarity: ```javascript // Old searchSettings: { handleSearchQueryChange: (query) => { // Handle query change console.log(query); }, // ... } // New searchSettings: { onQueryChange: (query) => { // Handle query change console.log(query); }, // ... } ``` ##### `tabSettings` The `tabSettings` property has been renamed to `tabs` for improved clarity and simplicity. See docs [here](/ui-components/common-settings/search#search-tabs) for more details: ```javascript // Old searchSettings: { tabSettings: { isAllTabEnabled: true, rootBreadcrumbsToUseAsTabs: ['Docs'], tabOrderByLabel: ['Resources', 'Blog', 'Solutions'], disabledDefaultTabs: undefined, // string[] | undefined alwaysDisplayedTabs: ['Blog'], }, // ... } // New searchSettings: { // Basic tabs tabs: ["All", "Publications", "GitHub", "Forums"], // With always visible option tabs: [ "All", "Publications", ["GitHub", { isAlwaysVisible: true }], "Forums", ], // Hide "All" tab, show only Publications and GitHub tabs: ["Publications", "GitHub"], // No tabs (just show all results) tabs: [], // ... } ``` ##### `maximumHitsLimit` The `maximumHitsLimit` property has been renamed to `maxResults` for improved clarity: ```javascript // Old searchSettings: { maximumHitsLimit: 10, // ... } // New searchSettings: { maxResults: 10, // ... } ``` ##### `debounceTime` The `debounceTime` property has been renamed to `debounceTimeMs` for improved clarity: ```javascript // Old searchSettings: { debounceTime: 500, // ... } // New searchSettings: { debounceTimeMs: 500, // ... } ``` ##### `shouldShowAskAICard` The `shouldShowAskAICard` property has been elevated to a top-level property: ```javascript // Old searchSettings: { shouldShowAskAICard: true, // ... } // New shouldShowAskAICard: true, // Now a top-level property ``` ### Modal Settings Changes #### Removed Properties ##### `isShortcutKeyEnabled` The `isShortcutKeyEnabled` property has been removed. To disable the shortcut key, pass `shortcutKey` as `null`, or pass a key to enable it: ```javascript // Old modalSettings: { isShortcutKeyEnabled: false, // ... } // New modalSettings: { shortcutKey: null, // Disables the shortcut key // ... } ``` ##### `isAlignedToTop` The `isAlignedToTop` property has been removed as modal positioning is now handled through CSS. ##### `isAlignedToRight` The `isAlignedToRight` property has been removed as modal positioning is now handled through CSS. ##### `onShortcutKeyPressed` The `onShortcutKeyPressed` property has been removed as shortcut key handling is now managed internally. #### Renamed Properties ##### `openShortcutKey` The `openShortcutKey` property has been renamed to `shortcutKey` for improved clarity: ```javascript // Old modalSettings: { openShortcutKey: "k", // ... } // New modalSettings: { shortcutKey: "k", // ... } ``` ##### `askAILabel` The `askAILabel` property has been moved to be a top-level property: ```javascript // Old modalSettings: { askAILabel: "Ask AI", // ... } // New askAILabel: "Ask AI", // Now a top-level property ``` ##### `switchToSearchMessage` The `switchToSearchMessage` property has been renamed to `searchLabel` and moved to be a top-level property: ```javascript // Old modalSettings: { switchToSearchMessage: "Search Documentation", // ... } // New searchLabel: "Search Documentation", // Now a top-level property ``` ##### `isModeSwitchingEnabled` The `isModeSwitchingEnabled` property has been renamed to `canToggleView` and moved to be a top-level property: ```javascript // Old modalSettings: { isModeSwitchingEnabled: true, // ... } // New canToggleView: true, // Now a top-level property ``` ##### `forceInitialDefaultView` The `forceInitialDefaultView` property has been renamed to `forceDefaultView` and moved to be a top-level property: ```javascript // Old modalSettings: { forceInitialDefaultView: "search", // ... } // New forceDefaultView: "search", // Now a top-level property ``` ### Chat Button Changes #### Removed Properties ##### `chatButtonType` The `chatButtonType` property has been removed as the button appearance can now be customized via CSS using the provided class names. ##### `chatButtonBgColor` The `chatButtonBgColor` property has been removed as the button background color can now be customized via CSS using the `.ikp-chat-button__button` class. ```css .ikp-chat-button__button { background-color: #4a5568; } ``` ##### `chatButtonBgColorDarkMode` The `chatButtonBgColorDarkMode` property has been removed as the button background color in dark mode can now be customized via CSS using the `[data-theme='dark'] .ikp-chat-button__button` selector. ```css [data-theme="dark"] .ikp-chat-button__button { background-color: #2d3748; } ``` ##### `isPositionFixed` The `isPositionFixed` property has been removed as the button positioning can now be customized via CSS by setting `position: relative;` on the `.ikp-chat-button__container` class. ```css .ikp-chat-button__container { position: relative; } ``` ##### `fixedPositionXOffset` The `fixedPositionXOffset` property has been removed as the button horizontal positioning can now be customized via CSS by setting `right: 0;` on the `.ikp-chat-button__container` class. ```css .ikp-chat-button__container { right: 0; } ``` ##### `fixedPositionYOffset` The `fixedPositionYOffset` property has been removed as the button vertical positioning can now be customized via CSS by setting `bottom: 0;` on the `.ikp-chat-button__container` class. ```css .ikp-chat-button__container { bottom: 0; } ``` #### Renamed Properties ##### Button Label * `chatButtonText` → `label` ```javascript // Old chatButtonSettings: { chatButtonText: "Chat with AI", // ... } // New chatButtonSettings: { label: "Chat with AI", // ... } ``` ## Example Migration ### Before (with @inkeep/uikit-js) ```html ``` ### After (with @inkeep/cxkit-js) ```html ``` ## API Keys Production API keys for web integrations now require `Enforce referrer URL` to be enabled for additional security. API keys without this setting will be severely rate limited. See [Public API Keys](/ui-components/common-settings/base#public-api-keys) for more details. ## New Features The new package includes several new features: * Intelligent form component - See [Form Settings](/ui-components/common-settings/form) * Embedded search component - See [Embedded Search](/ui-components/js-snippet/in-page/embedded-search) * Embedded search and chat component - See [Embedded Search and Chat](/ui-components/js-snippet/in-page/embedded-search-and-chat) ## Need Help? If you encounter any issues during migration, please [contact our support team](https://inkeep.com/contact) for assistance. *** title: Migrating from @inkeep/uikit to @inkeep/cxkit-react sidebarTitle: To @inkeep/cxkit-react keywords: React migration, cxkit migration, React SDK, package migration, breaking changes, API updates, configuration changes, component migration, React integration, migration guide, code updates, SDK migration, React toolkit, package transition, API migration ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This guide will help you migrate your application from using `@inkeep/uikit` to the new `@inkeep/cxkit-react` package. The new package includes several breaking changes but offers improved functionality and a more consistent API. ## Overview With version 0.5.x, we've renamed our package from `@inkeep/uikit` to `@inkeep/cxkit-react` to better reflect its purpose as a customer experience toolkit. This change comes with several API improvements and breaking changes that require updates to your code. ## Installation First, you'll need to update your package dependency: ```bash npm uninstall @inkeep/uikit npm install @inkeep/cxkit-react ``` ```bash yarn remove @inkeep/uikit yarn add @inkeep/cxkit-react ``` ```bash pnpm remove @inkeep/uikit pnpm add @inkeep/cxkit-react ``` ## Breaking Changes ### Package Import Changes Update your imports from: ```typescript import { InkeepChatButton } from "@inkeep/uikit"; ``` To: ```typescript import { InkeepChatButton } from "@inkeep/cxkit-react"; ``` ### Base Settings Changes Several properties in the base settings have been removed or renamed: #### Removed Properties ##### `integrationId` The `integrationId` property has been removed as it's no longer required for authentication. The API key now contains all the necessary information to identify your integration. ```typescript // Old baseSettings: { apiKey: "your-api-key", integrationId: "your-integration-id", // ... } // New baseSettings: { apiKey: "your-api-key", // No integrationId needed } ``` ##### `organizationId` The `organizationId` property has been removed as it's no longer required for authentication. The API key now contains all the necessary information to identify your organization. ```typescript // Old baseSettings: { apiKey: "your-api-key", organizationId: "your-organization-id", // ... } // New baseSettings: { apiKey: "your-api-key", // No organizationId needed } ``` ##### `userType` The `userType` property has been removed in favor of the more flexible `userProperties.cohorts` array, which allows you to specify multiple user types or roles. See docs [here](/ui-components/common-settings/base#user-properties) for more details. ```typescript // Old baseSettings: { userType: "admin", // ... } // New baseSettings: { userProperties: { cohorts: ["admin", "engineering"], // ... }, // ... } ``` ##### `remoteErrorLogsLevel` The `remoteErrorLogsLevel` property has been removed as error logging is now handled internally with improved defaults. ##### `consoleDebugLevel` The `consoleDebugLevel` property has been removed as debugging is now handled internally with improved defaults. ##### `customCardSettings` The `customCardSettings` property has been removed in favor of the more powerful and flexible `transformSource` function, which allows for more comprehensive customization of search results and chat sources ```typescript // Old baseSettings: { customCardSettings: { // Custom card settings }, // ... } // New baseSettings: { transformSource: (source) => { // Transform source data return { ...source, tabs: [] // Transform tabs }; }, // ... } ``` See [Source Transformation](/ui-components/customization-guides/source-transformation) for more details. ##### `breadcrumbRules` The `breadcrumbRules` property has been removed in favor of the more powerful and flexible `transformSource` function, which allows for more comprehensive customization of breadcrumbs. ```typescript // Old baseSettings: { breadcrumbRules: [ // Breadcrumb rules ], // ... } // New baseSettings: { transformSource: (source) => { // Transform source data return { ...source, breadcrumbs: [] }; }, // ... } ``` See [Source Transformation](/ui-components/customization-guides/source-transformation) for more details. ##### `stringReplacementRules` The `stringReplacementRules` property has been removed in favor of the more powerful and flexible `transformSource` function, which allows for more comprehensive string transformations. ```typescript // Old baseSettings: { stringReplacementRules: [ // String replacement rules ], // ... } // New baseSettings: { transformSource: (source) => { // Transform source data return { ...source, breadcrumbs: [] }; }, // ... } ``` See [Source Transformation](/ui-components/customization-guides/source-transformation) for more details. #### Renamed Properties ##### `userId` ##### `userEmail` ##### `userName` User properties are now grouped under `userProperties`. See [User Properties](/ui-components/common-settings/base#user-properties) for more details. ```typescript // Old baseSettings: { userId: "user-456", userEmail: "jane@enterprise.com", userName: "Jane Smith", // ... } // New baseSettings: { userProperties: { id: "user-456", email: "jane@enterprise.com", name: "Jane Smith", cohorts: ["admin", "engineering"], }, // ... } ``` ##### `userToken` The `userToken` property has been renamed to `userAuthToken` to better reflect its purpose as an authentication token for the user. See [User Properties](/ui-components/common-settings/base#user-properties) for more details: ```typescript // Old baseSettings: { userToken: "jwt-token-for-user-authentication", // ... } // New baseSettings: { userAuthToken: "jwt-token-for-user-authentication", // ... } ``` ##### `logEventCallback` The `logEventCallback` property has been renamed to `onEvent` with an updated event structure for more consistent event handling. See [Event Handling](/ui-components/common-settings/base#event-handling) for more details: ```typescript // Old baseSettings: { logEventCallback: (event) => { // Handle event console.log(event); }, // ... } // New baseSettings: { onEvent: (event) => { // Handle event console.log(event); }, // ... } ``` ##### `chatApiProxyDomain` The `chatApiProxyDomain` property has been renamed to `aiApiBaseUrl` to better reflect its purpose as an API endpoint for AI chat functionality. See [Event Handling](/ui-components/common-settings/base#core-settings) for more details: ```typescript // Old baseSettings: { chatApiProxyDomain: "https://api.inkeep.com/chat", // ... } // New baseSettings: { aiApiBaseUrl: "https://api.inkeep.com/chat", // ... } ``` ##### `analyticsApiProxyDomain` The `analyticsApiProxyDomain` property has been renamed to `analyticsApiBaseUrl` to better reflect its purpose as an API endpoint for analytics functionality. See [Core Settings](/ui-components/common-settings/base#core-settings) for more details: ```typescript // Old baseSettings: { analyticsApiProxyDomain: "https://api.example.com/analytics", // ... } // New baseSettings: { analyticsApiBaseUrl: "https://api.example.com/analytics", // ... } ``` ##### `appendQueryParamsToUrls` The `appendQueryParamsToUrls` property has been renamed to `urlQueryParamsToAppend` for clarity. See [URL Parameters](/ui-components/common-settings/base#url-parameters) for more details: ```typescript // Old baseSettings: { appendQueryParamsToUrls: { utm_source: "docs" }, // ... } // New baseSettings: { urlQueryParamsToAppend: { utm_source: "docs" }, // ... } ``` ##### `stylesheets` ##### `stylesheetUrls` Stylesheet properties have been consolidated under a single `styles` property. Style strings can be passed directly. See [Theme Configuration](/ui-components/customization-guides/style-components#theme-configuration) for more details: ```typescript // Old baseSettings: { stylesheets: ["custom-styles.css"], stylesheetUrls: ["https://example.com/styles.css"], // ... } // New baseSettings: { 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-ai-chat-message { border-radius: 8px; padding: 12px; } [data-theme='dark'] .ikp-ai-chat-message { background: #2D3748; } `, }, ], // ... } ``` #### Modified properties ##### `env` `env` options are now lowercase: `"development" | "production"` ```typescript // Old baseSettings: { env: "DEVELOPMENT", // ... } // New baseSettings: { env: "development", // ... } ``` ### AI Chat Settings Changes #### Removed Properties ##### `isControlledMessage` The `isControlledMessage` property has been removed as the component now uses a more intuitive controlled/uncontrolled pattern. Use the `defaultMessage` prop for uncontrolled behavior or the `message` and `onInputMessageChange` props for controlled behavior. ##### `includeAIAnnotations` The `includeAIAnnotations` property has been removed as annotations are now handled internally with improved defaults. Equivalent functionality will be available in a future release. ##### `aiAnnotationPolicies` The `aiAnnotationPolicies` property has been removed as annotation policies are now handled internally with improved defaults. Equivalent functionality will be available in a future release. #### Renamed Properties ##### `botName` ##### `botAvatarSrcUrl` ##### `botAvatarDarkSrcUrl` * `botName` → `aiAssistantName` * `botAvatarSrcUrl` → `aiAssistantAvatar` * `botAvatarDarkSrcUrl` → can be configured by changing `aiAssistantAvatar` to an object: ```typescript // Old aiChatSettings: { botAvatarSrcUrl: "/assets/assistant.png", botAvatarDarkSrcUrl: "/assets/assistant-dark.png", // ... } // New aiChatSettings: { aiAssistantAvatar: { light: "/assets/assistant-light.png", dark: "/assets/assistant-dark.png" }, // ... } ``` ##### `userAvatarSrcUrl` * `userAvatarSrcUrl` → `userAvatar` ```typescript // Old aiChatSettings: { userAvatarSrcUrl: userProfile.avatarUrl, // ... } // New aiChatSettings: { userAvatar: userProfile.avatarUrl, // ... } ``` ##### `quickQuestions` `quickQuestions` is now `exampleQuestions` for improved clarity: ```typescript // Old baseSettings: { quickQuestions: ["What is the capital of France?", "What is the capital of Germany?"], // ... } // New baseSettings: { exampleQuestions: ["What is the capital of France?", "What is the capital of Germany?"], // ... } ``` ##### `exampleQuestionsLabel` `exampleQuestionsLabel` is now `exampleQuestionsTitle` for improved clarity: ```typescript // Old baseSettings: { exampleQuestionsLabel: "Example Questions", // ... } // New baseSettings: { exampleQuestionsTitle: "Example Questions", // ... } ``` ##### `shouldHighlightFirstQuickQuestion` `shouldHighlightFirstQuickQuestion` is now `isFirstExampleQuestionHighlighted` for improved clarity: ```typescript // Old baseSettings: { shouldHighlightFirstQuickQuestion: true, // ... } // New baseSettings: { isFirstExampleQuestionHighlighted: true, // ... } ``` ##### `disclaimerSettings` `isDisclaimerEnabled` is now `isEnabled` and `disclaimerLabel` is now `label` and `disclaimerTooltip` is now `tooltip` within the `AIChatDisclaimerSettings` type. ```typescript // Old import { type InkeepAIChatSettings, type AIChatDisclaimerSettings, } from "@inkeep/uikit"; const aiChatDisclaimerSettings: AIChatDisclaimerSettings = { isDisclaimerEnabled: true, disclaimerLabel: "Usage policy", disclaimerTooltip: "Information provided by {{botName || 'this AI assistant'}} is not guaranteed to be accurate or comprehensive. Please consult {{organizationDisplayName}}'s terms of service and privacy policy for details on how information is used.", }; const inkeepAIChatSettings: InkeepAIChatSettings = { //... rest of inkeepAIChatSettings disclaimerSettings: aiChatDisclaimerSettings, }; // New import { type InkeepAIChatSettings, type AIChatDisclaimerSettings, } from "@inkeep/cxkit-react"; const aiChatDisclaimerSettings: AIChatDisclaimerSettings = { isEnabled: true, label: "Usage policy", tooltip: "Information provided by {{botName || 'this AI assistant'}} is not guaranteed to be accurate or comprehensive. Please consult {{organizationDisplayName}}'s terms of service and privacy policy for details on how information is used.", }; const inkeepAIChatSettings: InkeepAIChatSettings = { //... rest of inkeepAIChatSettings disclaimerSettings: aiChatDisclaimerSettings, ``` ##### `handleMessageChange` `handleMessageChange` is now `onInputMessageChange` for improved clarity: ```typescript // Old baseSettings: { handleMessageChange: (message) => { // Handle message change console.log(message); }, // ... } // New baseSettings: { onInputMessageChange: (message) => { // Handle message change console.log(message); }, // ... } ``` ##### `getHelpCallToActions` `getHelpCallToActions` is now `getHelpOptions` for improved clarity: ```typescript // Old baseSettings: { getHelpCallToActions: () => { // Get help call to actions return [ { icon: { builtIn: 'FaDiscord' }, name: 'Discord', url: 'https://inkeep.com/', }, ]; }, // ... } // New baseSettings: { getHelpOptions: () => { // Get help options return [ { name: 'Discord', icon: { builtIn: 'FaDiscord', }, action: { type: 'open_link', url: 'https://inkeep.com/', }, }, ]; }, // ... } ``` ##### `FormConfig` type `FormConfig` type is now `AIChatFormSettings` for improved clarity and the configuration has changed. See here for more details: [AIChatFormSettings](/ui-components/common-settings/actions#formconfig-reference) ##### `isChatSharingEnabled` The `isChatSharingEnabled` property has been renamed to `isShareButtonVisible` for improved clarity: ```typescript // Old aiChatSettings: { isChatSharingEnabled: true, // ... } // New aiChatSettings: { isShareButtonVisible: true, // ... } ``` ##### `shouldShowCopyChatButton` The `shouldShowCopyChatButton` property has been renamed to `isCopyChatButtonVisible` for improved clarity and consistency with other visibility properties: ```typescript // Old aiChatSettings: { shouldShowCopyChatButton: true, // ... } // New aiChatSettings: { isCopyChatButtonVisible: true, // ... } ``` ##### `actionButtonLabels` The `actionButtonLabels` property has been renamed to `toolbarButtonLabels` to better reflect its purpose for configuring toolbar button text: ```typescript // Old aiChatSettings: { actionButtonLabels: { copy: "Copy Chat", share: "Share Chat", // ... }, // ... } // New aiChatSettings: { toolbarButtonLabels: { copy: "Copy Chat", share: "Share Chat", // ... }, // ... } ``` ##### `context` ##### `guidance` The `context` and `guidance` properties have been consolidated under the more flexible `prompts` property. The new prompts is an array of strings. ```typescript // Old aiChatSettings: { context: "The user is new to the product.", guidance: "Be concise.", // ... } // New aiChatSettings: { prompts: [ "The user is new to the product.", "Be concise." ], // ... } ``` ### Search Settings Changes #### Removed Properties ##### `isControlledSearchQuery` The `isControlledSearchQuery` property has been removed as the component now uses a more intuitive controlled/uncontrolled pattern. Use the `defaultQuery` prop for uncontrolled behavior or the `query` and `onQueryChange` props for controlled behavior. #### Renamed Properties ##### `prefilledQuery` The `prefilledQuery` property has been renamed to `defaultQuery` for improved clarity and consistency with React patterns: ```typescript // Old searchSettings: { prefilledQuery: "How to get started", // ... } // New searchSettings: { defaultQuery: "How to get started", // ... } ``` ##### `handleSearchQueryChange` The `handleSearchQueryChange` property has been renamed to `onQueryChange` for improved clarity and consistency with React event handler naming conventions: ```typescript // Old searchSettings: { handleSearchQueryChange: (query) => { // Handle query change console.log(query); }, // ... } // New searchSettings: { onQueryChange: (query) => { // Handle query change console.log(query); }, // ... } ``` ##### `tabSettings` The `tabSettings` property has been renamed to `tabs` for improved clarity and simplicity. tabs definitions have been updated as well. See docs [here](/ui-components/common-settings/search#search-tabs) for more details. ```typescript // Old searchSettings: { tabSettings: { isAllTabEnabled: true, rootBreadcrumbsToUseAsTabs: ['Docs'], tabOrderByLabel: ['Resources', 'Blog', 'Solutions'], disabledDefaultTabs: undefined, // string[] | undefined alwaysDisplayedTabs: ['Blog'], }, // ... } // New const searchSettings: InkeepSearchSettings = { // Basic tabs tabs: ["All", "Publications", "GitHub", "Forums"], // With always visible option tabs: [ "All", "Publications", ["GitHub", { isAlwaysVisible: true }], "Forums", ], // Hide "All" tab, show only Publications and GitHub tabs: ["Publications", "GitHub"], // No tabs (just show all results) tabs: [], // ... }; ``` ##### `shouldShowAskAICard` The `shouldShowAskAICard` property has been elevated to a top-level property: ```typescript // Old searchSettings: { shouldShowAskAICard: true, // ... } // New shouldShowAskAICard: true, // Now a top-level property ``` ##### `maximumHitsLimit` The `maximumHitsLimit` property has been renamed to `maxResults` for improved clarity and simplicity: ```typescript // Old searchSettings: { maximumHitsLimit: 10, // ... } // New searchSettings: { maxResults: 10, // ... } ``` ##### `debounceTime` The `debounceTime` property has been renamed to `debounceTimeMs` for improved clarity on the unit of time: ```typescript // Old searchSettings: { debounceTime: 500, // ... } // New searchSettings: { debounceTimeMs: 500, // ... } ``` ### Modal Settings Changes #### Removed Properties ##### `isShortcutKeyEnabled` The `isShortcutKeyEnabled` property has been removed. To disable the shortcut key, pass `shortcutKey` as `null`. ```typescript // Old modalSettings: { isShortcutKeyEnabled: false, // ... } // New modalSettings: { shortcutKey: null, // Disables the shortcut key // ... } ``` ##### `isAlignedToTop` The `isAlignedToTop` property has been removed as modal positioning is now handled through CSS. ##### `isAlignedToRight` The `isAlignedToRight` property has been removed as modal positioning is now handled through CSS. ##### `onShortcutKeyPressed` The `onShortcutKeyPressed` property has been removed as shortcut key handling is now managed internally. #### Renamed Properties ##### `openShortcutKey` The `openShortcutKey` property has been renamed to `shortcutKey` for improved clarity. It has a default value of `k`: ```typescript // Old modalSettings: { openShortcutKey: "k", // ... } // New modalSettings: { shortcutKey: "k", // ... } ``` ##### `askAILabel` The `askAILabel` property has been moved to be a top-level prop: ```typescript // Old modalSettings: { askAILabel: "Ask AI", // ... } // New askAILabel: "Ask AI", // Now a top-level prop ``` ##### `switchToSearchMessage` The `switchToSearchMessage` property has been renamed to `searchLabel` and moved to be a top-level prop: ```typescript // Old modalSettings: { switchToSearchMessage: "Search Documentation", // ... } // New searchLabel: "Search Documentation", // Now a top-level prop ``` ##### `isModeSwitchingEnabled` The `isModeSwitchingEnabled` property has been renamed to `canToggleView` and moved to be a top-level prop: ```typescript // Old modalSettings: { isModeSwitchingEnabled: true, // ... } // New canToggleView: true, // Now a top-level prop ``` ##### `forceInitialDefaultView` The `forceInitialDefaultView` property has been renamed to `forceDefaultView` and moved to be a top-level prop: ```typescript // Old modalSettings: { forceInitialDefaultView: "search", // ... } // New forceDefaultView: "search", // Now a top-level prop ``` ### Chat Button Changes #### Removed Properties ##### `chatButtonType` The `chatButtonType` property has been removed as button styling is now handled through CSS. ##### `chatButtonBgColor` The `chatButtonBgColor` property has been removed. You can change the background color via CSS using the `.ikp-chat-button__button` class: ```css .ikp-chat-button__button { background-color: #4a5568; } ``` ##### `chatButtonBgColorDarkMode` The `chatButtonBgColorDarkMode` property has been removed. You can change the background color for dark mode via CSS using the `[data-theme='dark'] .ikp-chat-button__button` selector: ```css [data-theme="dark"] .ikp-chat-button__button { background-color: #2d3748; } ``` ##### `isPositionFixed` The `isPositionFixed` property has been removed. You can change the positioning via CSS by setting `position: relative;` on the `.ikp-chat-button__container` class: ```css .ikp-chat-button__container { position: relative; } ``` ##### `fixedPositionXOffset` The `fixedPositionXOffset` property has been removed. You can change the horizontal positioning via CSS by setting `right: 0;` on the `.ikp-chat-button__container` class: ```css .ikp-chat-button__container { right: 0; } ``` ##### `fixedPositionYOffset` The `fixedPositionYOffset` property has been removed. You can change the vertical positioning via CSS by setting `bottom: 0;` on the `.ikp-chat-button__container` class: ```css .ikp-chat-button__container { bottom: 0; } ``` #### Renamed Properties ##### `chatButtonText` The `chatButtonText` property has been renamed to `label` for improved clarity and consistency: ```typescript // Old chatButtonSettings: { chatButtonText: "Chat with AI", // ... } // New chatButtonSettings: { label: "Chat with AI", // ... } ``` ### Custom Trigger Changes #### Renamed Component The `CustomTrigger` component has been renamed to provide more specific functionality: * `ModalSearchAndChat` - For both search and chat functionality * `ModalSearch` - For just search functionality * `ModalChat` - For just chat functionality See [here](/ui-components/react/custom-modal-trigger) for more details. #### Moved Properties ##### `isOpen` The `isOpen` property has been moved inside `modalSettings`: ```typescript // Old // New ``` ##### `onOpen` The `onOpen` property has been renamed to `onOpenChange` and moved inside `modalSettings`: ```typescript // Old // New ``` ##### `onClose` The `onClose` property has been removed. You can now utilize `onOpenChange` (moved inside `modalSettings`) to handle both open and close events: ```typescript // Old // New { if (!isOpen) { // Handle close } }, // ... }} // ... /> ``` ### API Keys Production API keys for web integrations are now required to have `Enforce referrer URL` enabled for additional security. See [here](/ui-components/public-api-keys#referrer-url) for details. API keys without this setting will be severely rate limited. ### New Components * **Intelligent Form Component**: See [here](/ui-components/common-settings/form) for details. * **Embedded Search Component**: See [here](/ui-components/react/in-page/embedded-search) for details. * **Embedded Search and Chat Component**: See [here](/ui-components/react/in-page/embedded-search-and-chat) for details. *** sidebarTitle: Overview title: Inkeep AI API Overview icon: IoSparklesOutline keywords: AI API, chat completions API, OpenAI compatibility, LLM integration, chatbot development, AI assistant, RAG implementation, API endpoints, model selection, API authentication, chat API, AI models, API documentation, developer tools, API integration, TypeScript SDK, Python SDK, API examples, API modes, API configuration ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Inkeep's AI API endpoints make it easy to develop chatbot or copilot experiences powered by your own knowledge base. Because these endpoints are compatible with OpenAI's Chat Completion API format, so you can use most LLM application frameworks, libraries, or SDKs with zero code changes. For example, you can build a: * ChatGPT-like UI using the [Next.js Chatbot template](https://vercel.com/templates/next.js/nextjs-ai-chatbot) * Product-specific copilot using the [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) or [LangChain](https://github.com/langchain-ai/langchainjs) * An automation for replying to customer emails or as a plugin to your support platform using [OpenAI's TypeScript SDK](https://github.com/openai/openai-node). Check out our [examples](https://github.com/inkeep/inkeep-chat-api-examples) for quickstarts for the various APIs. ## Available Models We offer various APIs tailored for different use cases, we use the `model` concept to differentiate between the different scenarios and functionality. | Model (API) Name | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inkeep-qa` | Provides sensible defaults for customer-facing support assistant or "question-answer" scenarios. Useful for auto-reply automations or custom chat experiences. | | `inkeep-context` | A flexible "passthrough" proxy that injects Inkeep's RAG context into calls to underlying models from Anthropic or OpenAI. Fully compatible with all chat completion endpoint functionality including tool/function calling, JSON mode, and image inputs. Ideal for custom AI agents, LLM applications, or workflows requiring full output control while benefiting from a managed RAG system. Provides high flexibility but requires standard LLM application prompting and experimentation. | | `inkeep-base` | A fast version of the `inkeep-context` mode that skips RAG and instead only injects a general overview of your product into calls to base models. Best for when you want the flexibility of the `inkeep-context` mode, but don't need the full comprehensive context. | | `inkeep-rag` | Provides structured RAG chunks directly from your knowledge base. Returns chunks with URLs, excerpts from the original documents, and other source information. Ideal for custom implementations where you need direct access to the retrieved knowledge base content. You'd typically pass these chunks ('documents') to an LLM of your choice for any open-ended purpose. | ## Get an API key 1. Log in to the [Inkeep Dashboard](https://portal.inkeep.com) 2. Navigate to the **Projects** section and select your project 3. Open the **Assistants** tab 4. Click **Create assistant** and choose **API** from the options 5. Enter a Name for your new API assistant. 6. Click on **Create** 7. A generated **API key** will appear that you can use to authenticate API requests. ## Using the API To use with an OpenAI-compatible client, simply: 1. Customize the `baseURL` to `https://api.inkeep.com/v1` and use an Inkeep `apiKey` 2. Specify the mode by setting `model` to a value in the format of `{inkeep-mode}-{model}` If you'd like to let Inkeep manage which model is used * `inkeep-qa-expert` * `inkeep-context-expert` * `inkeep-base` * `inkeep-rag` If you'd like to pin the service against a preferred LLM model for the `qa` or `context` APIs, you can do so like this: * `inkeep-qa-sonnet-4` * `inkeep-qa-gpt-4o` * `inkeep-qa-gpt-4-turbo` * `inkeep-context-sonnet-4` * `inkeep-context-gpt-4-turbo` * `inkeep-context-gpt-4o` ### Calling the API All modes use the OpenAI chat completion API format. You can use any OpenAI compatible SDK in any language to make requests to the API. If you don't need streaming, then a regular HTTP request works fine. If you use streaming, we recommend using one of the SDKs. ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: 'YOUR_INKEEP_API_KEY', baseURL: 'https://api.inkeep.com/v1' }); const completion = await client.chat.completions.create({ model: 'inkeep-context-expert', messages: [ { role: 'user', content: 'How do I get started?' }, ], }); ``` ```typescript import { generateText } from 'ai'; import { createOpenAI } from '@ai-sdk/openai'; // Create an OpenAI provider configured for Inkeep const inkeep = createOpenAI({ apiKey: 'YOUR_INKEEP_API_KEY', baseURL: 'https://api.inkeep.com/v1', }); const { text } = await generateText({ model: inkeep('inkeep-context-expert'), messages: [ { role: 'user', content: 'How do I get started?' }, ], }); ``` ```python from openai import OpenAI client = OpenAI( api_key="YOUR_INKEEP_API_KEY", base_url="https://api.inkeep.com/v1" ) completion = client.chat.completions.create( model="inkeep-context-expert", messages=[ {"role": "user", "content": "How do I get started?"}, ], ) ``` ```sh curl https://api.inkeep.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "model": "inkeep-context-expert", "messages": [ { "role": "user", "content": "How do I get started?" } ] }' ``` Follow the guides for the mode you want to use for details on the expected response schema and usage patterns. ## Limitations ### Rate Limits * **Per-IP throttling** is enabled.\ Need a higher rate? Email [support@inkeep.com](mailto:support@inkeep.com?subject=Rate%20limit%20request). ### Chat Limits * **30 messages per chat session**\ (1 user message + 1 assistant response = 2 “messages”). ### Message Size | Direction | Recommended tokens | Notes | | ---------- | ------------------ | ------------------------------------------------------------------------------ | | **Input** | ≤ **100** | Short fragments, single sentences, or brief paragraphs yield the best results. | | **Output** | ≤ **1 000** | Longer outputs are allowed but may be less optimal. | Have a use case that is outside these recommended limits? Reach out to [support@inkeep.com](mailto:support@inkeep.com?subject=Custom%20limits). *** sidebarTitle: Overview title: Question Answer API Overview icon: IoSparklesOutline keywords: Question Answer API, chatbot development, AI assistant, support automation, API tools, response structure, custom tools, source citations, TypeScript schema, API integration, tool calls, QA implementation, AI models, chat completion, response formatting, API documentation, customer support, auto-reply system, inkeep-qa, Claude Sonnet, GPT-4, provideRecordsConsidered, provideLinks, custom tool calls --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `inkeep-qa` API is specifically tailored for customer-facing question-answer scenarios like support chatbots or auto-reply workflows. ## Overview This API comes with Inkeep's sensible built-in behavior for: * format of citations * tone * protecting your brand * minimal hallucinations `inkeep-qa` is best suited for when you want to develop your own chat UX or question-answer automations with a great out of the box building block. ## Available Models You can specify the model used in the format of `inkeep-qa-[model]` * `inkeep-qa-expert` - Let Inkeep manage which model is used * `inkeep-qa-sonnet-4` - Use Anthropic's Claude Sonnet 4 * `inkeep-qa-gpt-4o` - Use OpenAI's GPT-4o ## Response Structure The API responds with an AI assistant message (`content`) and optional tools for displaying extra metadata or annotations about an answer. | Component | Description | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `content` | Contains the conversational answer of the AI assistant as any normal OpenAI chat completion request. This is what you would display as the AI assistant answer in a traditional chat UI. | ## Tools In addition to `content`, which is always returned, `inkeep-qa` can return additional tool calls. You can provide your own and use the two built in ones: | Tools | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provideRecordsConsidered` | Provides a list of records considered (sources) by the AI assistant to generate a response. You can use this to give a preview of relevant records that were considered for an answer prior to the generation of the response. If using streaming, it will stream the records used before the response is generated. NOTE: Not all of these records are used in the final answer. | | `provideLinks` | Provides a list of links (sources) used by the AI assistant to generate a response. You can use this to display citations for an answer. | | `[customToolCall]` | Allows you to pass in custom tool calls to the AI assistant. You can use this to, for example, determine whether the AI assistant is confident, detect buying intent, categorize a question, determine when to call your own backend APIs to retrieve dynamic information from backend systems, or perform custom actions. These are defined by you and are not managed by Inkeep. See [common tools](/ui-components/tools/common-tool-schemas) for examples. | ## Built In Schemas ```ts title="inkeep-qa-tools-schema.ts" import { z } from "zod"; /* provideRecordsConsidered tool schema */ const InkeepRecordTypes = z.enum([ "documentation", "site", "discourse_post", "github_issue", "github_discussion", "stackoverflow_question", "discord_forum_post", "discord_message", "custom_question_answer", ]); const LinkType = z.union([ InkeepRecordTypes, z.string(), // catch all ]); const ProvideRecordsConsideredToolSchema = z.object({ recordsConsidered: z.array( z.object({ breadcrumbs: z.array(z.string()).nullish(), title: z.string().nullish(), type: LinkType.nullish(), url: z.string().nullish(), }) ), }); /* provideLinks tool schema */ const InkeepRecordTypes = z.enum([ "documentation", "site", "discourse_post", "github_issue", "github_discussion", "stackoverflow_question", "discord_forum_post", "discord_message", "custom_question_answer", ]); const LinkType = z.union([ InkeepRecordTypes, z.string(), // catch all ]); const LinkSchema = z .object({ label: z.string().nullish(), // the value of the footnote, e.g. `1` url: z.string(), title: z.string().nullish(), description: z.string().nullish(), type: LinkType.nullish(), breadcrumbs: z.array(z.string()).nullish(), }) .passthrough(); export const LinksSchema = z.array(LinkSchema).nullish(); export const LinksToolSchema = z.object({ links: LinksSchema, }); ``` ## Implementation Examples To learn more about implementing the QA API with different SDKs and frameworks: * [Using the OpenAI SDK](/ai-api/question-answer-mode/openai-sdk) * [Using the Vercel AI SDK](/ai-api/question-answer-mode/vercel-ai-sdk) * [Working with Custom Tool Calls](/ai-api/question-answer-mode/custom-tool-calls) *** sidebarTitle: Vercel AI SDK title: Using the Question Answer API with the Vercel AI SDK keywords: Vercel AI SDK, React integration, Next.js implementation, server components, streaming UI, chat interface, API integration, React hooks, server actions, TypeScript implementation, QA API, chat components, UI components, API streaming, tool functions, React Server Components, inkeep-qa, useChat hook, streamUI, edge runtime, server-side rendering, client-side rendering ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Using useChat and a route [`useChat`](https://sdk.vercel.ai/docs/reference/ai-sdk-ui/use-chat) is cross-platform hook that helps you create a conversational experience with the Vercel AI SDK with React, Svelte, Vue, and Solid frontends. To use useChat, first create an API route using Next.js. Here's where we'll call Inkeep. ### API Route ```tsx title="app/api/chat/route.ts" import { LinksTool } from "@/lib/chat/inkeep-qa-schema"; import { createOpenAI } from "@ai-sdk/openai"; import { streamText } from "ai"; export const runtime = "edge"; const openai = createOpenAI({ apiKey: process.env.INKEEP_API_KEY, baseURL: "https://api.inkeep.com/v1", }); export async function POST(req: Request) { const reqJson = await req.json(); const result = await streamText({ model: openai("inkeep-qa-sonnet-4"), messages: reqJson.messages.map((message: any) => ({ role: message.role, content: message.content, name: "inkeep-qa-user-message", id: message.id, })), tools: { // to get the citation information provideLinks: { ...LinksTool, }, }, toolChoice: "auto", }); return result.toAIStreamResponse(); } ``` ### Client ```tsx title="app/page.tsx" "use client"; import { useChat } from "ai/react"; export default function Page() { const { messages, isLoading, input, handleSubmit, handleInputChange } = useChat({ streamMode: "stream-data", sendExtraMessageFields: true, onResponse(response) { if (response.status === 401) { console.error(response.statusText); } }, }); return ( <> {messages.map((message) => (

{message.role === "user" ? "User: " : "AI: "} {message.content}

))} {isLoading &&

} ); } ``` ## Using Server Actions (AI SDK Actions) [`streamUI`](https://sdk.vercel.ai/docs/reference/ai-sdk-rsc/stream-ui) is another way to use the Vercel AI SDK, but with React Server Components. This lets you stream entire UI components, not just the text that is then parsed and rendered on the client. This example illustrates how to render assistant messages and a "sources" list provided by the `provideLinks` tool. ### Server Action ```tsx title="lib/chat/actions.ts" import "server-only"; import { createAI, getMutableAIState, streamUI } from "ai/rsc"; import { createOpenAI } from "@ai-sdk/openai"; import { Message } from "ai"; import { nanoid } from "./utils"; import { LinksTool } from "./inkeep-qa-schema"; const openai = createOpenAI({ apiKey: process.env.INKEEP_API_KEY, baseURL: "https://api.inkeep.com/v1", }); async function submitUserMessage(content: string) { "use server"; const aiState = getMutableAIState(); aiState.update({ ...aiState.get(), messages: [ ...aiState.get().messages, { id: nanoid(), role: "user", content, }, ], }); const answerMessageId = nanoid(); const result = await streamUI({ model: openai("inkeep-qa-sonnet-3-5"), messages: [ ...aiState.get().messages.map((message: any) => ({ role: message.role, content: message.content, name: "inkeep-qa-user-message", id: message.id, })), ], text: ({ content }) => { const assistantAnswerMessage = { id: answerMessageId, role: "assistant", content, name: "inkeep-qa-assistant-message", } as Message; const currentMessages = aiState.get().messages; const lastMessage = currentMessages[currentMessages.length - 1]; aiState.update({ ...aiState.get(), messages: lastMessage?.id === answerMessageId ? [...currentMessages.slice(0, -1), assistantAnswerMessage] : [...currentMessages, assistantAnswerMessage], }); return

{assistantAnswerMessage.content}

; }, tools: { provideLinks: { ...LinksTool, generate: async ({ links }) => { // render sources UI once tool is complete const currentMessages = aiState.get().messages; const lastMessage = currentMessages[currentMessages.length - 1]; const lastMessageWithToolResults = { ...lastMessage, toolInvocations: [ { toolName: "provideLinks", result: links, }, ], } as Message; aiState.done({ ...aiState.get(), messages: [ ...currentMessages.slice(0, -1), lastMessageWithToolResults, ], }); return

{lastMessageWithToolResults.content}

; }, }, }, toolChoice: "auto", }); return { id: nanoid(), display: result.value, }; } export type AIState = { chatId: string; messages: Message[]; }; export type UIState = { id: string; display: React.ReactNode; }[]; export const AI = createAI({ actions: { submitUserMessage, }, initialUIState: [], initialAIState: { chatId: nanoid(), messages: [] }, }); ``` ## Page.tsx ```tsx title="app/page.tsx" import { Chat } from "@/components/chat"; import { AI } from "@/lib/chat/actions"; import { nanoid } from "@/lib/chat/utils"; export default async function IndexPage() { const id = nanoid(); return ( ); } ``` ### Client ```tsx title="app/components/chat.tsx" "use client"; import { useUIState, useAIState, useActions } from "ai/rsc"; import { Message } from "ai"; import { UIState } from "@/lib/chat/actions"; import { nanoid } from "@/lib/chat/utils"; export interface ChatProps extends React.ComponentProps<"div"> { initialMessages?: Message[]; id?: string; } export function Chat({ id, className }: ChatProps) { const [messages] = useUIState(); return (

); } export interface ChatList { messages: UIState; } export function ChatList({ messages }: ChatList) { const [messagesUIState, setMessagesUIState] = useUIState(); const { submitUserMessage } = useActions(); const handleSubmit = async (e: any) => { e.preventDefault(); const form = e.currentTarget; const input = form.elements.namedItem("prompt") as HTMLInputElement; const value = input.value.trim(); if (!value) return; input.value = ""; // Clear the input after submission const userMessage = { id: nanoid(), content: value, role: "user", } as Message; // Optimistically add user message UI setMessagesUIState((currentMessages) => [ ...currentMessages, { id: nanoid(), display:

{userMessage.content}

, }, ]); // Submit and get response message const responseMessage = await submitUserMessage(value); setMessagesUIState((currentMessages) => [ ...currentMessages, responseMessage, ]); }; return ( <>

{messages.map((message) => (

{message.display}

))}

); } ``` *** sidebarTitle: OpenAI SDK title: Use the Question Answer API with the OpenAI SDK keywords: OpenAI SDK integration, chat completions, TypeScript implementation, streaming responses, tool calls, API examples, Node.js integration, QA API, response handling, link processing, API authentication, TypeScript SDK, OpenAI client, API streaming, tool functions, inkeep-qa, zod schema, JSON schema, environment variables, async streaming, tool call handling ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here's an example of how to use [Chat Completions](https://platform.openai.com/docs/guides/chat-completions) with one of Inkeep's `qa` models ```ts title="index.ts" import OpenAI from "openai"; import { z } from "zod"; import { zodToJsonSchema } from "zod-to-json-schema"; import { LinksToolSchema } from "./LinksToolSchema"; import dotenv from "dotenv"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } const client = new OpenAI({ baseURL: "https://api.inkeep.com/v1/", apiKey: process.env.INKEEP_API_KEY, // dangerouslyAllowBrowser: true, use this setting if you are using this in browser }); async function getResponseFromAI() { const result = await client.chat.completions.create({ model: "inkeep-qa-sonnet-4", messages: [{ role: "user", content: "How do I get started with Inkeep?" }], stream: true, tools: [ { type: "function", function: { name: "provideLinks", description: "Provides links", parameters: zodToJsonSchema( LinksToolSchema.extend({ text: z.string(), }) ), }, }, ], tool_choice: "auto", }); let toolCalls: any[] = []; for await (const chunk of result) { const c = chunk.choices[0]; process.stdout.write(c.delta.content || ""); if (c.delta?.tool_calls) { c.delta.tool_calls.forEach((toolCall) => { const existingCall = toolCalls[toolCall.index ?? 0]; if (existingCall) { // Update existing call if (toolCall.function) { existingCall.function = existingCall.function || {}; if (toolCall.function.name) existingCall.function.name = toolCall.function.name; if (toolCall.function.arguments) { existingCall.function.arguments = (existingCall.function.arguments || "") + toolCall.function.arguments; } } if (toolCall.type) existingCall.type = toolCall.type; } else { // Add new call toolCalls[toolCall.index ?? 0] = toolCall; } }); } } // Check if the function is called in the response if (toolCalls && toolCalls.length > 0) { const provideLinksCall = toolCalls.find( (call) => call.function.name === "provideLinks" ); if (provideLinksCall) { const functionArgs = JSON.parse(provideLinksCall.function.arguments); await provideLinks(functionArgs); } else { console.log("No provideLinks tool call found"); } } } const provideLinks = async ({ links, text, }: { links?: (typeof LinksToolSchema._type)["links"]; text: string; }) => { console.log("\nLinks used in response: ", links); return Promise.resolve(); }; getResponseFromAI(); ``` *** sidebarTitle: Custom Tool Calls title: Custom Tool Calls for the Question Answer API keywords: custom tool calls, AI assistant tools, function calling, OpenAI integration, tool schemas, API customization, answer confidence, sales detection, TypeScript implementation, API tools, tool definitions, schema validation, API examples, tool parameters, API integration, custom functions, tool automation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Inkeep's `inkeep-qa` API allows you to pass in custom tool calls to the AI assistant. You can use this to: - determine an answer's confidence and escalate to a human if needed - route, categorize, or label the question - trigger actions based on the content of a question or answer To effectively use tool calls, you should: 1. Define a clear semantic schema for the tool call arguments 2. Write detailed descriptions of each tool call and its intended use cases 3. Experiment with multiple test cases For more details on implementing function calling, see [this guide](https://platform.openai.com/docs/guides/function-calling?api-mode=chat) on tool calling. The examples below leverage the tool argument definitions found in the [Common Tools](/ui-components/tools/common-tool-schemas) guide. ## Single Tool Call You can provide a single tool definition to the AI assistant by passing a tool object to the `tools` array parameter in the `chat.completions.create` function. ```ts title="index.ts" import OpenAI from "openai"; import dotenv from "dotenv"; import { provideAnswerConfidenceSchema } from "./common-tool-schemas.ts"; import { zodToJsonSchema } from "zod-to-json-schema"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } const client = new OpenAI({ baseURL: "https://api.inkeep.com/v1/", apiKey: process.env.INKEEP_API_KEY, // dangerouslyAllowBrowser: true, use this setting if you are using this in browser }); const singleTool = [ { function: { name: "provideAnswerConfidence", description: "Determine how confident the AI assistant was and whether or not to escalate to humans.", parameters: zodToJsonSchema(provideAnswerConfidenceSchema), }, type: "function", }, ]; const completion = await client.chat.completions.create({ model: "inkeep-qa-expert", messages: [{ role: "user", content: "How do I get started?" }], tools: singleTool, }); console.log(completion.choices[0].message.tool_calls); ``` ## Multiple Tool Calls We can also combine multiple tool calls. The LLM will choose all relevant tools. If you'd like a tool to always be invoked, include that in the description of the tool. ```ts title="index.ts" import OpenAI from "openai"; import dotenv from "dotenv"; import { provideAnswerConfidenceSchema, detectedSalesSignal, } from "./common-tool-schemas.ts"; import { zodToJsonSchema } from "zod-to-json-schema"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } const client = new OpenAI({ baseURL: "https://api.inkeep.com/v1/", apiKey: process.env.INKEEP_API_KEY, // dangerouslyAllowBrowser: true, use this setting if you are using this in browser }); const completion = await client.chat.completions.create({ model: "inkeep-qa-expert", messages: [ { role: "user", content: "How much does your enterprise plan cost for a team of 50?", }, ], tools: [ { type: "function", function: { name: "provideAnswerConfidence", description: "Grade how confident the AI assistant was in its answer.", parameters: zodToJsonSchema(provideAnswerConfidenceSchema), }, }, { type: "function", function: { name: "detectSalesSignal", description: "Identify when users express interest in potentially purchasing a product.", parameters: zodToJsonSchema(detectedSalesSignal), }, }, ], }); console.log(completion.choices[0].message.tool_calls); ``` *** sidebarTitle: Vercel AI SDK title: Use the Context Mode API with the Vercel AI SDK keywords: context mode API, Vercel AI SDK, structured responses, streaming objects, TypeScript implementation, custom copilots, AI workflows, step-by-step instructions, API integration, OpenAI compatibility, LLM applications, dynamic UI, conversational AI, API examples, context-aware AI ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- With the Inkeep `context` mode, you can leverage all of the capabilities provided by a normal OpenAI API endpoint but "grounded" with context about your product. This gives you the full flexibility of creating any LLM application: custom copilots, AI workflows, etc., all backed by your own data. Structured data can be particularly powerful in rendering dynamic UI components as part of a conversational experience. As a basic example, instead of having a support bot that answers with a single `content` payload, we can instead define a response to be returned as a series of structured steps. The example shown below illustrates how to accomplish that with [streamObject](https://sdk.vercel.ai/docs/reference/ai-sdk-core/stream-object) and Inkeep's `context` model. ```ts title="index.ts" import { z } from "zod"; import { streamObject } from "ai"; import { createOpenAI } from "@ai-sdk/openai"; import dotenv from "dotenv"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } const openai = createOpenAI({ apiKey: process.env.INKEEP_API_KEY, baseURL: "https://api.inkeep.com/v1", }); const StepSchema = z.object({ steps: z.array( z.object({ step: z.string(), description: z.string(), }) ), }); async function getResponseFromAI() { const result = await streamObject({ model: openai("inkeep-context-sonnet-4"), schema: StepSchema, messages: [ { role: "system", content: "Generate step-by-step instructions to answer the user question about Inkeep only based on the information sources. Break it down to be as granular as possible. Always generate more than one step.", }, ], }); const { partialObjectStream } = result; for await (const partialObject of partialObjectStream) { console.clear(); console.log(partialObject.steps); } } getResponseFromAI(); ``` *** sidebarTitle: HTTP Request title: Call the Inkeep RAG API with an HTTP Request keywords: RAG API, HTTP request, API documentation, JSON response format, document retrieval, knowledge base integration, API endpoints, content schema, source types, API examples, curl commands, response processing, document structure, API authentication, content formatting, REST API, API integration, document sources, API response handling ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Inkeep RAG API provides structured documents from your knowledge base. This page shows how to make direct HTTP requests to the API. Please ensure you have an API key (don't have one? [Get one here](https://docs.inkeep.com/ai-api/chat-completions-api#get-an-api-key)). ## Request Format ```json POST https://api.inkeep.com/v1/chat/completions Content-Type: application/json Authorization: Bearer YOUR_INKEEP_API_KEY { "model": "inkeep-rag", "messages": [ { "role": "user", "content": "How do I get started?" } ], "response_format": { "type": "json_object" } } ``` ## Response Format ```json { "id": "chatcmpl-123abc", "object": "chat.completion", "created": 1677858242, "model": "inkeep-rag", "choices": [ { "message": { "role": "assistant", "content": "{\"content\":[{\"type\":\"document\",\"record_type\":\"Documentation\",\"url\":\"https://docs.inkeep.com/ui-components/js-snippet/in-page/embedded-search-and-chat\",\"title\":\"Embedded Search and Chat (JS) - Inkeep\",\"source\":{\"type\":\"content\",\"content\":[{\"type\":\"text\",\"text\":\"## Quick start\\n\\nAdd the below `\n```" } ] } ```` ## Processing the Response To process the response, you'll need to: 1. Parse the JSON response 2. Extract the `content` field from the `message.content` JSON string 3. Process each document in the `content` array This will give you structured access to the documents retrieved from your knowledge base. *** sidebarTitle: Vercel AI SDK title: Using the Inkeep RAG API with the Vercel AI SDK keywords: Vercel AI SDK, RAG API integration, TypeScript implementation, Zod schema validation, structured data retrieval, knowledge base integration, API examples, document processing, Vercel integration, Next.js integration, API authentication, TypeScript types, schema definition, RAG documents, API response handling, structured output --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Using the Vercel AI SDK with Inkeep's RAG API The Inkeep RAG API provides structured documents from your knowledge base. This example shows how to use the Vercel AI SDK to retrieve these documents. Please ensure you have an API key (don't have one? [Get one here](https://docs.inkeep.com/ai-api/chat-completions-api#get-an-api-key)). ### Schema Definition ```tsx title="inkeep-rag-schema.ts" import { generateObject } from "ai"; import { z } from "zod"; import dotenv from "dotenv"; import { createOpenAI } from "@ai-sdk/openai"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } export const provider = createOpenAI({ baseURL: "https://api.inkeep.com/v1/", apiKey: process.env.INKEEP_API_KEY, }); /* Inkeep RAG Document Schema */ export const InkeepSourceContentSchema = z .object({ type: z.union([z.literal("text"), z.string()]), media_type: z.union([z.literal("text/plain"), z.string()]).optional(), text: z.string().optional(), data: z.string().optional(), }) .passthrough(); export const InkeepSourceSchema = z .object({ content: z.array(InkeepSourceContentSchema).optional(), type: z.union([z.literal("content"), z.string()]).optional(), media_type: z.string().optional(), data: z.string().optional(), }) .passthrough(); const InkeepRecordTypes = z.enum([ "documentation", "site", "discourse_post", "github_issue", "github_discussion", "stackoverflow_question", "discord_forum_post", "discord_message", "custom_question_answer", ]); export const InkeepRAGDocumentSchema = z .object({ type: z.string(), source: InkeepSourceSchema, title: z.string().optional(), context: z.string().optional(), record_type: z.union([z.string(), InkeepRecordTypes]).optional(), url: z.string().optional(), }) .passthrough(); export const InkeepRAGResponseSchema = z .object({ content: z.array(InkeepRAGDocumentSchema), }) .passthrough(); export type InkeepSourceContent = z.infer; export type InkeepSource = z.infer; export type InkeepRAGDocument = z.infer; export type InkeepRAGResponse = z.infer; ``` ### Simple Example ```tsx title="index.ts" import { createOpenAI } from "@ai-sdk/openai"; import { z } from "zod"; import dotenv from "dotenv"; import fetch from "node-fetch"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } // Initialize OpenAI client with Inkeep's base URL const provider = createOpenAI({ apiKey: process.env.INKEEP_API_KEY, baseURL: "https://api.inkeep.com/v1", }); // Define the RAG document schema const InkeepSourceContentSchema = z .object({ type: z.union([z.literal("text"), z.string()]), media_type: z.union([z.literal("text/plain"), z.string()]).optional(), text: z.string().optional(), data: z.string().optional(), }) .passthrough(); const InkeepSourceSchema = z .object({ content: z.array(InkeepSourceContentSchema).optional(), type: z.union([z.literal("content"), z.string()]).optional(), media_type: z.string().optional(), data: z.string().optional(), }) .passthrough(); const InkeepRAGDocumentSchema = z .object({ type: z.string(), source: InkeepSourceSchema, title: z.string().optional(), context: z.string().optional(), record_type: z.string().optional(), url: z.string().optional(), }) .passthrough(); const InkeepRAGResponseSchema = z .object({ content: z.array(InkeepRAGDocumentSchema), }) .passthrough(); const { object } = await generateObject({ model: provider.languageModel("inkeep-rag"), messages: [{ role: "user", content: "How do I get started?" }], schema: InkeepRAGResponseSchema, mode: "json", }); // Process the RAG documents object.content.forEach((doc, index) => { console.log(`Document ${index + 1}:`); console.log(`Title: ${doc.title || "N/A"}`); console.log(`URL: ${doc.url || "N/A"}`); console.log(`Context: ${doc.context || "N/A"}`); console.log(`Record Type: ${doc.record_type || "N/A"}`); console.log("---"); }); ``` This example demonstrates how to use the Vercel AI SDK to retrieve structured RAG documents from Inkeep's knowledge base. The response includes an array of documents with context, source information, and URLs. *** sidebarTitle: OpenAI SDK title: Using the Inkeep RAG API with the OpenAI SDK keywords: OpenAI SDK, RAG implementation, TypeScript integration, Zod validation, structured output, API integration, knowledge base, document retrieval, schema validation, OpenAI client, API examples, TypeScript SDK, document processing, API response parsing, Node.js integration, RAG documents, API authentication, structured data -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Here's an example of how to use [Structured Output Parsing](https://platform.openai.com/docs/guides/structured-output) with Inkeep's `rag` model to retrieve structured documents from your knowledge base. Please ensure you have an API key (don't have one? [Get one here](https://docs.inkeep.com/ai-api/chat-completions-api#get-an-api-key)). ## Example ```ts title="index.ts" import OpenAI from "openai"; import { z } from "zod"; import dotenv from "dotenv"; import { zodResponseFormat } from "openai/helpers/zod"; dotenv.config(); if (!process.env.INKEEP_API_KEY) { throw new Error("INKEEP_API_KEY is required"); } const client = new OpenAI({ baseURL: "https://api.inkeep.com/v1/", apiKey: process.env.INKEEP_API_KEY, // dangerouslyAllowBrowser: true, use this setting if you are using this in browser }); // Define the RAG document schema const InkeepSourceContentSchema = z .object({ type: z.union([z.literal("text"), z.string()]), media_type: z.union([z.literal("text/plain"), z.string()]).optional(), text: z.string().optional(), data: z.string().optional(), }) .passthrough(); const InkeepSourceSchema = z .object({ content: z.array(InkeepSourceContentSchema).optional(), type: z.union([z.literal("content"), z.string()]).optional(), media_type: z.string().optional(), data: z.string().optional(), }) .passthrough(); const InkeepRecordTypes = z.enum([ "documentation", "site", "discourse_post", "github_issue", "github_discussion", "stackoverflow_question", "discord_forum_post", "discord_message", "custom_question_answer", ]); const InkeepRAGDocumentSchema = z .object({ type: z.string(), source: InkeepSourceSchema, title: z.string().optional(), context: z.string().optional(), record_type: z.union([z.string(), InkeepRecordTypes]).optional(), url: z.string().optional(), }) .passthrough(); const InkeepRAGResponseSchema = z .object({ content: z.array(InkeepRAGDocumentSchema), }) .passthrough(); const completion = await client.beta.chat.completions.parse({ model: "inkeep-rag", messages: [{ role: "user", content: "How do I get started?" }], response_format: zodResponseFormat(InkeepRAGResponseSchema, "rag"), }); const validationResult = completion.choices[0].message.parsed; console.log("Schema validation successful!"); // Process the RAG documents validationResult.content.forEach((doc, index) => { console.log(`Document ${index + 1}:`); console.log(`Title: ${doc.title || "N/A"}`); console.log(`URL: ${doc.url || "N/A"}`); console.log(`Context: ${doc.context || "N/A"}`); console.log(`Record Type: ${doc.record_type || "N/A"}`); console.log("---"); }); ``` This example demonstrates how to use the OpenAI Node SDK to retrieve structured RAG documents from Inkeep's knowledge base. The response includes an array of documents with context, source information, and URLs. *** sidebarTitle: Overview title: MCP Server Overview icon: IoSparklesOutline ----------------------- Inkeep provides multiple ways to integrate with Model Context Protocol (MCP) clients like Claude Desktop, Cursor, and Windsurf. Choose the option that best fits your needs. ## What is MCP? Model Context Protocol (MCP) allows AI assistants to access external tools and data sources. With Inkeep's MCP integration, you can give your AI assistant access to your knowledge base for answering questions and searching documentation. ## Choose Your Integration ### 1. Managed MCP Server (Recommended) **Best for**: Teams who want to get started quickly without managing infrastructure. Inkeep provides a fully managed MCP server that's ready to use with your existing knowledge base. No deployment or maintenance required. * **Zero setup**: Works with your existing Inkeep project * **Automatic updates**: Always has the latest features * **Built-in analytics**: Tracks usage and performance * **Enterprise ready**: Scales with your team *Recommended for most users* [Get started with Managed MCP Server →](/mcp/managed) *** ### 2. Self-Hosted Options **Best for**: Teams who need custom control or want to integrate with existing infrastructure. We provide open-source templates for deploying your own MCP server. These templates include the same core functionality as our managed server but give you full control over deployment and customization. Choose your deployment platform: * [Deploy on Vercel](/mcp/vercel-deployment) * [Deploy on Cloudflare Workers](/mcp/cloudflare-deployment) *** ### 3. Extend Your Existing MCP Server **Best for**: Teams who already have an MCP server and want to add Inkeep's tools to it. If you have an existing MCP server that you want to extend with Inkeep's question-answering and search capabilities, you can use our tool implementations as a reference. Check out our deployment templates to see how we implement the Inkeep MCP tools: * [Vercel deployment guide](/mcp/vercel-deployment) * [Cloudflare Workers deployment guide](/mcp/cloudflare-deployment) You can adapt these patterns to add the same functionality to your existing server. *** ## Available Tools Your MCP server automatically includes these tools based on your knowledge base: | Tool Name | Description | Use Case | | ----------------------------------- | ------------------------------------------ | ---------------------------------------- | | `ask-question-about-{product-name}` | AI-powered Q\&A using your knowledge base | Get direct answers to specific questions | | `search-{product-name}-docs` | Semantic search through your documentation | Find relevant content and context | *** ## Next Steps **Ready to get started?** 1. **Quick Start**: Use our [Managed MCP Server](/mcp/managed) for immediate setup 2. **Custom Deployment**: Try [Vercel](/mcp/vercel-deployment) or [Cloudflare Workers](/mcp/cloudflare-deployment) for easy self-hosting **Need help?** [Contact support](https://inkeep.com/contact) *** ## Supported MCP Clients Inkeep's MCP servers work with any MCP-compatible client: * **[Cursor](https://cursor.sh)** - AI-powered code editor * **[Claude Desktop](https://claude.ai/desktop)** - Anthropic's desktop application * **[Windsurf](https://windsurf.ai)** - AI development environment * **Custom clients** - Any application implementing the MCP protocol *** *** sidebarTitle: Managed title: Managed MCP Server icon: IoCloudOutline -------------------- **Best for**: Teams who want to get started quickly without managing infrastructure. Inkeep provides a fully managed MCP server that's ready to use with your existing knowledge base. No deployment or maintenance required. * **Zero setup**: Works with your existing Inkeep project * **Automatic updates**: Always has the latest features * **Built-in analytics**: Tracks usage and performance * **Enterprise ready**: Scales with your team ## Setup Steps 1. **Create an MCP Assistant** * Log in to the [Inkeep Dashboard](https://portal.inkeep.com) * Navigate to **Projects** → Select your project * Open the **Assistants** tab * Click **Create assistant** → Choose **MCP** * Enter a name and click **Create** 2. **Configure Your MCP Client** **Important**: Replace `YOUR_MCP_SERVER_URL` with the actual URL from your MCP Assistant page. **Cursor Example:** ```json title=".cursor/mcp.json" { "mcpServers": { "Inkeep MCP": { "url": "YOUR_MCP_SERVER_URL" } } } ``` **Claude Desktop Example:** ```json title="claude_desktop_config.json" { "mcpServers": { "inkeepMcp": { "command": "npx", "args": ["-y", "mcp-remote", "YOUR_MCP_SERVER_URL"] } } } ``` ## Available Tools Your MCP server automatically includes these tools based on your knowledge base: | Tool Name | Description | Use Case | | ----------------------------------- | ------------------------------------------ | ---------------------------------------- | | `ask-question-about-{product-name}` | AI-powered Q\&A using your knowledge base | Get direct answers to specific questions | | `search-{product-name}-docs` | Semantic search through your documentation | Find relevant content and context | ## Analytics & Insights All interactions through the managed MCP server are automatically logged to your Inkeep analytics dashboard, giving you insights into: * Most common questions * Content gaps * Usage patterns * Performance metrics ## Examples in Action ### Basic Q\&A ``` User: "How do I configure rate limiting?" Assistant: [Uses ask-question-about-inkeep tool] Response: "Rate limiting in Inkeep can be configured..." ``` ### Documentation Search ``` User: "Find information about API authentication" Assistant: [Uses search-inkeep-docs tool] Response: "Here are the relevant sections about API authentication..." ``` *** **Need help?** [Contact support](https://inkeep.com/contact) *** sidebarTitle: Vercel Deployment title: Deploy MCP Server on Vercel icon: TbBrandVercel ------------------- Deploy your own AI-powered MCP server on Vercel with automatic conversation logging and analytics integration. ## Overview This self-hosted option gives you full control over your MCP server while leveraging Vercel's serverless infrastructure. ### Key Features * **Ready-to-deploy**: Drop-in MCP server with Vercel integration * **AI-powered tools**: Q\&A and documentation search using Inkeep's models * **Inkeep Analytics integration**: Automatic conversation logging for insights * **Scalable**: Leverages Vercel's serverless infrastructure * **Custom domains**: Use your own domain for the MCP server * **Environment variables**: Secure configuration management *** ## Quick Start **[View the complete template on GitHub →](https://github.com/inkeep/mcp-for-vercel)** All setup instructions, configuration details, and deployment steps are in the repository README. The template provides a complete MCP server implementation ready to deploy: ```bash git clone https://github.com/inkeep/mcp-for-vercel cd mcp-for-vercel npm install vercel --prod ``` *** ## Implementation Example Below is a snippet of the server tool that calls the `inkeep-qa-expert` model: ```typescript title="app/[transport]/route.ts" server.tool( qaToolName, qaToolDescription, { question: z.string().describe('Question about the product') }, { title: `Ask AI about ${INKEEP_PRODUCT_NAME}`, readOnlyHint: true, openWorldHint: true, }, async ({ question }: { question: string }) => { try { const qaModel = 'inkeep-qa-expert'; const response = await openai.chat.completions.create({ model: qaModel, messages: [{ role: 'user', content: question }], }); const qaResponse = response.choices?.[0]?.message?.content; if (qaResponse) { await logToInkeepAnalytics({ messagesToLogToAnalytics: [ { role: 'user', content: question }, { role: 'assistant', content: qaResponse }, ], }); return { content: [ { type: 'text' as const, text: qaResponse, }, ], }; } return { content: [] }; } catch (error) { console.error('Error getting QA response:', error); return { content: [] }; } }, ); ``` *** ## MCP Client Setup After deploying, configure your MCP client to use your Vercel deployment: **Cursor:** ```json title=".cursor/mcp.json" { "mcpServers": { "Inkeep Custom": { "url": "https://your-app.vercel.app/mcp" } } } ``` **Claude Desktop:** ```json title="claude_desktop_config.json" { "mcpServers": { "inkeep-custom": { "command": "npx", "args": ["-y", "mcp-remote", "https://your-app.vercel.app/mcp"] } } } ``` *** **Need help?** [Contact support](https://inkeep.com/contact) *** sidebarTitle: Cloudflare Deployment title: Deploy MCP Server on Cloudflare Workers icon: TbBrandCloudflare ----------------------- Deploy a Model Context Protocol server to Cloudflare Workers with semantic search and Q\&A capabilities. ## Overview This self-hosted option deploys your MCP server to Cloudflare's infrastructure. ### Key Features * **Semantic search**: RAG-powered search through your knowledge base * **AI Q\&A**: Direct answers from an AI assistant trained on your content * **Inkeep Analytics integration**: Logs interactions for insights and improvements * **Serverless**: No server management required * **Custom domains**: Use your own domain with Cloudflare *** ## Quick Start **[View the complete template on GitHub →](https://github.com/inkeep/mcp-for-cloudflare)** All setup instructions, configuration details, and deployment steps are in the repository README. The template provides a complete MCP server implementation ready to deploy: ```bash git clone https://github.com/inkeep/mcp-for-cloudflare cd mcp-for-cloudflare npm install wrangler secret put INKEEP_API_KEY wrangler deploy ``` *** ## Implementation Example Below is a snippet of the server tool that calls the `inkeep-qa-expert` model. ```typescript title="src/index.ts" // Q&A tool using inkeep-qa-expert model const qaTool = this.server.tool( "ask-question-about-inkeep", { question: z.string().describe("Question about the product") }, async ({ question }) => { const openai = new OpenAI({ baseURL: INKEEP_API_BASE_URL, apiKey: INKEEP_API_KEY }); const resp = await openai.chat.completions.create({ model: "inkeep-qa-expert", messages: [ { role: "system", content: "You are an AI assistant knowledgeable about Inkeep." }, { role: "user", content: question }, ], }); const answer = resp.choices?.[0]?.message?.content; return answer ? { content: [{ type: "text", text: answer }] } : { content: [] }; }, ); ``` *** ## MCP Client Setup Configure your MCP client to use your Cloudflare Workers deployment: **Cursor:** ```json title=".cursor/mcp.json" { "mcpServers": { "Inkeep Cloudflare": { "url": "https://your-worker-name.your-subdomain.workers.dev/mcp" } } } ``` **Claude Desktop:** ```json title="claude_desktop_config.json" { "mcpServers": { "inkeep-cf": { "command": "npx", "args": ["-y", "mcp-remote", "https://your-worker-name.your-subdomain.workers.dev/mcp"] } } } ``` *** **Need help?** [Contact support](https://inkeep.com/contact) *** title: Add analytics to any OpenAI compatible chat sidebarTitle: Overview keywords: chat analytics, OpenAI integration, conversation tracking, user feedback, analytics API, conversation logging, chat monitoring, feedback collection, conversation history, API integration, chat metrics, analytics dashboard, conversation data, chat feedback, API implementation, conversation storage, chat reporting ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- With Inkeep's Analytics API, you can log your AI chat conversations to: 1. Get Inkeep's analytics and reporting for the chats 2. Provide and track "Thumbs up/down" feedback 3. Power "Share" or "Saved Chats" experiences The Inkeep Analytics API is designed to be flexible and can log any OpenAI-compatible conversation, including those with tool calls or custom functionality. If you're using [Inkeep's Chat API](/ai-api/chat-completions-api) to create your own chat UX or custom copilot, you should use the Analytics API to enable the same reporting as provided by the `@inkeep/cxkit-react` component library. ## Authentication All Analytics API endpoints require authentication using an API key in the request headers. See our [Authentication Page](/analytics-api/authentication) for details. ## Log a conversation ### Initial message To log a new conversation, make a POST request to the `/conversations` endpoint. ```javascript const initialConversationData = { id: "conv_1234", // optional type: "openai", messages: [ { role: "user", content: "Can I log any OpenAI-compatible conversation?", }, { role: "assistant", content: "Yes, our analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint.", }, ], properties: { // Add any custom properties here }, userProperties: { // Add any user-specific properties here }, }; let currentConversation = await fetch( "https://api.analytics.inkeep.com/conversations", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify(initialConversationData), } ).then((response) => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.json(); }); console.log(currentConversation); ``` ### Follow-up messages To log additional messages in an existing conversation, include the `id` returned from the initial submission: ```javascript const continueConversationData = { id: currentConversation.id, type: "openai", messages: [ ...currentConversation.messages, // Add new messages { role: "user", content: "Does that mean it supports logging tool calls?", }, { role: "assistant", content: "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completions endpoints, including tool calling.", }, ], }; currentConversation = await fetch( "https://api.analytics.inkeep.com/conversations", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify(continueConversationData), } ).then((response) => { if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } return response.json(); }); console.log(currentConversation); ``` You can provide your own IDs for conversations and messages, or Inkeep will auto-generate them. For logging continuous exchanges in a conversation, make sure to retain and use the same conversation ID and always include the entire message history. `POST /conversation` works like an upsert operation. ## Submit feedback Use the `/feedback` endpoint to log 👍 / 👎 feedback from your UI. ```javascript const feedbackData = { type: "positive", // or "negative" messageId: "{assistant_message_id}", // e.g. currentConversation.messages[1].id reasons: [ { label: "accurate_code_snippet", details: "The code worked perfectly.", }, ], userProperties: { // Add any user-specific properties here }, }; fetch("https://api.analytics.inkeep.com/feedback", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify(feedbackData), }) .then((response) => response.json()) .then((data) => console.log(data)); ``` ## Monitor To view analytics for your logged conversations and feedback: 1. Go to [portal.inkeep.com](https://portal.inkeep.com) 2. Navigate to **Projects** and select the relevant one 3. View the **Chat Sessions**, **Insights**, and **Analytics** tabs ## Use for "Share" or "Saved Chats" You can use the `GET /conversations` endpoint to retrieve logged conversations and power "Share" or "Saved Chats" features. Here's an example of how to fetch a specific conversation: ```ts fetch( "https://api.analytics.inkeep.com/conversations/{existing_conversation_id}", { method: "GET", headers: { Authorization: "Bearer YOUR_API_KEY", }, } ) .then((response) => response.json()) .then((data) => { // Use the conversation data to rehydrate your UI console.log(data); }); ``` The response will contain detailed information about the conversation: ```json { "id": "conv_123456789", "type": "openai", "createdAt": "2024-07-11T10:15:30.123Z", "updatedAt": "2024-07-11T10:16:45.678Z", "projectId": "proj_987654321", "integrationId": "intg_246813579", "properties": { "source": "web_chat" }, "userProperties": { "userId": "user_135792468" }, "messages": [ { "id": "msg_1", "type": "openai", "conversationId": "conv_123456789", "createdAt": "2024-07-11T10:15:30.123Z", "updatedAt": "2024-07-11T10:15:30.123Z", "role": "user", "content": "Can I log any OpenAI-compatible conversation?", "name": null, "links": null, "properties": {}, "userProperties": {} }, { "id": "msg_2", "type": "openai", "conversationId": "conv_123456789", "createdAt": "2024-07-11T10:15:40.456Z", "updatedAt": "2024-07-11T10:15:40.456Z", "role": "assistant", "content": "Yes, our analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint.", "name": null, "links": null, "properties": {}, "userProperties": {} }, { "id": "msg_3", "type": "openai", "conversationId": "conv_123456789", "createdAt": "2024-07-11T10:16:15.789Z", "updatedAt": "2024-07-11T10:16:15.789Z", "role": "user", "content": "Does that mean it supports logging tool calls?", "name": null, "links": null, "properties": {}, "userProperties": {} }, { "id": "msg_4", "type": "openai", "conversationId": "conv_123456789", "createdAt": "2024-07-11T10:16:45.678Z", "updatedAt": "2024-07-11T10:18:45.678Z", "role": "assistant", "content": "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completion endpoints, including tool calling.", "name": null, "links": null, "properties": {}, "userProperties": {} } ], "messagesOpenAIFormat": [ { "role": "user", "content": "Can I log any OpenAI-compatible conversation?" }, { "role": "assistant", "content": "Yes, Inkeep's analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint." }, { "role": "user", "content": "Does that mean it supports logging tool calls?" }, { "role": "assistant", "content": "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completions endpoints, including tool calling." } ] } ``` This response includes all extended details about the conversation and its messages, including any properties you associated with it. The `messagesOpenAIFormat` property provides the messages of the conversation in a format compatible with OpenAI's chat completions API. You can use this to implement **Share a chat**, **Saved Chats**, or any other functionality that requires retrieving an existing chat. Here's how: * **Share a chat** - Create an entry point in your application or UI that parses a query parameter, e.g. `?chatId=`. Then, use the `GET /conversations/{id}` endpoint to get the last state of a conversation and hydrate the chat UI in your own application. If you want to be able to "fork" shared chats, then simply use a different `id` when logging the continuation of a shared conversation to `POST /conversations`. This will log it as a separate conversation from the original. * **Saved Chats** - Whenever a user creates a new conversation, associate that `id` with the user in your database or application. This way, you have a relationship of `chats<>user` and can display a user's history in your UI. You can also store that relationship in a user's browser session for unauthenticated contexts. ## Log usage events In addition to logging conversations and feedback, you can also track specific usage events related to conversations or messages using the `/events` endpoint. For example, you may want to track events like: * `message:copied`: When a user copies a message * `message:code_snippet:copied`: When a user runs a code snippet from a message * `conversation:shared`: When a user shares a conversation When logged, they will be incorporated in the Inkeep Analytics reporting. The below shows an example of how to log these events. ```js title="log-event.js" // Message event const eventData = { type: "message:copied", entityType: "message" // 'message' or 'conversation' messageId: "{message_id}", }; fetch('https://api.analytics.inkeep.com/events', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify(eventData) }) .then(response => response.json()) .then(data => console.log(data)); // Conversation Event const conversationEventData = { type: "conversation:shared", entityType: "conversation" conversationId: "{conversation_id}", }; fetch('https://api.analytics.inkeep.com/events', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify(conversationEventData) }) .then(response => response.json()) ``` ## Concepts This glossary defines the key objects and concepts used throughout the Inkeep Analytics API and explains how they relate to each other. ### Conversation A conversation represents a series of messages between a user and an AI assistant. Conversations are the primary unit for tracking chat interactions in the Analytics API. Each conversation contains multiple messages and can receive feedback from users. Conversations can be grouped into semantic threads based on their topical similarity. ### Message A message represents a single interaction within a conversation, either from a user or the assistant. Messages are contained within conversations and can individually receive feedback. Users can perform various actions on messages (like copying), which are tracked as events. ### Feedback Feedback captures user reactions to assistant messages, typically in the form of thumbs up/down reactions with optional explanations. Feedback is associated with specific messages and helps improve the quality of responses over time. ### Event Events track specific user interactions with the Analytics API, such as copying a message, sharing a conversation, or clicking on a source. Events are always associated with either a message or a conversation entity and help analyze user engagement patterns. ### Query Queries allow for retrieving and analyzing analytics data stored in the system. There are several types of queries: * **Conversation queries**: Retrieve conversation data * **Event queries**: Access logged events * **Semantic thread queries**: Retrieve semantically linked conversation threads ### Properties / User Properties Custom properties can be attached to Analytics API objects for filtering and segmentation. These properties allow for flexible data organization and analysis across conversations, messages, and other entities. ### SemanticThread A semantic thread is a set of one or more related conversations grouped by semantic meaning rather than by converstion ID or timestamp. Threads connect conversations that discuss similar topics, allowing for analysis of user interests and common questions across multiple interactions. ### Project The organizational unit that groups analytics data in the Inkeep system. Projects contain conversations, messages, and all related analytics data, typically corresponding to a specific integration or implementation. *** title: "Authentication" sidebarTitle: "Authentication" icon: "LuLock" description: "How to authenticate with the Inkeep Analytics API" keywords: "authentication, API key, auth, bearer token, authorization header, authorization, api key generation, security" -------------------------------------------------------------------------------------------------------------------------- ## Authentication All Analytics API endpoints require authentication using an API key provided in the request headers. ### Authentication Header Include your API key in the `Authorization` header of each request using Bearer token authentication: ```javascript headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" } ``` ### API Key Generation ## Get an API key 1. Log in to the [Inkeep Dashboard](https://portal.inkeep.com) 2. Navigate to the **Projects** section and select your project 3. Open the **Assistants** tab 4. Click **Create assistant** and choose **API** from the options 5. Enter a Name for your new API assistant. 6. Click on **Create** 7. A generated **API key** will appear that you can use to authenticate API requests. ### API Key Access Levels API keys have different access levels depending on the assistant type: * **API Integration Keys**: Provide both read and write access to the Analytics API * **Other Integration Keys**: Some assistant types may have restricted access (write-only access) Always use an API Integration key for full access to all Analytics API functionalities. #### Assistant Types and Access Levels | Assistant Type | Access Level | Description | | ------------------- | :----------: | ---------------------------------------------------------------- | | API (Server-side) | Full Access | Can both send and retrieve data from all Analytics API endpoints | | Web (Docs, Website) | Write Only | Can only send data, cannot retrieve analytics | | Slack | Write Only | Limited to sending conversation data | | Support Copilot | Write Only | Can only log support interactions | | Discord | Write Only | Limited to logging community conversations | | MCP | Write Only | Limited to sending platform-specific data | ### Project Scoping All API keys are scoped to the specific project in which they were created. An API key cannot be used to access data from other projects. This ensures proper security isolation between different projects in your Inkeep account. ### Security Best Practices When using the API key in your applications: 1. **Never expose the API key** in client-side code 2. **Use environment variables** to store the key securely ### Rate Limiting The API implements rate limiting to prevent abuse. If you exceed the rate limits, you may receive a `429 Too Many Requests` response. Implementation details vary based on your usage plan. For more information on API access or issues with authentication, contact Inkeep support. *** title: Log Conversation description: >- Logs a new conversation or updates an existing one with new messages. Always include all messages. **API Key Types:** `WEB`, `API` full: true \_openapi: method: POST route: /conversations toc: \[] structuredData: headings: \[] contents: * content: >- Logs a new conversation or updates an existing one with new messages. Always include all messages. **API Key Types:** `WEB`, `API` *** {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Get All Conversations full: true \_openapi: method: GET route: /conversations toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Delete Conversation full: true \_openapi: method: DELETE route: /conversations/{id} toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Get All Feedback full: true \_openapi: method: GET route: /feedback toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Get Feedback by ID full: true \_openapi: method: GET route: /feedback/{id} toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Log Feedback description: |- Logs new feedback or updates an existing one. **API Key Types:** `WEB`, `API` full: true \_openapi: method: POST route: /feedback toc: \[] structuredData: headings: \[] contents: * content: |- Logs new feedback or updates an existing one. **API Key Types:** `WEB`, `API` *** {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Log Event full: true \_openapi: method: POST route: /events toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Query Conversations full: true \_openapi: method: POST route: /query/conversations toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Query Events full: true \_openapi: method: POST route: /query/events toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Query Feedback full: true \_openapi: method: POST route: /query/feedback toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Query Semantic Threads full: true \_openapi: method: POST route: /query/semantic-threads toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Export Semantic Threads Query Results full: true \_openapi: method: POST route: /query/semantic-threads/export toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Query Property Keys full: true \_openapi: method: POST route: /query/property-keys toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Query Property Values full: true \_openapi: method: POST route: /query/property-values toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Top Search Queries full: true \_openapi: method: GET route: /query/top-search-queries toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: Weekly Search Users full: true \_openapi: method: GET route: /query/weekly-search-users toc: \[] structuredData: headings: \[] contents: \[] ------------- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} *** title: "Pricing" keywords: "pricing plans, sandbox access, usage limits, free trial, AI search, neural search, spam protection, bot protection, white labeling, open source pricing, subscription management, billing options, enterprise pricing, service tiers" ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Can't find an answer? Reach out to [sales@inkeep.com](mailto:sales@inkeep.com?subject=Question). We aim to account for your expected usage in the pricing we quote you. If you're using a self-serve plan and your usage exceeds typical usage patterns, we'll communicate with your team to find pricing that makes sense for your scenario. Note that we monitor usage patterns to ensure fair use and maintain service quality for all customers. While we don't have a free tier, we do offer a free demo on your own content. To get one [schedule a call](https://inkeep.com/demo-form?cta_id=nav_demo_cta). Our team will have a sandbox prepared for you powered by your public content, in addition to reviewing your use case and answering any questions. Our team will provide that sandbox as a sharable link after the call, and with it you can try out the UI components and chat service against your own content without creating an account or providing a payment method. The sandbox will be available for 30 days after the call. To get access to the full platform, including the dashboard, analytics, AI assistant for Slack, and other features, we'll work with you to scope a pilot for your use case. A "search" refers to a traditional search query -- a user enters a few words or a phrase, and Inkeep returns a list of relevant documents. Our search service is available if you (optionally) use our Search Bar component or via our API. Unlimited searches are included in any plan. Our AI search is powered by proprietary neural net and lexical search algorithms that deliver fast, highly relevant out of the box search results without any tuning. Our AI search is part of our "RAG" system we use to feed relevant content to large language models to power our "Ask AI" chat experience. {" "} We use a variety of mechanisms to protect our service against malicious or miscellaneous usage. For example, we set dynamic IP-level or organization-level throttling to prevent against volume-based attacks. Further, we smartly detect if there is a surge of questions that seem out of the ordinary from your company's typically usage patterns. We strive to mitigate against these attack vectors and have not yet had downtime or cost issues related to malicious usage. If you're particularly keen on enforcing your protection mechanisms, we can work with you to [add authentication](/ui-components/customization-guides/authenticate-users), add a CAPTCHA service, send usage through your own proxy, or in general find a solution that meets your requirements. {" "} By default, the terms of all of our plans ask that customers keep the Inkeep branding in our UI components. If you require a white labeled solution, it can be offered as an add-on to enterprise plans. {" "} We don't currently offer a free tier for open source projects. {" "} We do not currently support multi-tenant or reseller/vendor scenarios. Log in to the [Inkeep Dashboard](https://portal.inkeep.com) and navigate to the **Billing** tab underneath **Organization**. Click on the **Manage Billing** button which will take you to the Stripe subscription management page. In some cases, if you signed up with specific promotions or you have an Enterprise agreement with Inkeep, Stripe billing management may not be available. For those cases, please email [billing@inkeep.com](mailto:billing@inkeep.com?subject=Cancel%20Subscription). **Note**: We're always on the look out for feedback and insights shared with us so we can take it into consideration as we build our roadmap. Please do feel free to share any feedback you have on how Inkeep did or did not fit your scenario. *** title: Features keywords: language support, self hosting, open source, image support, video content, multilingual support, content ingestion, documentation features, platform capabilities, technical specifications, service features, content handling, media support, platform functionality -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Can't find an answer? Reach out to [support@inkeep.com](mailto:support@inkeep.com?subject=Question). Yes, our AI assistant should automatically answer in the language that the user used. You can also set a 'primary language' in your project settings if your users or documentation are primarily in a different language. This will bias our AI and content ingestion service to account for that language (but still work for any). You can also customize the strings or use an internationalization solution with Inkeep's UI components {" "} Currently Inkeep is not setup to be a self-hostable solution. However, if your concern is data processing or privacy concerns, review our [privacy overview](/overview/privacy) to learn about options available for customers with custom data processing requirements. {" "} While we love supporting open source teams and projects like Drizzle, Auth.js and others, our solution is not currently open source. {" "} For security reasons, our UI components don't render images or content from URLs. We typically don't ingest images out of the box, but let us know if images are an important part of your documentation. We can enable ingestion of images for your sources. Yes, this is typically available as an add-on to your plan. *** title: Troubleshooting keywords: widget troubleshooting, Shadow DOM, custom CSS, component loading, widget display, search bar issues, chat mode, page performance, loading optimization, technical support, debugging guide, component issues, UI troubleshooting ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Can't find an answer? Reach out to [support@inkeep.com](mailto:support@inkeep.com?subject=Question). If you're having trouble loading the Inkeep UI components, try checking the below. Inkeep components are loaded into a "Shadow" DOM. This is done so that they don't affect your pages styles or vice versa. Use your browser's developer tools to check if there's an HTML element with an ID that contains `inkeep-shadow`. If you don't see an element that matches that description, that means there is an issue instantiating the component. This is typically due to an issue with loading the JavaScript. If you're using the `@inkeep/cxkit-js` package, there are two `scripts` that need to be loaded: 1. The component library: `` 2. A script that includes `Inkeep.({...})` to instantiate the UI components. Inspect your DOM to see if both of these scripts were successfully loaded. Sometimes, the issue is that script #2 loads before script #1. To prevent this, you can add an id to script #1 and use the "load" event to execute script #2. ``` inkeepScript.addEventListener("load", function () { // embed logic }); ``` The UI components are designed to not display until custom stylesheets have been fetched. If you specify a link type style in the `styles` array in the widget configurations' theme object but any of the provided paths are invalid, this can cause the widget to not render. Please ensure that the URL is an absolute URL (like for a CDN); or, if using a relative URL, ensure it's relative to your site's root. If you see the `inkeep-shadow` element, the issue might be that the Search Bar or Chat Button components are not being properly displayed in your page. Find all the elements with id `inkeep-widget-root` and inspect whether they are being rendered off the page or hidden by other elements. By default, UI components use same-domain cookies in the browser to keep track of what "mode" a user last had open so that they are taken to that same mode when they next open the Inkeep Modal. To disable this "remember" behavior, you can set `baseSettings.optOutFunctionalCookies` = `true` or use the `forceInitialDefaultView` prop in `modalSettings` which will open the modal in the `defaultView` regardless of which view was last opened. New users will see the default search or chat experience based on your component type or if you customize `modalSettings.defaultView`. The Inkeep UI components and related scripts are loaded asynchronously so they don't affect page performance. *** title: Comparisons description: How does Inkeep compare to other AI search and chat services? -------------------------------------------------------------------------- Teams that have evaluated Inkeep AI assistants compared to other products tend to highlight that Inkeep: * admits when it doesn't know and guides users to support channels * contains minimal (if any) hallucinations or search misses * provides rich citations that help users inspect answers * leverages many sources while prioritizing authoritative content That said - don't take our word for it! Use our [free trial](https://inkeep.com/demo-form) or [schedule a call](https://go.inkeep.com/demo) to test out Inkeep with your toughest questions. ## Comparisons Teams typically look for a managed solution so that they don't have to invest engineering resources in: * Building the pipelines and infra to ingest and keep content up to date * Experimenting with LLM models and RAG techniques to get high-quality results * Building user-friendly chat UIs that are embeddable anywhere * Providing insights to product and documentation teams Algolia is a popular service that is particularly focused on just search. While Algolia offers "Neural" or "AI search", those terms refer to search algorithms rather than "AI chat" or conversational experiences. While Inkeep similarly provides a neural search service (with unlimited usage in any plan), we also provide: * AI chat experiences powered by large language models and your own content * An analytics platform to analyze user conversations - not just search queries. * Slack and Discord bots that can be used in your employee or customer-facing channels * Zero-effort ingestion of any website using our intelligent scraper (no need for managing content over APIs!) Many teams use Inkeep for just the chat experiences - you don't have to replace your existing Algolia search experience if you're happy with it. Intercom is a general support solution for any type of product - consumer-facing, B2B SaaS products, etc. Intercom's offering includes "Fin", an AI chatbot focused on support deflection. In comparison to Intercom, Inkeep has: * UX experiences tailored for developer-facing or technical products * Assistants for any touchpoint - Slack, Discord, Search Bar, Chat button, etc. * Zero-effort ingestion of any content source * Tools to help documentation teams address content gaps

{{ t 'search' }}

{{ t 'search' }}

Ask AI ✨