Base Settings
Copy page
Review the basic configuration settings for our widgets.
The base configuration provides core settings for all Inkeep widgets. These settings control authentication, branding, theming, and general behavior.
Basic Configuration
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.
| Property | Type | Required | Description |
|---|---|---|---|
userProperties | UserProperties | No | User identification and metadata |
userAuthToken | string | No | Authentication token for the user |
Privacy Preferences
Control whether the widget sends analytics data and how it uses cookies for user identification and storage.
| Property | Type | Required | Description |
|---|---|---|---|
privacyPreferences | PrivacyPreferences | No | Privacy preferences configuration |
Set optOutAllAnalytics to true to disable all analytics. When this is enabled, conversations and event data are never sent to Inkeep. We do not recommend setting this to true; leave it unset or set it to false so Inkeep can capture conversations and event data.
When optOutAllAnalytics is false or omitted, conversations and event data can be sent to Inkeep. The default value is false. In this case, optOutAnalyticalCookies and optOutFunctionalCookies determine what cookie-backed context can be saved with analytics, such as anonymous user/session continuity and widget preferences.
For the best experience, keep both cookie preferences enabled by setting both opt-out flags to false.
optOutAnalyticalCookies | optOutFunctionalCookies | Behavior |
|---|---|---|
false | false | Recommended. Analytics can include cookie-backed anonymous user/session context, and functional cookies can preserve widget preferences for a more consistent product experience. |
true | false | Analytical cookie-backed user/session context is not saved with analytics, but functional cookies can still preserve widget preferences. |
false | true | Analytics can include cookie-backed anonymous user/session context, but functional cookies are disabled, so widget preferences and session behavior may be less persistent. |
true | true | Cookie-backed user/session context is not saved with analytics, and functional cookies are disabled, so the widget may behave more like a fresh session across visits. |
Event Handling
Configure callbacks for tracking and processing widget events. This allows you to integrate with your own analytics or monitoring systems.
| Property | Type | Required | Description |
|---|---|---|---|
onEvent | (event: InkeepCallbackEvent) => void | No | Event processing callback function |
analyticsProperties | Record<string, any> | No | Additional properties to send to analytics |
You can see the Analytics guide for more information.
Color Mode
Synchronize the widget's appearance with your application's theme. This enables seamless dark/light mode integration.
| Property | Type | Required | Description |
|---|---|---|---|
colorMode | ColorMode | No | Theme synchronization configuration |
Theme Customization
Configure advanced styling and branding options for the widget. This includes colors, styles, and custom CSS.
| Property | Type | Required | Description |
|---|---|---|---|
theme | UserTheme | No | Theme customization settings |
You can see the Theme Customization guide for more information.
Custom Icons
Configure custom icons for various widget elements. You can use built-in icons from popular icon libraries or provide custom SVG URLs.
| Property | Type | Required | Description |
|---|---|---|---|
customIcons | CustomIconMap | No | Custom icon configurations |
You can see the Custom Icons guide for more information.
URL Parameters
Configure URL parameters that will be automatically appended to all links within the widget. This is useful for tracking and maintaining context across page navigations.
| Property | Type | Required | Description |
|---|---|---|---|
urlQueryParamsToAppend | object | No | URL parameters to append to links |
Source Transformation
See the Source Transformation guide for more information on how to customize how source information is displayed in the search and chat results.
Custom Filters
See the Search and Chat Filters guide for more information on how to use filters to dynamically filter search and chat results.