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 sparkles 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. Set to true to enable the "share" button and let users share their conversations with other users. Requires shareChatUrlBasePath to also be set.
shareChatUrlBasePathstringBase path for shared chats. Default undefined. To use, create a page with a dedicated page in your domain (e.g. ` with an embedded chat component.
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.
includeAIAnnotationsIncludeAIAnnotationsDetermines which AI annotations to include. Refer to Support workflows for details. This is currently an enterprise preview feature.
aiAnnotationPoliciesAIAnnotationPoliciesConfigure policies for the different AI annotations. Refer to Support workflows for details.
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 can be used to provide additional details about the user that might be helpful information for the bot 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.


  • "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 context as a single phrase or a bullet point list.

context applies to the entire chat session.


guidance can be used to 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.


We recommend using the below format:

  <name>Sprinkle of Humor</name>
    <condition>For all questions where the user has a neutral or positive tone</condition>
  <action>Add a bit of humour to your answer while still answering the user's question</action>
  <name>Be brief</name>
    <condition>For all responses</condition>
  <action>Limit your answer to two sentences.</action>
  <name>Clarify app type</name>
    <condition>When asking how to add to their application</condition>
    <condition>And it is unclear what SDK or application framework they are using</condition>
  <action>Briefly enumerate some options that may apply to them and ask a clarifying question</action>

guidance applies to the entire chat session.

You can configure guidance that will apply to all chats of a project as Custom Rules under Project > Settings in the Inkeep dashboard. If you'd like to customize guidance on a per-integration basis or dynamically, then use this property in the widget settings instead.


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.
ModelsStandardUses the best models available that have 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.
openForm(formConfig: FormConfig)Opens the form with the configuration that was passed in. See FormConfig for details.


You can follow a similar pattern in React 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


There are two types of GetHelpCallToActions that can be used. The first, GetHelpCallToActionOpenUrl will open the specified url when clicked. The second, GetHelpCallToActionOpenForm can be used to open a custom form.


type"OPEN_LINK"Type of GetHelpCallToAction.
iconCustomIconIcon that goes next to the link. See below.
namestringLabel for the link.
urlstringURL to your community forum or help center.


type"OPEN_FORM"Type of GetHelpCallToAction.
iconCustomIconIcon that goes next to the button label. See below.
namestringLabel for the button.
formConfigFormConfigCustom form configuration. Refer to Support workflows for details.


type"INVOKE_CALLBACK"Type of GetHelpCallToAction.
iconCustomIconIcon that goes next to the button label. See below.
namestringLabel for the button.
callback() => voidCallback to be invoked when the button is clicked.
shouldCloseModalbooleanDetermines whether the chat modal should close when the callback is invoked. Default is false.


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.

If the url for a custom icon is a .svg file it will be rendered as an <svg>, all other file types will be rendered using an <img> tag.


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

const supportFormConfig: FormConfig = {
  heading: "Contact support",
  fields: [
      type: "STANDARD_FIELD",
      label: "Name",
      name: "first_name",
      inputType: "TEXT",
      type: "STANDARD_FIELD",
      label: "Email",
      name: "email",
      inputType: "EMAIL",
      required: true,
      defaultValue: true,
      type: "STANDARD_FIELD",
      label: "Additional details",
      name: "additional_details",
      inputType: "TEXTAREA",
  submitCallback: (values) => {
    // replace with your own api call
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve({ success: true });
      }, 2000);

const inkeepAIChatSettings: InkeepAIChatSettings = {
  //... rest of inkeepAIChatSettings
  getHelpCallToActions: [
      type: "OPEN_LINK",
      icon: { builtIn: "FaDiscord" },
      name: "Discord",
      url: "",
      icon: { builtIn: "LuUsers" },
      name: "Contact support",
      type: "OPEN_FORM",
      formConfig: supportFormConfig,


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.