Skip to content
Primary navigation

Suggested
API Dashboard
API Reference
Beta
ChatKit
Sessions

Create ChatKit session

beta.chatkit.sessions.create(**kwargs) -> ChatSession { id, chatkit_configuration, client_secret, 7 more }
POST/chatkit/sessions

Create a ChatKit session.

ParametersExpand Collapse
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.

id: String

Identifier for the workflow invoked by the session.

state_variables: Hash[Symbol, String | bool | Float]

State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object.

One of the following:
String
bool
Float
tracing: { enabled}

Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default.

enabled: bool

Whether tracing is enabled during the session. Defaults to true.

version: String

Specific workflow version to run. Defaults to the latest deployed version.

chatkit_configuration: ChatSessionChatKitConfigurationParam { automatic_thread_titling, file_upload, history }

Optional overrides for ChatKit runtime configuration features

automatic_thread_titling: { enabled}

Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.

enabled: bool

Enable automatic thread title generation. Defaults to true.

file_upload: { enabled, max_file_size, max_files}

Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).

enabled: bool

Enable uploads for this session. Defaults to false.

max_file_size: Integer

Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size.

maximum512
minimum1
max_files: Integer

Maximum number of files that can be uploaded to the session. Defaults to 10.

minimum1
history: { enabled, recent_threads}

Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null).

enabled: bool

Enables chat users to access previous ChatKit threads. Defaults to true.

recent_threads: Integer

Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.

minimum1
expires_after: ChatSessionExpiresAfterParam { anchor, seconds }

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

anchor: :created_at

Base timestamp used to calculate expiration. Currently fixed to created_at.

seconds: Integer

Number of seconds after the anchor when the session expires.

maximum600
minimum1
rate_limits: ChatSessionRateLimitsParam { max_requests_per_1_minute }

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

max_requests_per_1_minute: Integer

Maximum number of requests allowed per minute for the session. Defaults to 10.

minimum1
ReturnsExpand Collapse
class 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.

automatic_thread_titling: ChatSessionAutomaticThreadTitling { enabled }

Automatic thread titling preferences.

enabled: bool

Whether automatic thread titling is enabled.

file_upload: ChatSessionFileUpload { enabled, max_file_size, max_files }

Upload settings for the session.

enabled: bool

Indicates if uploads are enabled for the session.

max_file_size: Integer

Maximum upload size in megabytes.

max_files: Integer

Maximum number of uploads allowed during the session.

history: ChatSessionHistory { enabled, recent_threads }

History retention configuration.

enabled: bool

Indicates if chat history is persisted for the session.

recent_threads: Integer

Number of prior threads surfaced in history views. Defaults to null when all history is retained.

client_secret: String

Ephemeral client secret that authenticates session requests.

expires_at: Integer

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

max_requests_per_1_minute: Integer

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.

max_requests_per_1_minute: Integer

Maximum allowed requests per one-minute window.

status: ChatSessionStatus

Current lifecycle state of the session.

One of the following:
:active
:expired
:cancelled
user: String

User identifier associated with the session.

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

Workflow metadata for the session.

id: String

Identifier of the workflow backing the session.

state_variables: Hash[Symbol, String | bool | Float]

State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided.

One of the following:
String
bool
Float
tracing: { enabled}

Tracing settings applied to the workflow.

enabled: bool

Indicates whether tracing is enabled.

version: String

Specific workflow version used for the session. Defaults to null when using the latest deployment.

Create ChatKit session

require "openai"

openai = OpenAI::Client.new

chat_session = openai.beta.chatkit.sessions.create(user: "user", workflow: {id: "id"})

puts(chat_session)

{
  "client_secret": "chatkit_token_123",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": "2024-10-01"
  },
  "scope": {
    "project": "alpha",
    "environment": "staging"
  },
  "max_requests_per_1_minute": 60,
  "max_requests_per_session": 500,
  "status": "active"
}
Returns Examples
{
  "client_secret": "chatkit_token_123",
  "expires_at": 1735689600,
  "workflow": {
    "id": "workflow_alpha",
    "version": "2024-10-01"
  },
  "scope": {
    "project": "alpha",
    "environment": "staging"
  },
  "max_requests_per_1_minute": 60,
  "max_requests_per_session": 500,
  "status": "active"
}