Chat Button

The chat button component is a simple way to trigger the Inkeep chat bubble in your JavaScript application.

Quick Start

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

<script
    type="module"
    src="https://cdn.jsdelivr.net/npm/@inkeep/agents-ui-js@0.15/dist/embed.js"
    defer
></script>

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

const config: InkeepChatButtonProps = {
  aiChatSettings: {
    agentUrl: "https://your-api.example.com/api/chat",
    apiKey: process.env.INKEEP_API_KEY, // Your API key
  },
};

const chatButton = Inkeep.ChatButton(config);

Config

Prop

Type

Label for the chat button.

Type

string | undefined

URL to the AI assistant's avatar image. Should be a square image, recommended size 40x40px. Supports common image formats (PNG, JPG, SVG).

You can pass a string or an object to configure for different color modes.

Type

string | { light: string; dark: string; } | undefined

Type

OpenSettingsChatButton | undefined

Whether to autofocus the chat input on load.

Type

boolean | undefined

Default

true

Configuration for the base settings.

Type

InkeepBaseSettings | undefined

Configuration for the chat.

Type

(InkeepAIChatSettings & { shouldAutoFocusInput?: boolean; }) | undefined

Base Settings

Prop

Type

The display name of your organization that will be shown in various UI elements. For example, this may appear in chat messages or headers.

Type

string | undefined

The primary brand color used throughout the widget UI. This color will be used to generate a cohesive color scheme. Should be provided as a valid CSS color value (hex, rgb, etc).

Type

string

Settings to control the color mode (light/dark) behavior. Can be used to sync with your application's theme or set a forced color mode.

Type

ColorModeConfig | undefined

Theme customization settings for the widget. Allows customizing colors, typography, component styles, and more.

Type

UserTheme | undefined

Custom icon overrides for the default icon set. Allows replacing any of the built-in icons with your own components.

Type

CustomIconMap | undefined

Properties to identify and provide context about the current user. Used for personalization and analytics tracking.

Type

UserProperties | undefined

Authentication token for the current user. Used for authenticated API requests if required.

Type

string | undefined

Additional properties to be sent with analytics events. These properties will be merged with the event properties.

Type

Record<string, unknown> | undefined

Handler for analytics events from the widget.

Type

((event: InkeepCallbackEvent) => Promise<void>) | undefined

Parameters

event -

The analytics event object

Returns

Promise that resolves when the event is logged

Handler for feedback events from the widget.

Type

((feedback: InkeepFeedback & { properties?: Record<string, unknown>; }) => Promise<InkeepFeedback>) | undefined

Parameters

feedback -

The feedback object

Returns

The feedback object

Whether to bypass the captcha challenge. Only enable this flag if using a server side API type api key, otherwise the api requests will fail without the challenge solution.

Type

boolean | undefined

Default

false

Function to transform source data before display.

Type

TransformSource | undefined

Parameters

source -

The original source data

type -

The type of source data

opts -

The options for the transform source

Returns

The transformed source data

Reference to the shadow DOM host element if using custom Shadow DOM. Required when embedding the widget within a Shadow DOM.

Type

HTMLElement | null | undefined

Reference to the root element where the widget is mounted. Used for positioning and event handling.

Type

HTMLElement | null | undefined

Custom tags for widget identification. Used in analytics to segment and filter widget instances. Array of string identifiers.

Type

string[] | undefined

Instance of the Prism syntax highlighting library. Required for code block syntax highlighting functionality.

Type

any

Query parameters to automatically append to URLs in the widget. Useful for tracking or maintaining context in navigation. Object mapping parameter names to values.

Type

UrlQueryParam | undefined

Base-level filters to apply to all search and chat operations. These are typically organization or user-level filters.

Type

SearchAndChatFilters | undefined

Open Settings

Prop

Type

Controls whether the component is open.

Type

boolean | undefined

Handler called when the component opens or closes.

Type

((isOpen: boolean) => void) | undefined

Whether the component is open by default.

Type

boolean | undefined

Default

false

The shortcut key.

The key to trigger the component when pressed with Cmd (Mac) / Ctrl (Windows).

Set to null to disable the shortcut.

Type

string | null | undefined

Default

null

The trigger selector.

The selector to trigger the component when clicked.

Type

string | undefined

Default

undefined

AI Chat Settings

Prop

Type

Headers for requests

Type

Record<string, string> | undefined

API key for requests

Type

string | undefined

Agent URL for chatstream API.

Type

string | undefined

Context to be passed to the chatstream API.

Type

Record<string, unknown> | undefined

The placeholder text to display in the chat input field when empty. Use this to provide guidance on what kind of questions users can ask.

Type

string | undefined

A welcome message shown at the start of a new chat session. Supports markdown formatting for rich text styling. Use this to introduce the AI assistant's capabilities and set expectations.

Type

string | undefined

The name of the product/service/topic that the chat assistant specializes in. This helps contextualize the chat experience for users. If not provided, defaults to the organization name from base settings.

Type

string | undefined

The display name for the AI assistant in the chat interface. Choose a name that reflects the assistant's role and your brand.

Type

string | undefined

URL to the AI assistant's avatar image. Should be a square image, recommended size 40x40px. Supports common image formats (PNG, JPG, SVG).

You can pass a string or an object to configure for different color modes.

Type

string | { light: string; dark: string; } | undefined

URL to the user's avatar image in the chat interface. Should be a square image, recommended size 40x40px. Falls back to a default user icon if not provided.

Type

string | undefined

Controls whether links in chat messages open in new browser tabs. Enable this to help users maintain their chat context when following links.

Type

boolean | undefined

Default

true

Custom heading text for the example questions section. Use this to better describe your suggested queries.

Type

string | undefined

A list of pre-written questions users can click to quickly start a conversation. These should reflect common use cases and help users understand the AI assistant's capabilities.

Type

string[] | { value: string; label: string; }[] | undefined

Whether to visually emphasize the first example question. Use this to draw attention to the most important or common query.

Type

boolean | undefined

Enables the ability to share chat conversations via URL. Useful for allowing users to share helpful conversations with teammates.

Type

boolean | undefined

The base URL path used when generating shareable chat links. Should match your application's routing structure.

Type

string | undefined

Controls the visibility of the copy chat button. Allows users to copy the entire chat transcript to their clipboard.

Type

boolean | undefined

Unique identifier for loading a specific conversation. Use this to restore a previous conversation state.

Type

string | undefined

When enabled, prevents users from sending new messages. Useful for displaying archived or shared chat sessions.

Type

boolean | undefined

Default

false

Whether to make conversations public by default.

Type

"public" | "private" | undefined

Default

undefined (private)

Configuration for the chat's disclaimer message. Use this to display important notices about AI limitations or data usage.

Type

AIChatDisclaimerSettings | undefined

Callback function triggered whenever the user modifies their input message.

Type

((message: string) => void) | undefined

Parameters

message -

The current content of the input field

React ref for accessing the chat component's methods. Enables programmatic control of chat functions from parent components.

Type

Ref<AIChatFunctions> | undefined

Array of actions available in the "Get Help" menu. Use this to provide alternative support options like contact forms or documentation links.

Type

GetHelpOption[] | undefined

Array of actions available rendered after each message.

Type

CustomMessageAction[] | undefined

Custom heading text for the workflows section. Use this to describe available automated processes or guided flows.

Type

string | undefined

Custom labels for the chat interface's action buttons. Use this for internationalization or to better match your application's terminology.

Type

AIChatToolbarButtonLabels | undefined

Filters to apply to the chat results.

Type

SearchAndChatFilters | undefined

Components to be rendered in the chat interface.

Type

ComponentsConfig<any> | undefined

Type

ComponentsConfig<any> | undefined

Quick Start

Config

Base Settings

Open Settings

AI Chat Settings

On this page