# Sessions ## Accept call `client.live.sessions.accept(stringsessionID, SessionAcceptParamsbody, RequestOptionsoptions?): void` **post** `/live/sessions/{session_id}/accept` Accept an incoming SIP call. Supply session with type live, the model, and startup configuration. Before accepting calls, follow the [Live prompting guide](/api/docs/guides/live-prompting) to write frontend conversation instructions and a separate backend prompt. SIP media format is negotiated; omit audio.format. ### Parameters - `sessionID: string` - `body: SessionAcceptParams` - `session: Session` Model and startup configuration for the Live session that answers the incoming SIP call. - `model: (string & {}) | "gpt-live-1"` The Live model to use for the accepted call. - `(string & {})` - `"gpt-live-1"` - `"gpt-live-1"` - `type: "live"` The session type. Always `live`. - `"live"` - `audio?: Audio` Startup audio output configuration. SIP negotiates the media format; audio.format is only accepted for primary WebSockets. Voice cannot change after startup. - `output?: Output` Settings for speech generated by the Live model. Choose the voice before starting the session. - `voice?: string | BuiltInVoice | CustomVoice` The voice used for Live speech, as a built-in voice name or a custom voice object containing its ID. Defaults to `marin` and cannot change after startup. - `string` - `BuiltInVoice = "alloy" | "ash" | "ballad" | 20 more` A built-in voice available for Live speech. - `"alloy"` - `"ash"` - `"ballad"` - `"beacon"` - `"bossa"` - `"cedar"` - `"cinder"` - `"coral"` - `"delta"` - `"echo"` - `"gleam"` - `"marin"` - `"meridian"` - `"quartz"` - `"ripple"` - `"sage"` - `"shida"` - `"shimmer"` - `"stone"` - `"tempo"` - `"verse"` - `"vesper"` - `"willow"` - `CustomVoice` - `id: string` - `delegation?: ClientDelegation | Responses | Decisions | null` Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` or `decisions` to delegate to the corresponding API. - `ClientDelegation` Delegate tasks to your application. The Live session emits delegation events that your backend handles. - `type: "client"` The delegation owner. Always `client` for tasks handled by your application. - `"client"` - `acknowledgement_delay_ms?: number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. - `Responses` Delegate tasks to a Responses model managed by the Live session. - `responses: ResponsesDelegationConfig` Backend model, prompt, and tools used when the Live session delegates a task to Responses. - `model: string` The model used for server-owned Responses delegations. - `instructions?: string | null` Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). - `max_output_tokens?: number | null` Maximum number of output tokens for each delegated response. - `parallel_tool_calls?: boolean | null` Whether the delegated Responses model may request multiple tool calls in a single response. - `reasoning?: Reasoning | null` Reasoning settings passed to each delegated Responses request. - `effort?: "none" | "minimal" | "low" | 3 more | null` How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `summary?: "concise" | "detailed" | "auto" | null` The reasoning summary to request from the delegated Responses model, when supported. - `"concise"` - `"detailed"` - `"auto"` - `service_tier?: "auto" | "default" | "fast_tier_temp_pilot" | 3 more | null` Service tier for delegated Responses requests. - `"auto"` - `"default"` - `"fast_tier_temp_pilot"` - `"flex"` - `"priority"` - `"ultrafast"` - `text?: Text | null` Text generation settings passed to each delegated Responses request. - `verbosity?: "low" | "medium" | "high" | null` The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery. - `"low"` - `"medium"` - `"high"` - `tool_choice?: "auto" | "none" | "required" | LiveFunctionToolChoiceParam | LiveMCPToolChoiceParam` Controls which tool the Responses backend uses when handling a task delegated by the Live model. - `"auto" | "none" | "required"` - `"auto"` - `"none"` - `"required"` - `LiveFunctionToolChoiceParam` - `name: string` - `type: "function"` - `"function"` - `LiveMCPToolChoiceParam` - `name: string` - `server_label: string` - `type: "mcp"` - `"mcp"` - `tools?: Array` Tools available to the Responses backend while it handles tasks delegated by the Live model. - `FunctionTool` A function tool available to the Responses backend when the Live model delegates a task. - `name: string` The name the delegated Responses model uses when calling this function. - `type: "function"` The tool type. Always `function`. - `"function"` - `description?: string | null` What the function does and when the delegated Responses model should call it. - `parameters?: Record | null` A JSON Schema object describing the arguments accepted by the function. - `strict?: boolean | null` Whether the delegated Responses model must follow the function’s parameter schema exactly. - `WebSearch` A web search tool available to the Live session’s Responses backend. - `type: "web_search"` The tool type. Always `web_search`. - `"web_search"` - `type: "responses"` The delegation owner. Always `responses` for tasks handled by the Responses API. - `"responses"` - `acknowledgement_delay_ms?: number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. - `Decisions` - `decisions: DecisionsDelegationConfig` - `model: string` - `questions: Array` Native Decision API questions evaluated together, in order. - `QuestionParamPredicate` Estimate how likely it is that a statement about the input is true. - `instructions: string | Array` - `string` - `Array` - `DecisionQuestionInputText` - `text: string` - `type: "input_text"` - `"input_text"` - `DecisionQuestionInputImage` An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - `image_url: string` A base64-encoded image in a data URL or a publicly accessible HTTP(S) image URL. - `type: "input_image"` - `"input_image"` - `detail?: "low" | "high" | "auto" | "original" | null` The image detail level, using the selected model's image profile. Defaults to auto. - `"low"` - `"high"` - `"auto"` - `"original"` - `DecisionInputJSON` A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - `data: Record | Array>` - `Record` - `Array>` - `type: "input_json"` - `"input_json"` - `type: "predicate"` The type of the object. Always `predicate`. - `"predicate"` - `name?: string` - `QuestionParamChoice` Choose from the supplied options based on the input. - `choices: Array` Provide between 2 and 255 choices. Each choice must be unique. - `value: string | boolean` Choice values are typed: a string and a boolean with the same text are distinct. - `string` - `boolean` - `description?: string` - `instructions: string | Array` - `string` - `Array` - `DecisionQuestionInputText` - `DecisionQuestionInputImage` An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - `DecisionInputJSON` A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - `type: "choice"` The type of the object. Always `choice`. - `"choice"` - `name?: string` - `QuestionParamScore` Rate the input against the supplied ordered levels. - `instructions: string | Array` - `string` - `Array` - `DecisionQuestionInputText` - `DecisionQuestionInputImage` An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - `DecisionInputJSON` A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - `levels: Array` - `label: string` - `description?: string` - `type: "score"` The type of the object. Always `score`. - `"score"` - `name?: string` - `type: "decisions"` - `"decisions"` - `acknowledgement_delay_ms?: number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400. Updates apply to subsequent delegations. - `input?: Array` Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and a configured rendered-token limit (8,192 by default). - `Developer` A developer message included in the initial text history of a Live session. - `content: Array` The message content. Supply exactly one text part for the initial Live conversation history. - `text: string` The message text to include in the Live session’s initial conversation history. - `type?: "input_text"` The text content type. Always `input_text`. - `"input_text"` - `role: "developer"` The author of this history message. Always `developer`. - `"developer"` - `id?: string | null` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status?: "incomplete" | "completed" | null` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type?: "message"` The history item type. Always `message`. - `"message"` - `User` A user message included in the initial text history of a Live session. - `content: Array` The message content. Supply exactly one text part for the initial Live conversation history. - `text: string` The message text to include in the Live session’s initial conversation history. - `type?: "input_text"` The text content type. Always `input_text`. - `"input_text"` - `role: "user"` The author of this history message. Always `user`. - `"user"` - `id?: string | null` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status?: "incomplete" | "completed" | null` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type?: "message"` The history item type. Always `message`. - `"message"` - `Assistant` An assistant message included in the initial text history of a Live session. - `content: Array` The message content. Supply exactly one text part for the initial Live conversation history. - `Text` Assistant text supplied as conversation history when starting a Live session. - `text: string` The message text to include in the Live session’s initial conversation history. - `type?: "text"` The text content type. Always `text`. - `"text"` - `OutputText` Assistant output text supplied as conversation history when starting a Live session. - `text: string` The message text to include in the Live session’s initial conversation history. - `type: "output_text"` The text content type. Always `output_text`. - `"output_text"` - `role: "assistant"` The author of this history message. Always `assistant`. - `"assistant"` - `id?: string | null` An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation. - `status?: "incomplete" | "completed" | null` The supplied message’s status. Live uses its text as history and does not resume an incomplete message. - `"incomplete"` - `"completed"` - `type?: "message"` The history item type. Always `message`. - `"message"` - `instructions?: string | null` Frontend instructions for voice, conversation, interruptions, and when to delegate. Start with the [Live prompting guide](/api/docs/guides/live-prompting); put business rules and tool workflows in a separate [backend prompt](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). Limited to 16,384 client-supplied tokens. Omitted or blank instructions use server defaults. Immutable after startup. - `store?: boolean` Whether to store the session for later forking and recording download. Defaults to false for new sessions. - `triggers?: Array` At most one Decisions trigger per transcript event type. Triggers run independently of delegation. On update, omit triggers to keep the current configuration, send a list to replace it, or send an empty list to disable triggers. - `decisions: Decisions` Questions evaluated using the current transcript and the session's shared Decision items. - `questions: Array` Native Decision API questions evaluated together, in order. - `QuestionParamPredicate` Estimate how likely it is that a statement about the input is true. - `instructions: string | Array` - `string` - `Array` - `DecisionQuestionInputText` - `DecisionQuestionInputImage` An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - `DecisionInputJSON` A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - `type: "predicate"` The type of the object. Always `predicate`. - `"predicate"` - `name?: string` - `QuestionParamChoice` Choose from the supplied options based on the input. - `choices: Array` Provide between 2 and 255 choices. Each choice must be unique. - `value: string | boolean` Choice values are typed: a string and a boolean with the same text are distinct. - `string` - `boolean` - `description?: string` - `instructions: string | Array` - `string` - `Array` - `DecisionQuestionInputText` - `DecisionQuestionInputImage` An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - `DecisionInputJSON` A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - `type: "choice"` The type of the object. Always `choice`. - `"choice"` - `name?: string` - `QuestionParamScore` Rate the input against the supplied ordered levels. - `instructions: string | Array` - `string` - `Array` - `DecisionQuestionInputText` - `DecisionQuestionInputImage` An image provided as a base64 data URL or a publicly accessible HTTP(S) URL. File IDs are not supported. - `DecisionInputJSON` A JSON object or an array of objects rendered as text. Nested values may be any JSON value. Limited to 32 container levels, 10,000 values, and 256 KiB of compact UTF-8 JSON. - `levels: Array` - `label: string` - `description?: string` - `type: "score"` The type of the object. Always `score`. - `"score"` - `name?: string` - `event_type: "session.input_transcript.delta" | "session.output_transcript.delta"` - `"session.input_transcript.delta"` - `"session.output_transcript.delta"` - `type: "decisions"` - `"decisions"` ### Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted }); await client.live.sessions.accept('session_id', { session: { model: 'gpt-live-1', type: 'live' } }); ``` ## Download recording `client.live.sessions.downloadRecording(stringsessionID, RequestOptionsoptions?): Response` **get** `/live/sessions/{session_id}/content` Get Live session content ### Parameters - `sessionID: string` The ID of the stored Live session to download. Use the session ID returned when the session started with storage enabled. ### Returns - `unnamed_schema_3 = Response` ### Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted }); const response = await client.live.sessions.downloadRecording('live_SQ'); console.log(response); const content = await response.blob(); console.log(content); ``` ## Fork session `client.live.sessions.fork(stringsessionID, SessionForkParamsbody, RequestOptionsoptions?): SessionForkResponse` **post** `/live/sessions/{session_id}/fork` Fork a stored Live session onto a new WebRTC connection. ### Parameters - `sessionID: string` - `body: SessionForkParams` - `transport: Transport` WebRTC transport with an SDP offer for the new connection to the forked session. - `sdp: string` Session Description Protocol message for the WebRTC connection. - `type: "webrtc"` The transport used for the Live session. Always `webrtc`. - `"webrtc"` - `session?: MediaSessionForkConfig` Optional configuration overrides for the new Live session. Omit this object or send an empty object to inherit the stored session's settings. - `client?: ClientConfig` Startup-only capabilities for an untrusted frontend attached to a unified WebRTC session. Trusted sideband connections are unaffected. - `data_channel: DataChannelConfig` Client and server event permissions for the WebRTC frontend data channel. - `allowed_client_events?: "all" | Array` Client event types that the frontend data channel may send. Use 'all' to allow every client event; an empty array allows none. Omission preserves the existing allow-all behavior. - `"all"` - `"all"` - `Array` - `allowed_server_events?: "all" | Array` Server events that may be sent to the frontend data channel. Use 'all' to allow every server event; an empty array allows none. Omission preserves the existing allow-all behavior. Responses events use an object with type 'response.event' and a response_event selector. - `"all"` - `"all"` - `Array` - `type: string` The outer Live server event type. Use 'response.event' for Responses events. - `response_event?: string` The nested Responses event type. Required when type is 'response.event'; forbidden for other event types. - `delegation?: Delegation` Update the Responses backend for an existing Live session without changing delegation ownership. - `type: "responses"` The delegation owner. Always `responses` for tasks handled by the Responses API. - `"responses"` - `acknowledgement_delay_ms?: number` Milliseconds to wait before requesting an automatic spoken acknowledgement for a delegation. The model may still speak before this delay. Any commentary or thinking appended to the session cancels all pending acknowledgements, including those for other delegations. Defaults to 400 for Decisions sessions and 0 (request immediately) for other sessions. Omission in a session update preserves the current value. Updates apply to subsequent delegations. - `responses?: ResponsesDelegationUpdateConfig` Responses backend settings to update. Omitted settings keep their existing values. - `instructions?: string | null` Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt). - `max_output_tokens?: number | null` Maximum number of output tokens for each delegated response. - `model?: string` The Responses backend model to use for subsequent delegated requests. Omit to keep the current backend model. - `parallel_tool_calls?: boolean | null` Whether the delegated Responses model may request multiple tool calls in a single response. - `reasoning?: Reasoning | null` Reasoning settings passed to each delegated Responses request. - `effort?: "none" | "minimal" | "low" | 3 more | null` How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model. - `"none"` - `"minimal"` - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `summary?: "concise" | "detailed" | "auto" | null` The reasoning summary to request from the delegated Responses model, when supported. - `"concise"` - `"detailed"` - `"auto"` - `service_tier?: "auto" | "default" | "fast_tier_temp_pilot" | 3 more | null` Service tier for delegated Responses requests. - `"auto"` - `"default"` - `"fast_tier_temp_pilot"` - `"flex"` - `"priority"` - `"ultrafast"` - `text?: Text | null` Text generation settings passed to each delegated Responses request. - `verbosity?: "low" | "medium" | "high" | null` The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery. - `"low"` - `"medium"` - `"high"` - `tool_choice?: "auto" | "none" | "required" | LiveFunctionToolChoiceParam | LiveMCPToolChoiceParam` Controls which tool the Responses backend uses when handling a task delegated by the Live model. - `"auto" | "none" | "required"` - `"auto"` - `"none"` - `"required"` - `LiveFunctionToolChoiceParam` - `name: string` - `type: "function"` - `"function"` - `LiveMCPToolChoiceParam` - `name: string` - `server_label: string` - `type: "mcp"` - `"mcp"` - `tools?: Array` Tools available to the Responses backend while it handles tasks delegated by the Live model. - `FunctionTool` A function tool available to the Responses backend when the Live model delegates a task. - `name: string` The name the delegated Responses model uses when calling this function. - `type: "function"` The tool type. Always `function`. - `"function"` - `description?: string | null` What the function does and when the delegated Responses model should call it. - `parameters?: Record | null` A JSON Schema object describing the arguments accepted by the function. - `strict?: boolean | null` Whether the delegated Responses model must follow the function’s parameter schema exactly. - `WebSearch` A web search tool available to the Live session’s Responses backend. - `type: "web_search"` The tool type. Always `web_search`. - `"web_search"` - `store?: boolean` Whether to store the forked session. Omission inherits the stored session's setting. ### Returns - `SessionForkResponse` The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer's remote answer and wait for session.started on the data channel before sending commands. - `session: Session` The newly created Live session. Use its ID for session controls and sideband connections. - `id: string` Opaque session identifier. Preserve the returned value unchanged, including its prefix. - `transport: Transport` WebRTC transport with the SDP answer. - `sdp: string` Session Description Protocol message for the WebRTC connection. - `type: "webrtc"` The transport used for the Live session. Always `webrtc`. - `"webrtc"` ### Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted }); const response = await client.live.sessions.fork('session_id', { transport: { sdp: 'x', type: 'webrtc' }, }); console.log(response.session); ``` #### Response ```json { "session": { "id": "id" }, "transport": { "sdp": "x", "type": "webrtc" } } ``` ## Hang up session `client.live.sessions.hangup(stringsessionID, RequestOptionsoptions?): void` **post** `/live/sessions/{session_id}/hangup` End a SIP call identified by session_id. ### Parameters - `sessionID: string` ### Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted }); await client.live.sessions.hangup('session_id'); ``` ## Transfer call `client.live.sessions.refer(stringsessionID, SessionReferParamsbody, RequestOptionsoptions?): void` **post** `/live/sessions/{session_id}/refer` Transfer a SIP call to another destination. Supply a nonblank target_uri for the SIP Refer-To header. ### Parameters - `sessionID: string` - `body: SessionReferParams` - `target_uri: string` Nonblank URI for the SIP Refer-To header, such as tel:+14155550123 or sip:agent@example.com. ### Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted }); await client.live.sessions.refer('session_id', { target_uri: 'tel:+14155550123' }); ``` ## Reject call `client.live.sessions.reject(stringsessionID, SessionRejectParamsbody, RequestOptionsoptions?): void` **post** `/live/sessions/{session_id}/reject` Reject an incoming SIP call. Send a required SIP rejection status_code between 300 and 699. ### Parameters - `sessionID: string` - `body: SessionRejectParams` - `status_code: number` SIP rejection status sent to the caller. This field is required. ### Example ```typescript import OpenAI from 'openai'; const client = new OpenAI({ apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted }); await client.live.sessions.reject('session_id', { status_code: 486 }); ``` ## Domain Types ### Session Fork Response - `SessionForkResponse` The created Live session identifier and WebRTC answer. Apply transport.sdp as the peer's remote answer and wait for session.started on the data channel before sending commands. - `session: Session` The newly created Live session. Use its ID for session controls and sideband connections. - `id: string` Opaque session identifier. Preserve the returned value unchanged, including its prefix. - `transport: Transport` WebRTC transport with the SDP answer. - `sdp: string` Session Description Protocol message for the WebRTC connection. - `type: "webrtc"` The transport used for the Live session. Always `webrtc`. - `"webrtc"`