Session events

Send JSON text frames after the connection opens. Every event has a type. A client can supply an event_id; related acknowledgments and errors return it as client_event_id. Server events have their own event_id. See Connect a live session for session.start parameters.

Client events

Event Fields beyond type and optional event_id Behavior
session.start session Starts the session. This must be the first event.
session.input_audio.append audio: Base64 string Sends input audio in the session format.
session.input_audio.mute None Replaces input with silence. Replies and delegated work continue.
session.input_audio.unmute None Restores input audio.
session.commentary.append content: nonempty string; delegation_id: string or null Supplies a result or context that the voice can say.
session.instructions.append Same fields as commentary Adds trusted instructions for the voice. These can interrupt speech. They do not change backend instructions.
session.thinking.append Same fields as commentary Adds silent context. The voice can use it later.
response.item.create item: object Supplies a function result or a text message in backend mode.
response.create None Continues the backend after tool results, or starts a backend response.
session.update session.delegation: object Updates backend settings for later requests. The delegation object must include its unchanged type.
session.close None Ends the session with reason close_requested.

Each context append permits at most 500 tokens. Use the ID from session.delegation.created for client delegation results. Several commentary updates can use the same completed client delegation ID. Use null or omit delegation_id for context unrelated to a client delegation. Backend mode refuses a non-null delegation_id on a context append.

A function result uses this shape:

{"type":"response.item.create","item":{"type":"function_call_output","call_id":"<call_id>","output":"The requested task is complete."}}

Send response.create after the function results. A text message uses item.type: "message", a text content array, and role user, developer, system, or assistant. The message remains available as context for later responses.

session.update accepts only session.delegation. Its responses object accepts the backend settings in Connect a live session. The delegation type, delegation mode, voice, audio format, and storage choice cannot change during a session.

Server events

Event Fields Meaning
session.started session The server accepted the start parameters.
session.updated session, optional client_event_id The server accepted an update.
session.output_audio.delta delta Base64 output audio in the session format.
session.output_audio.cleared event_id Stop the current reply's playback. Drop its queued audio. Later audio belongs to the next reply.
session.input_transcript.delta delta, start_ms, end_ms Recognized input text, with times on the input audio timeline.
session.output_transcript.delta delta, start_ms, end_ms Spoken output text. The text follows estimated playback time.
session.input_audio.muted Optional client_event_id Input is muted.
session.input_audio.unmuted Optional client_event_id Input is unmuted.
session.commentary.appended start_ms, end_ms, optional client_event_id The server accepted commentary.
session.instructions.appended start_ms, end_ms, optional client_event_id The server accepted instructions.
session.thinking.appended start_ms, end_ms, optional client_event_id The server accepted silent context.
session.delegation.created delegation, offset_ms, optional client_event_id A task needs external work. See the fields below.
response.event delegation_id, event A client-visible backend Responses event.
session.usage.updated usage.seconds, context_window.usage_ratio Session time and context use, sent every 15 seconds.
session.closed reason, session, usage.seconds The session ended.
error error, optional client_event_id The server refused an event or reports a failure.

A delegation object contains id, type: "delegation", and target (client or responses). Backend mode also supplies delegation.response_id. The event carries offset_ms at its top level. In backend mode, session.delegation.created can also carry client_event_id after a client response.create. The event contains no task text; a client uses the transcripts for context.

The session resource contains id, model, status, expires_at, audio, delegation, store, and input. It includes nonempty instructions. audio.output.voice reports the effective voice, including the default. expires_at is a Unix timestamp in seconds.

Close reasons are close_requested, expired, and connection_lost. After session.close, an active backend response can forward events for up to ten seconds before session.closed. Session duration excludes that wait.

Admission errors

HTTP status error.code Meaning
401 invalid_api_key Missing or invalid credentials.
402 insufficient_funds The organization lacks funds.
403 insufficient_scope The key cannot open a paid session.
429 session_limit Session capacity is full. Retry after a session ends.
503 server_error Session admission is unavailable. Retry after service recovery.

Header clients receive these errors before the WebSocket opens. Browser clients receive one error event followed by a close, as Connect a live session describes. A capacity refusal can precede credential validation.

Event errors

The error object contains type, code, and message. It includes param when a field caused the error. An invalid start closes with code 1008. A refused event after startup generally leaves the session open.

error.code Cause
invalid_request Invalid event shape, invalid Base64 audio, empty context, or an invalid delegation or function-call ID.
invalid_value Invalid voice or delegation mode, or text above its token limit.
array_above_max_length More than 128 initial messages.
unknown_parameter An unsupported field in session.update.
missing_required_parameter A required update field is absent.
immutable_field_update An update changes the delegation type or mode.
unsupported_field A start field, backend setting, or requested storage option is unsupported.
unknown_event The event type is unknown.
unsupported_event A second session.start is not served after startup.
model_not_found The session model is wrong or the backend model is unavailable.
input_audio_rate_limit_exceeded Input audio exceeds the accepted rate. Pace audio at real time.
engine_unavailable The session cannot start, or voice validation is unavailable.
engine_error Speech processing failed during the session.
recording_failed The session recording was not saved.
{"type":"error","event_id":"event_1","error":{"type":"invalid_request_error","code":"invalid_value","message":"delegation.mode must be off, auto, or always.","param":"session.delegation.mode"}}