ChatKit JS

The @openai/chatkit-react package provides React bindings for the ChatKit web component. It allows you to build AI-powered chat experiences using React-native patterns like JSX and hooks instead of direct DOM manipulation.

Key features include:

• The <ChatKit /> component for rendering the chat widget.
• The useChatKit hook for managing configuration and handling events within the React lifecycle.
• Full parity with the vanilla JavaScript API while maintaining a React-idiomatic developer experience.

To use ChatKit in a vanilla JavaScript environment:

1. Install the @openai/chatkit package.
2. Create an openai-chatkit element using document.createElement('openai-chatkit').
3. Configure the element using the .setOptions() method, passing an api object with the required url and domainKey.
4. Append the element to a container in your DOM.

<div id="chat-root"></div>
<script type="module">
  import '@openai/chatkit';

  const chatkit = document.createElement('openai-chatkit');

  chatkit.setOptions({
    api: {
      url: 'http://localhost:8000/chatkit',
      domainKey: 'local-dev',
    },
  });

  document.getElementById('chat-root')?.append(chatkit);
</script>

To use ChatKit in a non-React environment, use the <openai-chatkit> Web Component. Create the element, configure it using .setOptions({ api: { url, domainKey } }), and append it to the DOM.

function InitChatkit({ clientToken }) {
  const chatkit = document.createElement('openai-chatkit');
  chatkit.setOptions({ api: { url, domainKey } });
  chatkit.classList.add('h-[600px]', 'w-[320px]');
  document.body.appendChild(chatkit);
}

To embed ChatKit in a React application, use the useChatKit hook to obtain a control object and pass it to the <ChatKit /> component. You must provide an api configuration object containing the url and domainKey.

function MyChat({ clientToken }) {
  const { control } = useChatKit({
    api: { url, domainKey }
  });

  return (
    <ChatKit 
      control={control}
      className="h-[600px] w-[320px]"
    />
  );
}

To get started with ChatKit, follow these four steps:

1. Generate a client token on your server: Create an endpoint (e.g., using FastAPI) that calls openai.chatkit.sessions.create() to return a client_secret.
2. Install React bindings: Install the @openai/chatkit-react package via npm.
3. Add the ChatKit JS script: Include the ChatKit CDN script in your HTML to load the core logic.
4. Render the component: Use the ChatKit component and the useChatKit hook in your React application, providing a getClientSecret function to handle session authentication.

npm install @openai/chatkit-react

To use ChatKit in a React application:

1. Install the @openai/chatkit-react package.
2. Import ChatKit and useChatKit from @openai/chatkit-react.
3. Initialize the chat interface using the useChatKit hook, providing an api configuration object containing the url and domainKey.
4. Pass the returned control object to the ChatKit component.

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function SupportChat() {
  const { control } = useChatKit({
    api: {
      url: 'http://localhost:8000/chatkit',
      domainKey: 'local-dev',
    },
  });

  return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}

The ChatKit component is a React wrapper that renders the <openai-chatkit> web component. It requires a control object, which is obtained from the useChatKit hook. This object synchronizes the hook's state with the component. You can also pass standard HTML attributes (like className or style) and React event handlers, which are forwarded directly to the underlying web component.

<ChatKit control={control} {...props} />

To use ChatKit, you must first include the ChatKit script in your root HTML file. This script should be loaded with the async attribute.

<!-- Add once to your root HTML -->
<script
  src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
  async
></script>

Add the following script tag to your HTML page to load the ChatKit core library asynchronously:

<script
  src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
  async
></script>

To make the openai-chatkit custom element and its associated CustomEvents available globally in your TypeScript project (for example, when using the custom element in JSX without an explicit import), add @openai/chatkit to the types array in your tsconfig.json under compilerOptions.

{
  "compilerOptions": {
    "types": ["@openai/chatkit"]
  }
}