# Sessions

## Accept call

`live().sessions().accept(SessionAcceptParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**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

- `SessionAcceptParams params`

  - `Optional<String> sessionId`

  - `Session session`

    Model and startup configuration for the Live session that answers the incoming SIP call.

    - `Model model`

      The Live model to use for the accepted call.

      - `GPT_LIVE_1("gpt-live-1")`

    - `JsonValue; type "live"constant`

      The session type. Always `live`.

      - `LIVE("live")`

    - `Optional<Audio> audio`

      Startup audio output configuration. SIP negotiates the media format; audio.format is only accepted for primary WebSockets. Voice cannot change after startup.

      - `Optional<Output> output`

        Settings for speech generated by the Live model. Choose the voice before starting the session.

        - `Optional<Voice> voice`

          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`

          - `enum BuiltInVoice:`

            A built-in voice available for Live speech.

            - `ALLOY("alloy")`

            - `ASH("ash")`

            - `BALLAD("ballad")`

            - `BEACON("beacon")`

            - `BOSSA("bossa")`

            - `CEDAR("cedar")`

            - `CINDER("cinder")`

            - `CORAL("coral")`

            - `DELTA("delta")`

            - `ECHO("echo")`

            - `GLEAM("gleam")`

            - `MARIN("marin")`

            - `MERIDIAN("meridian")`

            - `QUARTZ("quartz")`

            - `RIPPLE("ripple")`

            - `SAGE("sage")`

            - `SHIMMER("shimmer")`

            - `STONE("stone")`

            - `TEMPO("tempo")`

            - `VERSE("verse")`

            - `VESPER("vesper")`

            - `WILLOW("willow")`

          - `class CustomVoice:`

            - `String id`

    - `Optional<Delegation> delegation`

      Who handles tasks delegated by the Live model. Omitted or null selects your application; use `responses` to let the API manage a Responses backend.

      - `class ClientDelegation:`

        Delegate tasks to your application. The Live session emits delegation events that your backend handles.

        - `JsonValue; type "client"constant`

          The delegation owner. Always `client` for tasks handled by your application.

          - `CLIENT("client")`

      - `class Responses:`

        Delegate tasks to a Responses model managed by the Live session.

        - `ResponsesDelegationConfig responses`

          Backend model, prompt, and tools used when the Live session delegates a task to Responses.

          - `String model`

            The model used for server-owned Responses delegations.

          - `Optional<String> instructions`

            Instructions for the delegated Responses model, separate from Live instructions. See [backend prompting](/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt).

          - `Optional<Long> maxOutputTokens`

            Maximum number of output tokens for each delegated response.

          - `Optional<Boolean> parallelToolCalls`

            Whether the delegated Responses model may request multiple tool calls in a single response.

          - `Optional<Reasoning> reasoning`

            Reasoning settings passed to each delegated Responses request.

            - `Optional<Effort> effort`

              How much reasoning effort the delegated Responses model should use. Supported values depend on the backend model.

              - `NONE("none")`

              - `MINIMAL("minimal")`

              - `LOW("low")`

              - `MEDIUM("medium")`

              - `HIGH("high")`

              - `XHIGH("xhigh")`

            - `Optional<Summary> summary`

              The reasoning summary to request from the delegated Responses model, when supported.

              - `CONCISE("concise")`

              - `DETAILED("detailed")`

              - `AUTO("auto")`

          - `Optional<ServiceTier> serviceTier`

            Service tier for delegated Responses requests.

            - `AUTO("auto")`

            - `DEFAULT("default")`

            - `FAST_TIER_TEMP_PILOT("fast_tier_temp_pilot")`

            - `FLEX("flex")`

            - `PRIORITY("priority")`

            - `ULTRAFAST("ultrafast")`

          - `Optional<Text> text`

            Text generation settings passed to each delegated Responses request.

            - `Optional<Verbosity> verbosity`

              The amount of detail in text generated by the Responses backend. This does not configure the Live model’s spoken delivery.

              - `LOW("low")`

              - `MEDIUM("medium")`

              - `HIGH("high")`

          - `Optional<ToolChoice> toolChoice`

            Controls which tool the Responses backend uses when handling a task delegated by the Live model.

            - `enum LiveToolChoiceEnum:`

              - `AUTO("auto")`

              - `NONE("none")`

              - `REQUIRED("required")`

            - `class LiveFunctionToolChoiceParam:`

              - `String name`

              - `JsonValue; type "function"constant`

                - `FUNCTION("function")`

            - `class LiveMcpToolChoiceParam:`

              - `String name`

              - `String serverLabel`

              - `JsonValue; type "mcp"constant`

                - `MCP("mcp")`

          - `Optional<List<Tool>> tools`

            Tools available to the Responses backend while it handles tasks delegated by the Live model.

            - `class FunctionTool:`

              A function tool available to the Responses backend when the Live model delegates a task.

              - `String name`

                The name the delegated Responses model uses when calling this function.

              - `JsonValue; type "function"constant`

                The tool type. Always `function`.

                - `FUNCTION("function")`

              - `Optional<String> description`

                What the function does and when the delegated Responses model should call it.

              - `Optional<Parameters> parameters`

                A JSON Schema object describing the arguments accepted by the function.

              - `Optional<Boolean> strict`

                Whether the delegated Responses model must follow the function’s parameter schema exactly.

            - `JsonValue;`

              - `JsonValue; type "web_search"constant`

                The tool type. Always `web_search`.

                - `WEB_SEARCH("web_search")`

        - `JsonValue; type "responses"constant`

          The delegation owner. Always `responses` for tasks handled by the Responses API.

          - `RESPONSES("responses")`

    - `Optional<List<InitialItem>> input`

      Ordered text-only history supplied before startup. Supports developer, user, and assistant messages with one text part each; at most 128 messages and 8,192 rendered tokens in total.

      - `Developer`

        - `List<Content> content`

          The message content. Supply exactly one text part for the initial Live conversation history.

          - `String text`

            The message text to include in the Live session’s initial conversation history.

          - `Optional<Type> type`

            The text content type. Always `input_text`.

            - `INPUT_TEXT("input_text")`

        - `JsonValue; role "developer"constant`

          The author of this history message. Always `developer`.

          - `DEVELOPER("developer")`

        - `Optional<String> id`

          An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.

        - `Optional<Status> status`

          The supplied message’s status. Live uses its text as history and does not resume an incomplete message.

          - `INCOMPLETE("incomplete")`

          - `COMPLETED("completed")`

        - `Optional<Type> type`

          The history item type. Always `message`.

          - `MESSAGE("message")`

      - `User`

        - `List<Content> content`

          The message content. Supply exactly one text part for the initial Live conversation history.

          - `String text`

            The message text to include in the Live session’s initial conversation history.

          - `Optional<Type> type`

            The text content type. Always `input_text`.

            - `INPUT_TEXT("input_text")`

        - `JsonValue; role "user"constant`

          The author of this history message. Always `user`.

          - `USER("user")`

        - `Optional<String> id`

          An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.

        - `Optional<Status> status`

          The supplied message’s status. Live uses its text as history and does not resume an incomplete message.

          - `INCOMPLETE("incomplete")`

          - `COMPLETED("completed")`

        - `Optional<Type> type`

          The history item type. Always `message`.

          - `MESSAGE("message")`

      - `Assistant`

        - `List<Content> content`

          The message content. Supply exactly one text part for the initial Live conversation history.

          - `class Text:`

            Assistant text supplied as conversation history when starting a Live session.

            - `String text`

              The message text to include in the Live session’s initial conversation history.

            - `Optional<Type> type`

              The text content type. Always `text`.

              - `TEXT("text")`

          - `class OutputText:`

            Assistant output text supplied as conversation history when starting a Live session.

            - `String text`

              The message text to include in the Live session’s initial conversation history.

            - `JsonValue; type "output_text"constant`

              The text content type. Always `output_text`.

              - `OUTPUT_TEXT("output_text")`

        - `JsonValue; role "assistant"constant`

          The author of this history message. Always `assistant`.

          - `ASSISTANT("assistant")`

        - `Optional<String> id`

          An optional identifier for the supplied history message. Live uses the message’s role and text to initialize the conversation.

        - `Optional<Status> status`

          The supplied message’s status. Live uses its text as history and does not resume an incomplete message.

          - `INCOMPLETE("incomplete")`

          - `COMPLETED("completed")`

        - `Optional<Type> type`

          The history item type. Always `message`.

          - `MESSAGE("message")`

    - `Optional<String> instructions`

      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.

    - `Optional<Boolean> store`

      Whether to store the session for later forking and recording download. Defaults to false for new sessions.

### Example

```java
package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.live.sessions.SessionAcceptParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionAcceptParams params = SessionAcceptParams.builder()
            .sessionId("session_id")
            .session(SessionAcceptParams.Session.builder()
                .model(SessionAcceptParams.Session.Model.GPT_LIVE_1)
                .build())
            .build();
        client.live().sessions().accept(params);
    }
}
```

## Download recording

`HttpResponse live().sessions().downloadRecording(SessionDownloadRecordingParamsparams = SessionDownloadRecordingParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**get** `/live/sessions/{session_id}/content`

Get Live session content

### Parameters

- `SessionDownloadRecordingParams params`

  - `Optional<String> sessionId`

    The ID of the stored Live session to download. Use the session ID returned when the session started with storage enabled.

### Example

```java
package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponse;
import com.openai.models.live.sessions.SessionDownloadRecordingParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        HttpResponse response = client.live().sessions().downloadRecording("live_SQ");
    }
}
```

## Fork session

`SessionForkResponse live().sessions().fork(SessionForkParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/live/sessions/{session_id}/fork`

Fork a stored Live session onto a new WebRTC connection.

### Parameters

- `SessionForkParams params`

  - `Optional<String> sessionId`

  - `Transport transport`

    WebRTC transport with an SDP offer for the new connection to the forked session.

    - `String sdp`

      Session Description Protocol message for the WebRTC connection.

    - `JsonValue; type "webrtc"constant`

      The transport used for the Live session. Always `webrtc`.

      - `WEBRTC("webrtc")`

  - `Optional<MediaSessionForkConfig> session`

    Optional configuration overrides for the new Live session. Omit this object or send an empty object to inherit the stored session's settings.

### Returns

- `class 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.

    - `String id`

      Opaque session identifier. Preserve the returned value unchanged, including its prefix.

  - `Transport transport`

    WebRTC transport with the SDP answer.

    - `String sdp`

      Session Description Protocol message for the WebRTC connection.

    - `JsonValue; type "webrtc"constant`

      The transport used for the Live session. Always `webrtc`.

      - `WEBRTC("webrtc")`

### Example

```java
package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.live.sessions.SessionForkParams;
import com.openai.models.live.sessions.SessionForkResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionForkParams params = SessionForkParams.builder()
            .sessionId("session_id")
            .transport(SessionForkParams.Transport.builder()
                .sdp("x")
                .build())
            .build();
        SessionForkResponse response = client.live().sessions().fork(params);
    }
}
```

#### Response

```json
{
  "session": {
    "id": "id"
  },
  "transport": {
    "sdp": "x",
    "type": "webrtc"
  }
}
```

## Hang up session

`live().sessions().hangup(SessionHangupParamsparams = SessionHangupParams.none(), RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/live/sessions/{session_id}/hangup`

End a SIP call identified by session_id.

### Parameters

- `SessionHangupParams params`

  - `Optional<String> sessionId`

### Example

```java
package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.live.sessions.SessionHangupParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        client.live().sessions().hangup("session_id");
    }
}
```

## Transfer call

`live().sessions().refer(SessionReferParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**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

- `SessionReferParams params`

  - `Optional<String> sessionId`

  - `String targetUri`

    Nonblank URI for the SIP Refer-To header, such as tel:+14155550123 or sip:agent@example.com.

### Example

```java
package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.live.sessions.SessionReferParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionReferParams params = SessionReferParams.builder()
            .sessionId("session_id")
            .targetUri("tel:+14155550123")
            .build();
        client.live().sessions().refer(params);
    }
}
```

## Reject call

`live().sessions().reject(SessionRejectParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

**post** `/live/sessions/{session_id}/reject`

Reject an incoming SIP call. Send a required SIP rejection status_code between 300 and 699.

### Parameters

- `SessionRejectParams params`

  - `Optional<String> sessionId`

  - `long statusCode`

    SIP rejection status sent to the caller. This field is required.

### Example

```java
package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.live.sessions.SessionRejectParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        SessionRejectParams params = SessionRejectParams.builder()
            .sessionId("session_id")
            .statusCode(486L)
            .build();
        client.live().sessions().reject(params);
    }
}
```