Implementation:Openai Openai node ChatKit Sessions

Knowledge Sources	Openai_Openai_node
Domains	SDK, Beta, ChatKit
Last Updated	2026-02-15 12:00 GMT

Overview

The Sessions resource class provides methods for creating and cancelling ChatKit sessions via the OpenAI ChatKit beta API.

Description

The Sessions class extends APIResource and exposes two methods: create and cancel. The create method sends a POST request to /chatkit/sessions to initialize a new ChatKit session, while cancel sends a POST request to /chatkit/sessions/{sessionID}/cancel to terminate an active session. Both methods include the OpenAI-Beta: chatkit_beta=v1 header to indicate the beta API version.

The SessionCreateParams interface requires a user string (identifying the end user) and a workflow object (specifying the workflow that powers the session). Optional parameters include chatkit_configuration for runtime feature overrides, expires_after for custom session expiration timing (defaults to 10 minutes), and rate_limits for per-minute request limit overrides (defaults to 10).

Both methods return a ChatSession object that contains the session state and configuration.

Usage

Use the Sessions resource to manage the lifecycle of ChatKit sessions. Call create when initializing a new chat experience for a user with a specific workflow, and call cancel when the session should be terminated before its natural expiration.

Code Reference

Source Location

Repository: openai-node
File: src/resources/beta/chatkit/sessions.ts

Signature

export class Sessions extends APIResource {
  create(body: SessionCreateParams, options?: RequestOptions): APIPromise<ChatSession>;
  cancel(sessionID: string, options?: RequestOptions): APIPromise<ChatSession>;
}

export interface SessionCreateParams {
  user: string;
  workflow: ChatSessionWorkflowParam;
  chatkit_configuration?: ChatSessionChatKitConfigurationParam;
  expires_after?: ChatSessionExpiresAfterParam;
  rate_limits?: ChatSessionRateLimitsParam;
}

Import

import OpenAI from 'openai';

I/O Contract

Inputs

Name	Type	Required	Description
user	`string`	Yes	Free-form string identifying the end user; scopes session access to matching objects
workflow	`ChatSessionWorkflowParam`	Yes	Workflow that powers the session (must include `id`)
chatkit_configuration	`ChatSessionChatKitConfigurationParam`	No	Optional overrides for ChatKit runtime configuration features
expires_after	`ChatSessionExpiresAfterParam`	No	Optional session expiration timing in seconds (default: 10 minutes)
rate_limits	`ChatSessionRateLimitsParam`	No	Optional per-minute request limit override (default: 10)

Outputs

Name	Type	Description
ChatSession	`ChatSession`	The created or cancelled ChatKit session object with full state and configuration

Usage Examples

import OpenAI from 'openai';

const client = new OpenAI();

// Create a new ChatKit session
const session = await client.beta.chatkit.sessions.create({
  user: 'user_abc',
  workflow: { id: 'my-workflow-id' },
});
console.log('Session created:', session);

// Cancel an existing session
const cancelled = await client.beta.chatkit.sessions.cancel('cksess_123');
console.log('Session cancelled:', cancelled);

// Create with optional configuration
const customSession = await client.beta.chatkit.sessions.create({
  user: 'user_abc',
  workflow: { id: 'my-workflow-id' },
  expires_after: { seconds: 600 },
  rate_limits: { requests_per_minute: 20 },
});

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment