The chat button is a great way to add an AI copilot to your landing page, dashboard, or documentation without changing your current search experience.

​
Quick start

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

<!-- Add Inkeep widget -->
<script
  type="module"
  src="https://unpkg.com/@inkeep/widgets-embed@0.2.278/dist/embed.js"
  defer
></script>

Insert the Chat Button by using the Inkeep.embed() function.

<script type="module" defer>
  const inkeepWidget = Inkeep().embed({
    componentType: "ChatButton", // required
    stylesheetUrls: ['/path/to/stylesheets'], // optional
    // optional -- for syncing UI color mode
    colorModeSync: {
      observedElement: document.documentElement,
      isDarkModeCallback: (el) => {
        return el.classList.contains("dark");
      },
      colorModeAttribute: 'class',
    },
    properties: {
      chatButtonType: 'ICON_TEXT', // default. Alternatives are 'ICON_TEXT_SHORTCUT' and 'ICON'
      baseSettings: {
        apiKey: process.env.INKEEP_INTEGRATION_API_KEY!, // required
        integrationId: process.env.INKEEP_INTEGRATION_ID!, // required
        organizationId: process.env.INKEEP_ORGANIZATION_ID!, // required
        organizationDisplayName: "Inkeep",
        primaryBrandColor: "#26D6FF",
        //... optional base settings
      },
      modalSettings: {
        // optional InkeepModalSettings
      },
      searchSettings: {
        // optional InkeepSearchSettings
      },
      aiChatSettings: {
        // optional InkeepAIChatSettings
          botAvatarSrcUrl: "/img/inkeep-logo.svg", // use your own bot avatar
          botAvatarDarkSrcUrl: "/img/inkeep-logo-dark.svg" // for dark mode or more contrast against button bg
          quickQuestions: [
            "Example question 1?",
            "Example question 2?",
            "Example question 3?",
          ],
      }
    },
  });
</script>

​
Inkeep.Embed() for Chat Button

ParameterTypeDescription
componentTypestringRequired. Must be ChatButton to add the ChatButton component.
targetElementHTMLElementA valid HTML element where you want to render the ChatButton component.
propertiesInkeepChatButtonPropsRequired. An object that contains the base settings and other optional settings for the ChatButton
colorModeSyncColorModeSyncAn object that contains the settings to sync the color mode in the widgets with the parent UI.

​
ColorModeSync

These setting can be used to sync the widget's color mode with the color mode set in the parent UI.

ParameterTypeDescription
observedElementHTMLElementRequired. Element to observe for color mode change. Example: document.body.
isDarkModeCallback(observedElement: Node) => booleanRequired. Function that returns true if dark mode otherwise false. Example: (observedElement) => observedElement.dataset.theme === 'dark'.
colorModeAttributestringRequired. Attribute that changes on the observedElement when colorMode changes. Example: "class" or "data-theme".

​
InkeepChatButtonProps

This type represents the configuration for the Inkeep Chat Button widget.

​
Properties

All properties are optional.

PropertyTypeDescription
chatButtonTypeChatButtonTypesType of the chat button. Can be ICON_TEXT_SHORTCUT, ICON_TEXT, or ICON. Default value ICON_TEXT.
isPositionFixedbooleanDetermines whether the position of the chat button is fixed. Default value true.
fixedPositionXOffsetstringX offset for the fixed position of the chat button. Default value 1.5rem
fixedPositionYOffsetstringY offset for the fixed position of the chat button. Default value 1.5rem.
chatButtonBgColorstringBackground color of the chat button.
chatButtonBgColorDarkModestringBackground color of the chat button in dark mode.
chatButtonPillTextstringText on the chat button if using the ICON_TEXT version. Default is Ask AI.
chatButtonPillTextstringText on the chat button if using the ICON_TEXT_SHORTCUT version. Default is Ask anything.
stylesheetUrlsstring[]Optional. An array of strings. The strings must be valid absolute or relative URLs to CSS files.
baseSettingsInkeepWidgetBaseSettingsRequired. Base settings for any Inkeep widget. See reference here.
modalSettingsInkeepModalSettingsSettings for the modal. See reference here.
searchSettingsInkeepSearchSettingsAdditional search settings for the Inkeep widget. See reference here.
aiChatSettingsInkeepAIChatSettingsAI chat settings for the Inkeep widget. See reference here.

​
ChatButtonType

There are three variations of the chat button. The default is ICON_TEXT.

​
Example

import type {
  InkeepChatButtonSettings,
  InkeepChatButtonModalSettings,
} from "@inkeep/widgets";
import baseSettings from "./baseSettings"; // your base settings typeof InkeepWidgetBaseSettings

const inkeepChatButtonSettings: InkeepChatButtonSettings = {
    chatButtonType: "ICON_TEXT",
    isPositionFixed: true,
    fixedPositionXOffset: "1.5rem",
    fixedPositionYOffset: "1.5rem",
    baseSettings : {
        ...baseSettings
        //... typeof InkeepWidgetBaseSettings
    },
    modalSettings : {
        //... typeof InkeepModalSettings
    }
    searchSettings : {
        //... typeof InkeepSearchSettings
    },
    aiChatSettings : {
        //... typeof InkeepAIChatSettings
    },
};

​
Multiple widgets

You may want to add mutliple Inkeep widgets on your site, like both a search bar and a chat button. In these cases, it can be helpful to create a common Inkeep JavaScript object that shares the same base settings for every widget.

const inkeepBase = Inkeep({
  integrationId: envConfig.INTEGRATION_ID || "", // required
  apiKey: envConfig.API_KEY || "", // required
  organizationId: envConfig.ORGANIZATION_ID || "", // required
  organizationDisplayName: "Inkeep",
  primaryBrandColor: "black",
  userId: "", // if you'd like analytics by user ID, like in cases where the user is authenticated or you have your own analytics platform
  userEmail: "dev@inkeep.com",
  userName: "Inkeep",
  optOutAllAnalytics: false,
  optOutAnalyticalCookies: false,
  optOutFunctionalCookies: false,
});

You can then use inkeepBase.embed() to add different components with the same base settings.

​
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 render 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++;
    inkeepWidget.render({
      baseSettings: {
        primaryBrandColor: colors[count % colors.length],
      },
    });
  });
Custom TriggerSearch Bar