Skip to content
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.

Accepts 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.

Accepts 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.

Accepts 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(api_key: "My API Key")

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

puts(chat_session)
{
  "id": "id",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 0,
      "max_files": 0
    },
    "history": {
      "enabled": true,
      "recent_threads": 0
    }
  },
  "client_secret": "client_secret",
  "expires_at": 0,
  "max_requests_per_1_minute": 0,
  "object": "chatkit.session",
  "rate_limits": {
    "max_requests_per_1_minute": 0
  },
  "status": "active",
  "user": "user",
  "workflow": {
    "id": "id",
    "state_variables": {
      "foo": "string"
    },
    "tracing": {
      "enabled": true
    },
    "version": "version"
  }
}
Returns Examples
{
  "id": "id",
  "chatkit_configuration": {
    "automatic_thread_titling": {
      "enabled": true
    },
    "file_upload": {
      "enabled": true,
      "max_file_size": 0,
      "max_files": 0
    },
    "history": {
      "enabled": true,
      "recent_threads": 0
    }
  },
  "client_secret": "client_secret",
  "expires_at": 0,
  "max_requests_per_1_minute": 0,
  "object": "chatkit.session",
  "rate_limits": {
    "max_requests_per_1_minute": 0
  },
  "status": "active",
  "user": "user",
  "workflow": {
    "id": "id",
    "state_variables": {
      "foo": "string"
    },
    "tracing": {
      "enabled": true
    },
    "version": "version"
  }
}