ChatKit

Purpose and Scope

ChatKit is the OpenAI product surface for building agentic chat experiences with an embeddable chat interface, widgets, file attachments, tool invocation support, and action-driven interactions. In this SDK, the relevant server-side API is exposed as a beta resource under the client namespace, so Node and TypeScript applications can create and manage ChatKit sessions while their frontend uses the ChatKit UI primitives described in the platform guides. The page focuses on what the openai-node package exposes: the beta ChatKit namespace, session lifecycle calls, workflow metadata, and typed thread/session objects that connect a backend session to a ChatKit conversation.

Sources: src/resources/beta/chatkit.ts, src/resources/beta/chatkit/index.ts, src/resources/beta/chatkit/chatkit.ts

The product documentation distinguishes between ChatKit frontend concepts and backend integration responsibilities. Widgets are UI containers and components; actions are payloads triggered by widget events or imperative frontend calls; sessions are the backend-scoped objects that allow a user-facing chat instance to talk to a workflow or server integration. The TypeScript SDK does not define the frontend widget renderer in the supplied source evidence. Instead, it gives backend code a typed way to create sessions, cancel sessions, and work with ChatKit thread and item types returned by the API.

Sources: src/resources/beta/chatkit/sessions.ts, src/resources/beta/chatkit/index.ts

Relevant Source Files

• src/resources/beta/chatkit.ts - Re-exports the beta ChatKit index so consumers can reach the generated ChatKit beta surface through the SDK package.
• src/resources/beta/chatkit/index.ts - Collects and re-exports the ChatKit resource class, session params, and thread-related response and pagination types.
• src/resources/beta/chatkit/chatkit.ts - Defines the ChatKit APIResource subclass, attaches sessions and threads resource instances, and declares workflow metadata types.
• src/resources/beta/chatkit/sessions.ts - Implements session creation and cancellation, including beta headers, bearer authentication, request body typing, and returned chat session typing.
• src/resources/chat/index.ts - Shows the stable chat namespace exports, useful for contrasting ChatKit with conventional chat generation resources.
• src/resources/chat/completions/index.ts - Exposes Chat Completions types and helpers adjacent to, but separate from, ChatKit session-oriented workflows.

System-to-Code Mapping

The SDK surface is layered as a generated resource tree. The short beta file re-exports the ChatKit index, and the index re-exports the concrete resource class plus related generated types. The concrete class extends the shared API resource base and creates two child resources named sessions and threads. That structure means application code should think of ChatKit as a resource family rather than a single method: sessions represent issued access to a ChatKit experience, while threads represent conversation state and thread items. The exported types make this resource family usable from TypeScript without hand-writing response shapes.

Sources: src/resources/beta/chatkit.ts, src/resources/beta/chatkit/index.ts, src/resources/beta/chatkit/chatkit.ts

The thread type exports reveal the shape of the conversation concepts that the SDK expects callers to handle. Names such as ChatSession, ChatKitThread, ChatKitThreadUserMessageItem, ChatKitThreadAssistantMessageItem, ChatKitWidgetItem, ChatKitAttachment, and ChatKitResponseOutputText distinguish metadata, user-visible messages, assistant messages, widget payloads, attachments, and text output. Even when an application delegates much of the interface to ChatKit frontend widgets, these names matter on the server because they describe what may be returned from session and thread operations and what a strongly typed integration can inspect.

Sources: src/resources/beta/chatkit/index.ts, src/resources/beta/chatkit/chatkit.ts

Core Primitives

A ChatKit session is the backend object created for a specific end user and workflow. The create call requires a user string and a workflow descriptor, then returns a ChatSession. The parameter comments explain that the user field scopes access so the session can reach other objects with the same user scope. Optional configuration fields allow a backend to override runtime ChatKit configuration, expiration timing, and per-minute rate limits. The generated comments also document defaults: expiration defaults to ten minutes, and omitted rate limits default to ten requests per minute.

Sources: src/resources/beta/chatkit/sessions.ts

A workflow is modeled as metadata and state returned for the session. The ChatKitWorkflow interface contains an identifier, optional state variable overrides, tracing settings, and an optional workflow version. The tracing object includes a boolean enabled field. This type mirrors the product idea that a ChatKit experience is backed by a workflow or server-side agent implementation, but the SDK keeps the representation concrete: workflow identity, version selection, state variables, and tracing configuration are normal typed response data rather than opaque frontend-only concepts.

Sources: src/resources/beta/chatkit/chatkit.ts

Widgets and actions fit around the SDK surface rather than inside the session method itself. The official guides describe widgets as customizable cards, rows, shortcuts, and components that can emit actions. Those actions are usually sent to a server, where backend code can perform side effects, update state, or stream new thread items. In a TypeScript backend using this SDK, the ChatKit beta resources are the API bridge for session and thread management, while the widget action handler remains application code that decides how to respond to the incoming action payload.

Sources: src/resources/beta/chatkit/index.ts, src/resources/beta/chatkit/sessions.ts

Execution Flow

A typical hosted-workflow integration starts on the backend, not in the browser. The server creates a ChatKit session for the current authenticated application user, supplies the workflow identifier, and optionally tightens expiration or rate limits for that particular session. The create method posts to the ChatKit sessions endpoint, adds the required beta opt-in header, and uses bearer authentication through the SDK client. The returned ChatSession can then be used by the application integration to initialize the user-facing ChatKit experience without exposing a long-lived API key to the frontend.

Sources: src/resources/beta/chatkit/sessions.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});
 
const chatSession = await client.beta.chatkit.sessions.create({
  user: 'user_123',
  workflow: { id: 'workflow_abc' },
});

When a session should no longer accept new requests, the backend can cancel it by identifier. The cancellation method posts to a session-specific cancel endpoint and returns the most recent ChatSession metadata. The generated comment is important for operational design: cancelling prevents new requests from using the issued client secret. That makes cancellation a fit for logout, administrator revocation, workflow handoff, or cleanup after a sensitive support session. Existing application state still needs normal product-level handling; the SDK method is specifically about invalidating future use of that issued ChatKit session credential.

Sources: src/resources/beta/chatkit/sessions.ts

API Components

The compact API contract is centered on the beta namespace. The ChatKit resource has sessions and threads children. Sessions exposes create and cancel methods. The create method accepts SessionCreateParams and returns an API promise of ChatSession. The cancel method accepts a session identifier string and also returns an API promise of ChatSession. Both methods attach the OpenAI-Beta header value for the ChatKit beta and declare bearer authentication. Those details mean callers usually rely on the standard OpenAI client configuration for credentials while the generated resource handles the endpoint path and beta header.

Sources: src/resources/beta/chatkit/chatkit.ts, src/resources/beta/chatkit/sessions.ts

The chat resource files are useful mainly as a boundary marker. They export the stable Chat and Chat Completions namespaces, including message parameters, tool choice types, streaming options, message listing, and completion response types. ChatKit should not be treated as a replacement spelling for chat completions. Chat Completions is a direct model-generation API centered on messages and completions; ChatKit is a higher-level chat experience surface centered on sessions, threads, widgets, and workflow-backed UI. Applications may use both, but their SDK entrypoints and typed contracts are intentionally distinct.

Sources: src/resources/chat/index.ts, src/resources/chat/completions/index.ts, src/resources/beta/chatkit/index.ts

Implementation Details and Next Steps

Because this surface is generated from the OpenAPI specification, the SDK follows the same conventions used by other generated resources in the package: resource classes extend the shared API base, request methods return APIPromise values, and request customization is passed through RequestOptions. The session methods merge caller-provided options with generated headers, so advanced callers can still supply per-request options while preserving the required ChatKit beta opt-in. For production integrations, pair this API usage with normal client configuration, server-side authentication, short-lived session issuance, and careful handling of user identity scope.

Sources: src/resources/beta/chatkit/sessions.ts, src/resources/beta/chatkit/chatkit.ts

Next, read the general client configuration page if you need to control API keys, organization or project headers, custom fetch behavior, request options, retries, and timeouts. Read the streaming and Responses pages if your ChatKit backend action handler will run model inference or stream new items after a widget action. Read the tools and approvals pages if widget actions need to trigger function-like backend work. Finally, use the official ChatKit widget and action guides when designing the frontend, because those guides define the user-interface contracts that surround the beta SDK session and thread resources.

Sources: src/resources/beta/chatkit/index.ts, src/resources/beta/chatkit/sessions.ts