This interface is used to configure the settings related to the AI chat. It is used in any component that renders the AI chat.


All are optional configurations.

placeholderstringPlaceholder text for the chat input. Default How to get started?.
chatSubjectNamestringName of what the chat is about, e.g. "Inkeep". Defaults to the organizationDisplayName if not provided.
botNamestringName of the bot. Default undefined.
introMessagestringIntroductory bot message in markdown format. Default Hi! \n\n I'm.... See the example below for the pattern used.
contextstringInformation about the user that might be helpful to ground answers for the bot. Default undefined.
guidancestringCustom instructions for the bot, like "Be succinct". Default undefined.
botAvatarSrcUrlstringSource URL for the bot's avatar. Defaults to the Inkeep's octupus icon customized for your brand color.
botAvatarDarkSrcUrlstringSource URL for the bot's avatar for dark mode.
userAvatarSrcUrlstringSource URL for the user's avatar. Defaults to a generic user avatar icon.
quickQuestionsLabelstringHeader for suggested queries. Default Popular Questions.
quickQuestionsstring[]Suggested queries user can auto-submit. Default [].
shouldHighlightFirstQuickQuestionbooleanDetermines whether to highlight the first quick question. Default true.
shouldOpenLinksInNewTabbooleanDetermines whether citation links should open in a new tab. Default true.
isChatSharingEnabledbooleanDetermines if chat sharing is enabled. Default false.
shareChatUrlBasePathstringBase path for shared chats. Default undefined.
defaultChatModeChatModeDefault chat mode. Can be TURBO or AUTO. Default AUTO. Learn about the difference here
toggleButtonSettingsAIChatToggleButtonSettingsSettings for the chat mode toggle button. Default undefined (not enabled). See here.
disclaimerSettingsAIChatDisclaimerSettingsSettings for the chat disclaimer. Default undefined (not enabled). See here.
isControlledMessagebooleanDetermines whether the message will be controlled externally.
handleMessageChange(query: string) => voidCallback for when the input message changes.
chatFunctionsRefReact.Ref<AIChatFunctions>Ref to the AIChat component's callable functions.
getHelpCallToActionsGetHelpCallToAction[]Get help button that opens a menu displaying the list of urls with additional support or community links. See here.
actionButtonLabelsAIChatActionButtonLabelsCustom labels for the chat action buttons. See here.


import { type InkeepAIChatSettings } from "@inkeep/widgets";

export const aiChatSettings: InkeepAIChatSettings = {
  placeholder: "How do I get started?",
  botName: "Keepie",
  chatSubjectName: "Inkeep",
  introMessage: `Hi, I'm {{botName}} \n\n I'm an AI assistant trained on documentation, help articles, and other content. \n\n Ask me anything about {{chatSubjectName}}.`,
  botAvatarSrcUrl: "",
  botAvatarDarkSrcUrl: "",
  userAvatarSrcUrl: "",
  quickQuestionsLabel: "Popular Questions",
  quickQuestions: ["How do I get started?", "How do I get help?"],
  shouldOpenLinksInNewTab: true,
  isChatSharingEnabled: true,
  shareChatUrlBasePath: "",
  defaultChatMode: "AUTO",
  isControlledMessage: false,
  handleMessageChange: undefined,
  chatFunctionsRef: undefined,


context is useful when you'd like to provide additional details that might be helpful information for the bot to consider while answering.

This is used to both refine retrieval and "ground" model answers.

Often, this is used to dynamically provide information about the user that can be inferred by their account or the page they are viewing. Examplle may include:

  • "The user is currently viewing documentation page {url}."
  • "The user is new to the platform." (for user life cycle stages)
  • "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)

Frame as a single phrase or bullet point list.

context applies to the entire chat session.


guidance can be used to dynamically customize the behavior of the bot response using natural language. You can think of guidance as custom instructions for the large language model.

We've already optimized chat responses to have proper guardrails for staying on topic, tone, brand-protection, etc.

However, guidance is useful when you want to go beyond the default behavior. Examples include:

  • "Limit to two sentences."
  • "Distinguish between Cloud and Self-Hosted versions, if ambiguious from the user's question or source material."

Frame as a single phrase or bullet point list.

guidance applies to the entire chat session.


We currently offer two chat modes: Expert and Turbo modes.

Turbo ModeExpert Mode
Conversation lengthStandardSupports longer conversations.
Input sizeStandardUser questions can have greater amount of content.
Sources consideredStandardMore sources are considered when formulating an answer.
Intermediary LLM StepsStandardAdditional chain of thought reasoning and other LLM techniques are used for Q&A.
ModelsStandard (e.g. GPT 3.5-turbo)Uses the best models available (e.g. GPT4 and Claude V2). Better reasoning and instruction following.
Response speedFasterSlower
CostMore affordableMore expensive

End-users can switch between these modes using the chat mode toggle button. The default chat mode can be configured using the defaultChatMode property.


isChatModeToggleEnabledbooleanDetermines if the chat mode toggle is enabled. Default false.
chatModeToggleValueChatModeThe value for chat mode toggle. It can either be TURBO or AUTO. Default AUTO.
chatModeToggleLabelstringLabel for the chat mode toggle based on defaultChatMode.
chatModeToggleTooltipstringTooltip for the chat mode toggle based on defaultChatMode.

Default values

PropertyWhen defaultChatMode is AUTOWhen defaultChatMode is TURBO
chatModeToggleLabelTurbo modeExpert mode
chatModeToggleTooltipTurbo mode is fast and effective for less complex questions, but can be less accurate.Expert mode is great for more complex questions, but can be slower.


import {
  type InkeepAIChatSettings,
  type AIChatToggleButtonSettings,
} from "@inkeep/widgets";

const aiChatToggleButtonSettings: AIChatToggleButtonSettings = {
  isChatModeToggleEnabled: true,
  chatModeToggleValue: "TURBO",
  chatModeToggleLabel: "Turbo mode",
  chatModeToggleTooltip: `Turbo mode is great for complex questions, but can be slower.`,

const inkeepAIChatSettings: InkeepAIChatSettings = {
  //... rest of inkeepAIChatSettings
  toggleButtonSettings: aiChatToggleButtonSettings,


This nested configuration allows you to add your own "Disclaimer" to the chat widget. This is useful if you want to add a link to your terms of service, privacy policy, or otherwise inform your users about how the chat widget works.

isDisclaimerEnabledbooleanDetermines whether to enable the usage disclaimer. Default false.
disclaimerLabelstringLabel for the disclaimer. Default Usage policy.
disclaimerTooltipstringTooltip text for the disclaimer. You can include links to, for example, your terms of service using markdown. Default value is in the pattern shown in the example below.


import {
  type InkeepAIChatSettings,
  type AIChatDisclaimerSettings,
} from "@inkeep/widgets";

const aiChatDisclaimerSettings: AIChatDisclaimerSettings = {
  isDisclaimerEnabled: true,
  disclaimerLabel: "Usage policy",
    "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,


The AIChatFunctions interface provides a set of functions that can be used to programmatically interact with the AI chat. Once a ref is defined, the functions outlined below can be invoked programmatically based on your own business logic.

submitCurrentInputMessage-Submits the current message in the input field.
updateInputMessage(message: string)Updates the current message in the input field with the provided string.
submitNewMessage(message: string)Submits a new message directly, bypassing the input field.


You can follow a similar pattern to the below to programmatically call any of the above methods. Keep in mind you should only call these methods once the ref is defined, which is why we are using useEffect in the below example.

import React, { useEffect, useRef } from "react";
import { InkeepEmbeddedChat, AIChatFunctions } from "@inkeep/widgets";
import baseSettings from "./baseSettings"; // your base settings
import aiChatSettings from "./aiChatSettings"; // your ai chat settings

export const EmbeddedChat = () => {
  const chatFunctionsRef = useRef<AIChatFunctions | null>(null);

  useEffect(() => {
    if (chatFunctionsRef.current) {
      // Submit a new message when the chat ref is defined
      chatFunctionsRef.current.submitNewMessage("How do I get started");
  }, [chatFunctionsRef.current]);
  return (
        aiChatSettings={{ ...aiChatSettings, chatFunctionsRef }} // Spread the ref into aiChatSettings


iconCardIconIcon that goes next to the link. See below.
namestringLabel for the link.
urlstringURL to your community forum or help center.


Can either be builtIn or custom

builtInAvailableBuiltInIconsPass in the name of an icon that is already included in the widgets package.
customstringURL of icon image.


clearButtonLabelstringLabel for the button that clears the current chat. Default Clear.
shareButtonLabelstringLabel for the button that copies a link to the current chat. Default Share.
getHelpButtonLabelstringLabel for the button that opens the get help menu. Default Get help.
stopButtonLabelstringLabel for the button that stops the chat while the bot is answering. Default Stop.