ChatKit Starter Template

This repository is the simplest way to bootstrap a ChatKit application. It ships with a minimal Next.js UI, the ChatKit web component, and a ready-to-use session endpoint so you can experiment with OpenAI-hosted workflows built using Agent Builder.

What You Get

• Next.js app with <openai-chatkit> web component and theming controls
• API endpoint for creating a session at app/api/create-session/route.ts
• Config file for starter prompts, theme, placeholder text, and greeting message

Getting Started

1. Install dependencies

npm install

2. Create your environment file

Copy the example file and fill in the required values:

cp .env.example .env.local

You can get your workflow id from the Agent Builder interface, after clicking "Publish":

You can get your OpenAI API key from the OpenAI API Keys page.

3. Configure ChatKit credentials

Update .env.local with the variables that match your setup.

• OPENAI_API_KEY — This must be an API key created within the same org & project as your Agent Builder. If you already have a different OPENAI_API_KEY env variable set in your terminal session, that one will take precedence over the key in .env.local one (this is how a Next.js app works). So, please run unset OPENAI_API_KEY (set OPENAI_API_KEY= for Windows OS) beforehand.
• NEXT_PUBLIC_CHATKIT_WORKFLOW_ID — This is the ID of the workflow you created in Agent Builder, which starts with wf_...
• (optional) CHATKIT_API_BASE - This is a customizable base URL for the ChatKit API endpoint

Note: if your workflow is using a model requiring organization verification, such as GPT-5, make sure you verify your organization first. Visit your organization settings and click on "Verify Organization".

4. Run the app

npm run dev

Visit http://localhost:3000 and start chatting. Use the prompts on the start screen to verify your workflow connection, then customize the UI or prompt list in lib/config.ts and components/ChatKitPanel.tsx.

5. Deploy your app

npm run build

Before deploying your app, you need to verify the domain by adding it to the Domain allowlist on your dashboard.

Customization Tips

• Adjust starter prompts, greeting text, chatkit theme, and placeholder copy in lib/config.ts.
• Update the event handlers inside components/.tsx to integrate with your product analytics or storage.

References

• ChatKit JavaScript Library
• Advanced Self-Hosting Examples