OpenAIChatKit

A Web Component that serves as the entry point for a ChatKit integration.

Examples

Imperative setup

const chatkit = document.createElement('openai-chatkit');
chatkit.setOptions({
  /* ... */
});
document.body.append(chatkit);

Declarative markup

<openai-chatkit id="chatkit-container"></openai-chatkit>
<script type="module">
  const chatkit = document.getElementById('chatkit-container');
  chatkit.setOptions({
    /* ... */
  });
</script>

Extends

• HTMLElement

Methods

addEventListener()

Call Signature

addEventListener<K>(
   type: K,
   listener: EventHandler<K>,
   options?: boolean | AddEventListenerOptions): void;

Adds an event listener for the specified ChatKitEvents event.

Type Parameters

Type Parameter
K extends keyof ChatKitEvents

Parameters

Parameter	Type	Description
type	K	See ChatKitEvents for available events.
listener	EventHandler<K>	The event listener callback.
options?	boolean | AddEventListenerOptions	An object that specifies characteristics about the event listener. See https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options

Returns

void

Example

chatKit.addEventListener('chatkit.error', (event) => {
  logToMyErrorLogger(event.detail.error);
});

See

https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

Overrides

HTMLElement.addEventListener;

Call Signature

addEventListener(
   type: string,
   listener: null | EventListenerOrEventListenerObject,
   options?: boolean | AddEventListenerOptions): void;

Internal

Parameters

Parameter	Type
type	string
listener	null | EventListenerOrEventListenerObject
options?	boolean | AddEventListenerOptions

Returns

void

Overrides

HTMLElement.addEventListener;

---

fetchUpdates()

fetchUpdates(): Promise<void>;

Manually fetches updates from the server.

Use this when you’ve manually updated the thread or thread items and need to sync them with the client.

Returns

Promise<void>

---

focusComposer()

focusComposer(): Promise<void>;

Focuses the composer input field.

Returns

Promise<void>

---

hideHistory()

hideHistory(): Promise<void>;

Closes the thread history view and returns to the current thread.

Returns

Promise<void>

---

removeEventListener()

Call Signature

removeEventListener<K>(
   type: K,
   listener: EventHandler<K>,
   options?: boolean | EventListenerOptions): void;

Removes an event listener for the specified event.

Type Parameters

Type Parameter
K extends keyof ChatKitEvents

Parameters

Parameter	Type	Description
type	K	See ChatKitEvents for available events.
listener	EventHandler<K>	The event listener callback to remove.
options?	boolean | EventListenerOptions	An object that specifies characteristics about the event listener. See https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener#options

Returns

void

Example

chatKit.removeEventListener('chatkit.error', myErrorListener);

See

https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener

Overrides

HTMLElement.removeEventListener;

Call Signature

removeEventListener(
   type: string,
   listener: null | EventListenerOrEventListenerObject,
   options?: boolean | EventListenerOptions): void;

Internal

Parameters

Parameter	Type
type	string
listener	null | EventListenerOrEventListenerObject
options?	boolean | EventListenerOptions

Returns

void

Overrides

HTMLElement.removeEventListener;

---

sendCustomAction()

sendCustomAction(action: {
  payload?: Record<string, unknown>;
  type: string;
}, itemId?: string): Promise<void>;

Sends a custom application-defined action to your backend. See https://openai.github.io/chatkit-js/guides/widget-actions/ for more details.

Parameters

Parameter	Type	Description
action	{ payload?: Record<string, unknown>; type: string; }	‐
action.payload?	Record<string, unknown>	‐
action.type?	string	‐
itemId?	string	The ID of the WidgetItem that the action is associated with. You may need this if the action was triggered by a widget, gets handled client-side, and then you want to send the action back to the server to do additional handling. Example chatKit.options = { // other options... widgets: { async onAction(action, widgetItem) { await someClientSideHandling(action); await chatkit.sendAction(action, widgetItem.id); }, }, };

Returns

Promise<void>

---

sendUserMessage()

sendUserMessage(params: {
  attachments?: Attachment[];
  content?: UserMessageContent[];
  model?: string;
  newThread?: boolean;
  reply?: string;
  text?: string;
  toolChoice?: ToolChoice;
}): Promise<void>;

Sends a user message.

Parameters

Parameter	Type	Description
params	{ attachments?: Attachment[]; content?: UserMessageContent[]; model?: string; newThread?: boolean; reply?: string; text?: string; toolChoice?: ToolChoice; }	‐
params.attachments?	Attachment[]	Attachment associated with the user message. It must already be uploaded by your server.
params.content?	UserMessageContent[]	Use instead of text when sending structured content such as entity tags.
params.model?	string	‐
params.newThread?	boolean	‐
params.reply?	string	‐
params.text?	string	‐
params.toolChoice?	ToolChoice	toolChoice and model map directly to backend inference_options for the submitted user message. These options do not update the selected tool or model in the composer. Use setComposerValue({ selectedToolId, selectedModelId }) for selection in the composer.

Returns

Promise<void>

---

setComposerValue()

setComposerValue(params: {
  attachments?: Attachment[];
  content?: UserMessageContent[];
  files?: File[];
  reply?: string;
  selectedModelId?: string;
  selectedToolId?: string;
  text?: string;
}): Promise<void>;

Sets the composer’s content without sending a message.

Parameters

Parameter	Type	Description
params	{ attachments?: Attachment[]; content?: UserMessageContent[]; files?: File[]; reply?: string; selectedModelId?: string; selectedToolId?: string; text?: string; }	‐
params.attachments?	Attachment[]	Attachment associated with the user input. It must already be uploaded by your server.
params.content?	UserMessageContent[]	Use instead of text when setting structured content such as entity tags.
params.files?	File[]	Uploads the provided files and attaches them to the composer input. Use this option instead of attachments when the files still need to be sent to the server. Each file must already carry the correct MIME type metadata to be uploaded and rendered correctly.
params.reply?	string	‐
params.selectedModelId?	string	‐
params.selectedToolId?	string	‐
params.text?	string	‐

Returns

Promise<void>

---

setOptions()

setOptions(options: ChatKitOptions): void;

Applies configuration options to the ChatKit instance.

IMPORTANT: New options are not merged with the existing options. You must provide a full set of options every time you call this method.

Parameters

Parameter	Type
options	ChatKitOptions

Returns

void

---

setThreadId()

setThreadId(threadId: null | string): Promise<void>;

Changes the active thread. Pass null to switch to a new thread.

Parameters

Parameter	Type
threadId	null | string

Returns

Promise<void>

---

showHistory()

showHistory(): Promise<void>;

Opens the thread history view.

Intended for apps with a custom header or navigation that need to show history programmatically (for example, from a custom History button).

Returns

Promise<void>