ChatKit

ChatKit is the best way to build agentic chat experiences. Whether you’re building an internal knowledge base assistant, HR onboarding helper, research companion, shopping or scheduling assistant, troubleshooting bot, financial planning advisor, or support agent, ChatKit provides a customizable chat embed to handle all user experience details.

Use ChatKit’s embeddable UI widgets, customizable prompts, tool‑invocation support, file attachments, and chain‑of‑thought visualizations to build agents without reinventing the chat UI.

Overview

Choose between two ChatKit paths:

• Custom server integration. Run ChatKit on your own infrastructure. Use the ChatKit Python SDK and connect to any agentic service, including one built with the Agents SDK. Use widgets to build the frontend.
• Existing Agent Builder-hosted integration. If you already use ChatKit with an Agent Builder workflow, you can keep using that hosted workflow during the Agent Builder transition window.

Get started with ChatKit

Custom server integration

Use any backend and the ChatKit SDKs to build your own custom ChatKit user experience

Existing hosted workflow

Connect ChatKit to an existing Agent Builder workflow during the transition window

Embed ChatKit in your frontend

Use this path only if you already have an Agent Builder workflow that backs your ChatKit implementation. For new ChatKit apps, or when migrating before Agent Builder shuts down, use the advanced integration to connect ChatKit to your own server-side agent implementation.

At a high level, setting up ChatKit with an existing hosted workflow is a three-step process. Open your existing workflow while Agent Builder remains available. Then set up ChatKit and add features to build your chat experience.

1. Use an existing hosted workflow

Open your existing workflow in Agent Builder. You’ll get a workflow ID. For transition planning, see Migrate from Agent Builder.

The chat embedded in your frontend will point to the workflow you select.

2. Set up ChatKit in your product

To set up ChatKit, you’ll create a ChatKit session and create a backend endpoint, pass in your workflow ID, exchange the client secret, add a script to embed ChatKit on your site.

Important Security Note: When creating a ChatKit session, you must pass in a user parameter, which should be unique for each individual end user. It is your backend’s responsibility to authenticate your application’s users and pass a unique identifier for them in this parameter.

1. On your server, generate a client token.

   This snippet spins up a FastAPI service whose sole job is to create a new ChatKit session via the OpenAI Python SDK and hand back the session’s client secret:

   server.py

   python

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   from fastapi import FastAPI
   from pydantic import BaseModel
   from openai import OpenAI
   import os
   
   app = FastAPI()
   openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
   
   @app.post("/api/chatkit/session")
   def create_chatkit_session():
       session = openai.chatkit.sessions.create({
         # ...
       })
       return { client_secret: session.client_secret }

2. In your server-side code, pass in your workflow ID and secret key to the session endpoint.

   The client secret is the credential that your ChatKit frontend uses to open or refresh the chat session. You don’t store it; you immediately hand it off to the ChatKit client library.

   See the chatkit-js repo on GitHub.

   chatkit.ts

   typescript

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   export default async function getChatKitSessionToken(
   deviceId: string
   ): Promise<string> {
   const response = await fetch("https://api.openai.com/v1/chatkit/sessions", {
       method: "POST",
       headers: {
       "Content-Type": "application/json",
       "OpenAI-Beta": "chatkit_beta=v1",
       Authorization: "Bearer " + process.env.VITE_OPENAI_API_SECRET_KEY,
       },
       body: JSON.stringify({
       workflow: { id: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1" },
       user: deviceId,
       }),
   });
   
   const { client_secret } = await response.json();
   
   return client_secret;
   }

3. In your project directory, install the ChatKit React bindings:

   npm install @openai/chatkit-react

4. Add the ChatKit JS script to your page. Drop this snippet into your page’s <head> or wherever you load scripts, and the browser will fetch and run ChatKit for you.

   index.html

   html

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

5. Render ChatKit in your UI. This code fetches the client secret from your server and mounts a live chat widget connected to your workflow.

   Your frontend code

   react

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   import { ChatKit, useChatKit } from '@openai/chatkit-react';
   
      export function MyChat() {
        const { control } = useChatKit({
          api: {
            async getClientSecret(existing) {
              if (existing) {
                // implement session refresh
              }
   
              const res = await fetch('/api/chatkit/session', {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json',
                },
              });
              const { client_secret } = await res.json();
              return client_secret;
            },
          },
        });
   
        return <ChatKit control={control} className="h-[600px] w-[320px]" />;
      }

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   const chatkit = document.getElementById('my-chat');
   
     chatkit.setOptions({
       api: {
         getClientSecret(currentClientSecret) {
           if (!currentClientSecret) {
             const res = await fetch('/api/chatkit/start', { method: 'POST' })
             const {client_secret} = await res.json();
             return client_secret
           }
           const res = await fetch('/api/chatkit/refresh', {
             method: 'POST',
             body: JSON.stringify({ currentClientSecret })
             headers: {
               'Content-Type': 'application/json',
             },
           });
           const {client_secret} = await res.json();
           return client_secret
         }
       },
     });

3. Build and iterate

See the custom theming, widgets, and actions docs to learn more about how ChatKit works. Or explore the following resources to test your chat, iterate on prompts, and add widgets and tools.

Build your implementation

Explore ChatKit UI

See working examples

Next steps

When you’re happy with your ChatKit implementation, learn how to optimize it with evals. For new ChatKit apps, or to move an existing ChatKit app off an Agent Builder-hosted workflow, see the advanced integration docs.