AI Chat

InkeepAIChatSettings

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

Properties

All are optional configurations.

Property	Type	Description
placeholder	`string`	Placeholder text for the chat input. Default `How to get started?`.
chatSubjectName	`string`	Name of what the chat is about, e.g. "Inkeep". Defaults to the `organizationDisplayName` if not provided.
botName	`string`	Name of the bot. Default `undefined`.
introMessage	`string`	Introductory bot message in markdown format. Default `Hi! \n\n I'm...`. See the example below for the pattern used.
context	`string`	Information about the user that might be helpful to ground answers for the bot. Default `undefined`.
guidance	`string`	Custom instructions for the bot, like "Be succinct". Default `undefined`.
botAvatarSrcUrl	`string`	Source URL for the bot's avatar. Defaults to the sparkles icon customized for your brand color.
botAvatarDarkSrcUrl	`string`	Source URL for the bot's avatar for dark mode.
userAvatarSrcUrl	`string`	Source URL for the user's avatar. Defaults to a generic user avatar icon.
quickQuestionsLabel	`string`	Header for suggested queries. Default `Popular Questions`.
quickQuestions	`string[]`	Suggested queries user can auto-submit. Default `[]`.
shouldHighlightFirstQuickQuestion	`boolean`	Determines whether to highlight the first quick question. Default `true`.
shouldOpenLinksInNewTab	`boolean`	Determines whether citation links should open in a new tab. Default `true`.
isChatSharingEnabled	`boolean`	Determines 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.
shareChatUrlBasePath	`string`	Base path for shared chats. Default `undefined`. To use, create a page with a dedicated page in your domain (e.g. `https://mydomain.com/ask-ai) with an embedded chat component.
shouldShowCopyChatButton	`boolean`	Determines whether to show the copy conversation button, which allows users to copy the entire conversation in markdown format when clicked. Default `false`.
defaultChatMode	`ChatMode`	Default chat mode. Can be `TURBO` or `AUTO`. Default `AUTO`. Learn about the difference here
toggleButtonSettings	`AIChatToggleButtonSettings`	Settings for the chat mode toggle button. Default `undefined` (not enabled). See here.
disclaimerSettings	`AIChatDisclaimerSettings`	Settings for the chat disclaimer. Default `undefined` (not enabled). See here.
isControlledMessage	`boolean`	Determines whether the message will be controlled externally.
handleMessageChange	`(query: string) => void`	Callback for when the input message changes.
chatFunctionsRef	`React.Ref<AIChatFunctions>`	Ref to the AIChat component's callable functions.
includeAIAnnotations	`IncludeAIAnnotations`	Determines which AI annotations to include. Refer to Support workflows for details. This is currently an enterprise preview feature.
aiAnnotationPolicies	`AIAnnotationPolicies`	Configure policies for the different AI annotations. Refer to Support workflows for details.
getHelpCallToActions	`GetHelpCallToAction[]`	Get help button that opens a menu displaying the list of urls with additional support or community links. See here.
actionButtonLabels	`AIChatActionButtonLabels`	Custom labels for the chat action buttons. See here.

Example

import { type InkeepAIChatSettings } from "@inkeep/uikit";
 
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: "http://example.com/bot-avatar.png",
  botAvatarDarkSrcUrl: "http://example.com/bot-avatar-dark-mode.png",
  userAvatarSrcUrl: "http://example.com/user-avatar.png",
  quickQuestionsLabel: "Popular Questions",
  quickQuestions: ["How do I get started?", "How do I get help?"],
  shouldOpenLinksInNewTab: true,
  isChatSharingEnabled: true,
  shareChatUrlBasePath: "https://mydomain.com/dedicated-chat-page",
  defaultChatMode: "AUTO",
  isControlledMessage: false,
  handleMessageChange: undefined,
  chatFunctionsRef: undefined,
};

context

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.

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)

Frame context as a single phrase or a bullet point list.

context applies to the entire chat session.

guidance

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.

Checkout the Custom Guidance article for tips on how to use it.

guidance applies to the entire chat session, not just the first message.

ChatMode

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

	Turbo Mode	Expert Mode
Conversation length	Standard	Supports longer conversations.
Input size	Standard	User questions can have greater amount of content.
Sources considered	Standard	More sources are considered when formulating an answer.
Intermediary LLM Steps	Standard	Additional chain of thought reasoning and other LLM techniques are used for Q&A.
Models	Standard	Uses the best models available that have better reasoning and instruction following.
Response speed	Faster	Slower
Cost	More affordable	More 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.

AIChatToggleButtonSettings

Property	Type	Description
isChatModeToggleEnabled	`boolean`	Determines if the chat mode toggle is enabled. Default `false`.
chatModeToggleValue	`ChatMode`	The value for chat mode toggle. It can either be `TURBO` or `AUTO`. Default `AUTO`.
chatModeToggleLabel	`string`	Label for the chat mode toggle based on `defaultChatMode`.
chatModeToggleTooltip	`string`	Tooltip for the chat mode toggle based on `defaultChatMode`.

Default values

Property	When `defaultChatMode` is `AUTO`	When `defaultChatMode` is `TURBO`
chatModeToggleValue	`TURBO`	`AUTO`
chatModeToggleLabel	`Turbo mode`	`Expert mode`
chatModeToggleTooltip	`Turbo 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.`

Example

import {
  type InkeepAIChatSettings,
  type AIChatToggleButtonSettings,
} from "@inkeep/uikit";
 
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.

Property	Type	Description
isDisclaimerEnabled	`boolean`	Determines whether to enable the usage disclaimer. Default `false`.
disclaimerLabel	`string`	Label for the disclaimer. Default `Usage policy`.
disclaimerTooltip	`string`	Tooltip 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.

Example

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,
};

AIChatFunctions

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.

Method	Parameters	Description
`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.

Example

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/uikit";
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 (
    <div>
      <InkeepEmbeddedChat
        baseSettings={baseSettings}
        aiChatSettings={{ ...aiChatSettings, chatFunctionsRef }} // Spread the ref into aiChatSettings
      />
    </div>
  );
};

You can follow a similar pattern in Javascript to programmatically call any of the above methods.

<div id="embedded-chat"></div>
<button id="submit-new-message">submit new message</button>

const embeddedChat = Inkeep().embed({
  componentType: "EmbeddedChat",
  targetElement: document.getElementById("embedded-chat"),
  properties: {
    baseSettings: {
      apiKey: "INKEEP_API_KEY",
      integrationId: "INKEEP_INTEGRATION_ID",
      organizationId: "INKEEP_ORGANIZATION_ID",
      primaryBrandColor: "#26D6FF",
    },
    // ...additional settings
  },
});
 
const submitNewMessageButton = document.getElementById("submit-new-message");
// Submit a new message upon clicking a button
submitNewMessageButton.addEventListener("click", () => {
  embeddedChat.submitNewMessage("How do I get started?");
});

GetHelpCallToAction

There are three 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. The third, GetHelpCallToActionInvokeCallback can be used to call a custom function, for example to trigger a live chat.

GetHelpCallToActionOpenUrl

Property	Type	Description
type	`"OPEN_LINK"`	Type of `GetHelpCallToAction`.
icon	`CustomIcon`	Icon that goes next to the link. See below.
name	`string`	Label for the link.
pinToToolbar	`boolean`	Whether or not pin the item to the toolbar instead of showing it in the get help menu. Default `false`, unless it's the only item, then it will be pinned by default.
url	`string`	URL to your community forum or help center.

GetHelpCallToActionOpenForm

Property	Type	Description
type	`"OPEN_FORM"`	Type of `GetHelpCallToAction`.
icon	`CustomIcon`	Icon that goes next to the button label. See below.
name	`string`	Label for the button.
pinToToolbar	`boolean`	Whether or not pin the item to the toolbar instead of showing it in the get help menu. Default `false`, unless it's the only item, then it will be pinned by default.
formConfig	`FormConfig`	Custom form configuration. Refer to Support workflows for details.

Example

import { type InkeepAIChatSettings, type FormConfig } from "@inkeep/uikit";
 
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,
    },
    {
      type: "INCLUDE_CHAT_SESSION",
      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: "https://example-discord.com",
    },
    {
      icon: { builtIn: "LuUsers" },
      name: "Contact support",
      type: "OPEN_FORM",
      formConfig: supportFormConfig,
    },
  ],
};

GetHelpCallToActionInvokeCallback

Use this property to trigger a live support chat, such as Intercom or Zendesk, or to open an in-app support form or any other custom component within your application.

Property	Type	Description
type	`"INVOKE_CALLBACK"`	Type of `GetHelpCallToAction`.
icon	`CustomIcon`	Icon that goes next to the button label. See below.
name	`string`	Label for the button.
pinToToolbar	`boolean`	Whether or not pin the item to the toolbar instead of showing it in the get help menu. Default `false`, unless it's the only item, then it will be pinned by default.
callback	`(args: InvokeCallbackArgs) => void`	Callback to be invoked when the button is clicked. See here for details.
shouldCloseModal	`boolean`	Determines whether the chat modal should close when the callback is invoked. Default is `false`.

InvokeCallbackArgs

Property	Type	Description
chatSessionId	`string`	Id for the chat session.
messages	`Message[]`	Messages from the chat session.

Example

import { type InkeepAIChatSettings } from "@inkeep/uikit";
 
const inkeepAIChatSettings: InkeepAIChatSettings = {
  //... rest of inkeepAIChatSettings
  getHelpCallToActions: [
    {
      icon: { builtIn: 'IoChatbubblesOutline' },
      name: 'Chat live with support',
      type: 'INVOKE_CALLBACK',
      callback: ({ chatSessionId, messages }) => {
        // code to trigger live chat
        console.log('Opening support chat:', chatSessionId, messages);
      },
      shouldCloseModal: true,
    },
  ],
};

CustomIcon

Can either be builtIn or custom

Property	Type	Description
builtIn	`AvailableBuiltInIcons`	Pass in the name of an icon that is already included in the widgets package.
custom	`string`	URL 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.

AIChatActionButtonLabels

Property	Type	Description
clearButtonLabel	`string`	Label for the button that clears the current chat. Default `Clear`.
shareButtonLabel	`string`	Label for the button that copies a link to the current chat. Default `Share`.
getHelpButtonLabel	`string`	Label for the button that opens the get help menu. Default `Get help`.
stopButtonLabel	`string`	Label for the button that stops the chat while the bot is answering. Default `Stop`.
copyChatButtonLabel	`string`	Label for the button that copies the current conversation in markdown. Default `Copy`.

On this page