Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Create a ChatKit session

client.beta.chatkit.sessions.create(body, options?): ChatSession { id, chatkit_configuration, client_secret, 7 more }
POST
/chatkit/sessions

Create a ChatKit session.

Parameters
body: SessionCreateParams { user, workflow, chatkit_configuration, 2 more }
user: string

A free-form string that identifies your end user; ensures this Session can access other objects that have the same user scope.

minLength1
workflow: ChatSessionWorkflowParam { id, state_variables, tracing, version }

Workflow that powers the session.

chatkit_configuration?: ChatSessionChatKitConfigurationParam { automatic_thread_titling, file_upload, history }

Optional overrides for ChatKit runtime configuration features

expires_after?: ChatSessionExpiresAfterParam { anchor, seconds }

Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes.

rate_limits?: ChatSessionRateLimitsParam { max_requests_per_1_minute }

Optional override for per-minute request limits. When omitted, defaults to 10.

Returns
ChatSession { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

id: string

Identifier for the ChatKit session.

chatkit_configuration: ChatSessionChatKitConfiguration { automatic_thread_titling, file_upload, history }

Resolved ChatKit feature configuration for the session.

client_secret: string

Ephemeral client secret that authenticates session requests.

expires_at: number

Unix timestamp (in seconds) for when the session expires.

formatunixtime
max_requests_per_1_minute: number

Convenience copy of the per-minute request limit.

object: "chatkit.session"

Type discriminator that is always chatkit.session.

rate_limits: ChatSessionRateLimits { max_requests_per_1_minute }

Resolved rate limit values.

status: ChatSessionStatus

Current lifecycle state of the session.

user: string

User identifier associated with the session.

workflow: ChatKitWorkflow { id, state_variables, tracing, version }

Workflow metadata for the session.

Create a ChatKit session

import OpenAI from 'openai';

const client = new OpenAI();

const chatSession = await client.beta.chatkit.sessions.create({ user: 'user_123', workflow: { id: 'workflow_alpha' } });

console.log(chatSession.id);

{
  "id": "cksess_123",
  "object": "chatkit.session",
  "client_secret": "ek_example_00eyJleHBpcmVzX2F0IjogMTczNTY4OTYwMH0=",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": null,
    "state_variables": null,
    "tracing": {
      "enabled": true
    }
  },
  "user": "user_123",
  "rate_limits": {
    "max_requests_per_1_minute": 10
  },
  "max_requests_per_1_minute": 10,
  "status": "active",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": false,
      "max_file_size": 512,
      "max_files": 10
    },
    "history": {
      "enabled": true,
      "recent_threads": null
    }
  }
}
Returns Examples
{
  "id": "cksess_123",
  "object": "chatkit.session",
  "client_secret": "ek_example_00eyJleHBpcmVzX2F0IjogMTczNTY4OTYwMH0=",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": null,
    "state_variables": null,
    "tracing": {
      "enabled": true
    }
  },
  "user": "user_123",
  "rate_limits": {
    "max_requests_per_1_minute": 10
  },
  "max_requests_per_1_minute": 10,
  "status": "active",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": false,
      "max_file_size": 512,
      "max_files": 10
    },
    "history": {
      "enabled": true,
      "recent_threads": null
    }
  }
}