Ui componentsJs snippet

Embedded Chat (JS)

Add a chat UI directly on a dedicated page

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

Add the below <script> tag to the <head> or <body> of your website.

<script
  type="module"
  src="https://unpkg.com/@inkeep/cxkit-js@^0.5.40/dist/embed.js"
  defer
></script>

Define an element in your page that will be the "container" for the embedded chat.

 
<div style="display: flex; align-items: center; justify-content: center; height: calc(100vh - 16px);">
  <div style="max-height: 600px; height: 100%;">
    <div id="ikp-embedded-chat-target"></div>
  </div>
</div>

Insert the Embedded Chat by using the Inkeep.EmbeddedChat() function.

<script type="module">
  const config = {
    baseSettings: {
      apiKey: "YOUR_API_KEY",
    },
    aiChatSettings: {
      aiAssistantName: "Keepie",
    },
  };
 
  // Initialize the widget
  const widget = Inkeep.EmbeddedChat("#ikp-embedded-chat-target", config);
</script>

Embedded Chat Props

This type represents the configuration for the Inkeep embedded chat widget.

PropTypeRequiredDescription
baseSettingsobjectYesCore configuration settings. See Base Settings for details.
aiChatSettingsobjectNoAI chat configuration settings. See AI Chat Settings for details.
isHiddenbooleanNoWhether to hide the chat interface. Defaults to false.
shouldAutoFocusInputbooleanNoWhether to auto focus the input. Defaults to true.

Examples

Auto Focus Input

const config = {
  // ... other config
  shouldAutoFocusInput: true,
};
 
const widget = Inkeep.EmbeddedChat("#chat", config);

With AI Chat Settings

const config = {
  // ... other config
  aiChatSettings: {
    aiAssistantName: "Support Assistant",
    introMessage: "👋 Hi! How can I help you today?",
  },
};
 
const widget = Inkeep.EmbeddedChat("#ikp-embedded-chat-target", config);

Refer to the Chat Settings docs for more details on the available properties.

Changing props after initial render

Sometimes you may need to manage change settings after a widget has already been initialized, for example, to update user privacy preferences. To do this, you can use the update method.

The below example illustrates how you change the primary color on the widget when a button is clicked.

const colors = [
  "#26D6FF",
  "#e300bd",
  "#512fc9",
  "#fde046",
  "#2ecc71",
  "#e74c3c",
  "#9b59b6",
  "#f1c40f",
];
 
let count = 0;
 
const changeColorButton = document.getElementById("change-color-button");
 
changeColorButton.addEventListener("click", () => {
  count++;
  widget.update({
    baseSettings: {
      primaryBrandColor: colors[count % colors.length],
    },
  });
});

Accessing chat methods

The instance of the chat object returned by Inkeep.EmbeddedChat() exposes some methods that you can use to interact with the chat.

// Access chat methods
chat.clearChat();
chat.submitMessage("Hello!");
MethodDescription
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 reference docs for more details on the available properties for the openForm method.

On this page