# `ReqLLM.OpenAI.Realtime`
[🔗](https://github.com/agentjido/req_llm/blob/main/lib/req_llm/openai/realtime.ex#L1)

Experimental low-level Realtime WebSocket client for OpenAI.

This module exposes a small session-oriented API for Realtime workflows that
do not map cleanly onto `ReqLLM.stream_text/3`. It is intentionally low-level:
you connect a session, send JSON events, receive JSON events, and close the
socket when you are done.

`next_event/2` remains the raw provider-event API. Use
`next_projected_event/3` or `project_event/2` for an additive view that keeps
the sanitized native event alongside any exact `ReqLLM.StreamEvent` overlap.
Session, transport, audio, MCP, rate-limit, and other provider-native events
are not forced into portable event types.

# `close`

```elixir
@spec close(ReqLLM.OpenAI.Realtime.Session.t()) :: :ok
```

# `connect`

```elixir
@spec connect(ReqLLM.model_input() | String.t(), keyword()) ::
  {:ok, ReqLLM.OpenAI.Realtime.Session.t()} | {:error, term()}
```

# `next_event`

```elixir
@spec next_event(ReqLLM.OpenAI.Realtime.Session.t(), timeout()) ::
  {:ok, map()} | :halt | {:error, term()}
```

# `next_projected_event`

```elixir
@spec next_projected_event(ReqLLM.OpenAI.Realtime.Session.t()) ::
  {:ok, ReqLLM.OpenAI.Realtime.Event.t()} | :halt | {:error, term()}
```

Receives one raw event and returns its provider-native and exact portable views.

Sensitive text, audio transcript, tool, and error payloads are redacted by
default. Pass `payloads: :raw` only when the consumer is authorized to retain
model and tool content. This function does not loop, reconnect, execute tools,
or continue a response.

# `next_projected_event`

```elixir
@spec next_projected_event(ReqLLM.OpenAI.Realtime.Session.t(), timeout() | keyword()) ::
  {:ok, ReqLLM.OpenAI.Realtime.Event.t()} | :halt | {:error, term()}
```

# `next_projected_event`

```elixir
@spec next_projected_event(
  ReqLLM.OpenAI.Realtime.Session.t(),
  non_neg_integer(),
  keyword()
) ::
  {:ok, ReqLLM.OpenAI.Realtime.Event.t()} | :halt | {:error, term()}
```

# `project_event`

```elixir
@spec project_event(map(), keyword()) :: ReqLLM.OpenAI.Realtime.Event.t()
```

Projects one already-decoded OpenAI Realtime server event.

The returned `ReqLLM.OpenAI.Realtime.Event` always retains a native view.
`stream_events` is empty when no exact provider-neutral meaning exists.
Supplying the resolved `:model` allows `response.created` to project to the
canonical `:start` event.

# `response_create`

```elixir
@spec response_create(ReqLLM.OpenAI.Realtime.Session.t(), map()) ::
  :ok | {:error, term()}
```

# `send_event`

```elixir
@spec send_event(ReqLLM.OpenAI.Realtime.Session.t(), map()) :: :ok | {:error, term()}
```

# `session_update`

```elixir
@spec session_update(ReqLLM.OpenAI.Realtime.Session.t(), map()) ::
  :ok | {:error, term()}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*