### SwiftUI Voice Chat Interface

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Implement a voice-enabled chat interface using SwiftUI and the `Conversation` class. This example demonstrates message display, text input, and real-time status indicators for user and model activity. Ensure you obtain an ephemeral key from your backend for connection.

```swift
import SwiftUI
import RealtimeAPI

struct VoiceChatView: View {
    @State private var conversation = try! Conversation()
    @State private var newMessage: String = ""

    var body: some View {
        VStack {
            // Display conversation messages
            ScrollView {
                ForEach(conversation.messages, id: \.id) {
                    message in
                    HStack {
                        if message.role == .user {
                            Spacer()
                            Text(message.content.first?.text ?? "")
                                .padding()
                                .background(Color.blue)
                                .foregroundColor(.white)
                                .cornerRadius(10)
                        } else {
                            Text(message.content.first?.text ?? "")
                                .padding()
                                .background(Color.gray.opacity(0.2))
                                .cornerRadius(10)
                            Spacer()
                        }
                    }
                }
            }

            // Text input
            HStack {
                TextField("Type a message", text: $newMessage)
                    .textFieldStyle(.roundedBorder)
                Button("Send") {
                    Task {
                        try await conversation.send(from: .user, text: newMessage)
                        newMessage = ""
                    }
                }
            }
            .padding()

            // Voice status indicators
            HStack {
                Circle()
                    .fill(conversation.isUserSpeaking ? .green : .gray)
                    .frame(width: 10, height: 10)
                Text(conversation.isUserSpeaking ? "Listening..." : "")

                Circle()
                    .fill(conversation.isModelSpeaking ? .blue : .gray)
                    .frame(width: 10, height: 10)
                Text(conversation.isModelSpeaking ? "Speaking..." : "")
            }
        }
        .task {
            // Connect with ephemeral key (obtain from your backend)
            try! await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")
        }
    }
}
```

--------------------------------

### Manually Sending Messages

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Provides examples for sending text and audio messages through the `Conversation` class, including options for customizing responses and handling audio data chunks.

```APIDOC
## Manually sending messages

To send a text message, call the `send(from: Item.ItemRole, text: String, response: Response.Config? = nil)` providing the role of the sender (`.user`, `.assistant`, or `.system`) and the contents of the message. You can optionally also provide a `Response.Config` object to customize the response, such as enabling or disabling function calls.

To manually send an audio message (or part of one), call the `send(audioDelta: Data, commit: Bool = false)` with a valid audio chunk. If `commit` is `true`, the model will consider the message finished and begin responding to it. Otherwise, it might wait for more audio depending on your `Session.turnDetection` settings.
```

--------------------------------

### RealtimeAPI Initialization and Event Handling

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Shows how to initialize the `RealtimeAPI` using different connectors (WebRTC, WebSocket) with API keys or URLs, and how to listen for and send events.

```APIDOC
### `RealtimeAPI`

To interact with the API directly, create a new instance of `RealtimeAPI` providing one of the available connectors. There are helper methods that let you create an instance from an apiKey or a `URLRequest`, like so:

```swift
let api = RealtimeAPI.webRTC(ephemeralKey: YOUR_EPHEMERAL_KEY, model: .gptRealtime) // or RealtimeAPI.webRTC(connectingTo: URLRequest)
let api = RealtimeAPI.webSocket(authToken: YOUR_OPENAI_API_KEY, model: .gptRealtime) // or RealtimeAPI.webSocket(connectingTo: URLRequest)
```

You can listen for new events through the `events` property, like so:

```swift
for try await event in api.events {
    switch event {
        case let .sessionCreated(event):
            print(event.session.id)
    }
}
```

To send an event to the API, call the `send` method with a `ClientEvent` instance:

```swift
try await api.send(event: .updateSession(session))
try await api.send(event: .appendInputAudioBuffer(encoding: audioData))
try await api.send(event: .createResponse())
```
```

--------------------------------

### Initialize RealtimeAPI in Swift

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Create instances of RealtimeAPI using either WebRTC or WebSocket connectors. Provide necessary authentication details like ephemeral keys or API tokens.

```swift
let api = RealtimeAPI.webRTC(ephemeralKey: YOUR_EPHEMERAL_KEY, model: .gptRealtime) // or RealtimeAPI.webRTC(connectingTo: URLRequest)
```

```swift
let api = RealtimeAPI.webSocket(authToken: YOUR_OPENAI_API_KEY, model: .gptRealtime) // or RealtimeAPI.webSocket(connectingTo: URLRequest)
```

--------------------------------

### Initialize RealtimeAPI with WebRTC or WebSocket

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Instantiate the RealtimeAPI using either WebRTC for recommended client-side usage or WebSocket for server-side applications. Ensure you provide the correct authentication (ephemeral key for WebRTC, API key for WebSocket) and specify the desired model.

```swift
import RealtimeAPI

// Create API instance with WebRTC (recommended)
let api = try await RealtimeAPI.webRTC(
    ephemeralKey: "YOUR_EPHEMERAL_KEY",
    model: .gptRealtime
)

// Or with WebSocket (for server-side usage)
// let api = try await RealtimeAPI.webSocket(
//     authToken: "YOUR_API_KEY",
//     model: .gptRealtime
// )
```

--------------------------------

### Configure Function Calling Tools in Swift

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Define available tools with their descriptions and parameters, and configure how the model should choose them. Use this to allow the model to call functions in your application.

```swift
import RealtimeAPI

let conversation = try! Conversation()
try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

try await conversation.whenConnected {
    try conversation.updateSession {
        // Define available tools
        session.tools = [
            .function(Tool.Function(
                name: "get_weather",
                description: "Get current weather for a location",
                parameters: JSONSchema(
                    type: .object,
                    properties: [
                        "location": JSONSchema(type: .string, description: "City name"),
                        "unit": JSONSchema(type: .string, enumValues: ["celsius", "fahrenheit"])
                    ],
                    required: ["location"]
                )
            )),
            .function(Tool.Function(
                name: "search_database",
                description: "Search the product database",
                parameters: JSONSchema(
                    type: .object,
                    properties: [
                        "query": JSONSchema(type: .string, description: "Search query"),
                        "limit": JSONSchema(type: .integer, description: "Max results")
                    ],
                    required: ["query"]
                )
            ))
        ]

        // Configure tool choice
        session.toolChoice = .auto // Let model decide
        // session.toolChoice = .required // Force tool use
        // session.toolChoice = .function(name: "get_weather") // Force specific tool
    }
}

// Handle function calls in your event loop
for entry in conversation.entries {
    if case .functionCall(let call) = entry {
        print("Function: \(call.name), Arguments: \(call.arguments)")

        // Process the function call
        let result = await processFunction(name: call.name, arguments: call.arguments)

        // Send the result back
        let output = Item.FunctionCallOutput(
            id: UUID().uuidString,
            callId: call.callId,
            output: result
        )
        try conversation.send(result: output)
    }
}
```

--------------------------------

### Configure Session Voice and Audio Settings in Swift

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Customize voice, speech speed, modalities, turn detection (server and semantic VAD), transcription, and noise reduction for Realtime API sessions. Ensure correct imports and asynchronous handling.

```swift
import RealtimeAPI

let conversation = try! Conversation()
try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

try await conversation.whenConnected {
    try conversation.updateSession {
        session in
        // Select voice (available: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar)
        session.audio.output.voice = .sage

        // Set speech speed (0.25 to 1.5, default 1.0)
        session.audio.output.speed = 1.1

        // Configure modalities
        session.modalities = [.text, .audio] // Enable both text and audio output

        // Server VAD configuration (volume-based detection)
        session.audio.input.turnDetection = Session.Audio.Input.TurnDetection(
            createResponse: true,
            interruptResponse: true,
            prefixPaddingMs: 300,      // Audio before speech
            silenceDurationMs: 500,     // Silence to end turn
            threshold: 0.5,             // Volume threshold (0.0-1.0)
            type: .server
        )

        // OR Semantic VAD (AI-powered turn detection)
        session.audio.input.turnDetection = Session.Audio.Input.TurnDetection(
            createResponse: true,
            eagerness: .high,           // low, medium, high, or auto
            idleTimeout: 30000,         // Timeout in ms
            interruptResponse: true,
            type: .semantic
        )

        // Transcription configuration
        session.audio.input.transcription = Session.Audio.Input.Transcription(
            model: .gpt4o,              // or .whisper, .gpt4oMini, .gpt4oDiarize
            language: "en",
            prompt: "Technical discussion about Swift programming"
        )

        // Noise reduction
        session.audio.input.noiseReduction = .nearField  // For headphones
        // session.audio.input.noiseReduction = .farField // For room mics
    }
}
```

--------------------------------

### Select OpenAI Realtime Models in Swift

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Connect to different OpenAI Realtime models using their predefined cases or custom identifiers. Ensure the correct model is specified during the connection phase.

```swift
import RealtimeAPI

// Use the standard GPT Realtime model (default)
let conversation1 = try! Conversation()
try await conversation1.connect(ephemeralKey: "KEY", model: .gptRealtime)

// Use the mini model (faster, lower cost)
let conversation2 = try! Conversation()
try await conversation2.connect(ephemeralKey: "KEY", model: .gptRealtimeMini)

// Use a custom/preview model
let conversation3 = try! Conversation()
try await conversation3.connect(ephemeralKey: "KEY", model: .custom("gpt-4o-realtime-preview-2024-10-01"))

// With RealtimeAPI directly
let api = try await RealtimeAPI.webRTC(
    ephemeralKey: "KEY",
    model: .gptRealtime
)

// Transcription model options
// .whisper - Original Whisper model
// .gpt4o - GPT-4o transcription (recommended)
// .gpt4oMini - Faster, lower cost
// .gpt4oDiarize - With speaker diarization
```

--------------------------------

### Customizing the Session

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Demonstrates how to update the current session's configuration, such as the system prompt or enabling audio transcription, using `updateSession` within a connected callback.

```APIDOC
## Customizing the Session

You can customize the current session using the `setSession(_: Session)` or `updateSession(withChanges: (inout Session) -> Void)` methods. Note that they requires that a session has already been established, so it's recommended you call them from a `whenConnected(_: @Sendable () async throws -> Void)` callback or await `waitForConnection()` first. For example:

```swift
try await conversation.whenConnected {
    try await conversation.updateSession {
        // update system prompt
        session.instructions = "You are a helpful assistant."

        // enable transcription of users' voice messages
        session.inputAudioTranscription = Session.InputAudioTranscription()

        // ...
    }
}
```
```

--------------------------------

### Build iMessage-like Chat App

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Create an iMessage-style chat interface with AI integration in under 60 lines of code. Requires connecting the conversation and sending messages.

```swift
import SwiftUI
import RealtimeAPI

struct ContentView: View {
	@State private var newMessage: String = ""
	@State private var conversation = try! Conversation()

	var messages: [Item.Message] {
		conversation.entries.compactMap { switch $0 {
			case let .message(message): return message
			default: return nil
		} }
	}

	var body: some View {
		VStack(spacing: 0) {
			ScrollView {
                VStack(spacing: 12) {
                    ForEach(messages, id: \.id) {
                        message in 
                        MessageBubble(message: message)
                    }
                }
                .padding()
			}

			HStack(spacing: 12) {
				HStack {
					TextField("Chat", text: $newMessage, onCommit: { sendMessage() })
						.frame(height: 40)
						.submitLabel(.send)

					if newMessage != "" {
						Button(action: sendMessage) {
							Image(systemName: "arrow.up.circle.fill")
								.resizable()
								.aspectRatio(contentMode: .fill)
								.frame(width: 28, height: 28)
								.foregroundStyle(.white, .blue)
						}
					}
				}
				.padding(.leading)
				.padding(.trailing, 6)
				.overlay(RoundedRectangle(cornerRadius: 20).stroke(.quaternary, lineWidth: 1))
			}
			.padding()
		}
		.navigationTitle("Chat")
		.navigationBarTitleDisplayMode(.inline)
		.task { try! await conversation..connect(ephemeralKey: YOUR_EPHEMERAL_KEY_HERE) }
	}

	func sendMessage() {
		guard newMessage != "" else { return }

		Task {
			try await conversation.send(from: .user, text: newMessage)
			newMessage = ""
		}
	}
}

```

--------------------------------

### Integrate with MCP Servers in Swift

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Connect to MCP servers to leverage remote tools and service connectors. Handles custom MCP servers and predefined service connectors like Google Calendar.

```swift
import RealtimeAPI

let conversation = try! Conversation()
try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

try await conversation.whenConnected {
    try conversation.updateSession {
        session.tools = [
            // Custom MCP server
            .mcp(Tool.MCP(
                label: "my-tools",
                url: URL(string: "https://mcp.example.com/tools")!,
                authorization: "Bearer oauth_token_here",
                allowedTools: ["search", "create_document"],
                headers: ["X-Custom-Header": "value"],
                requireApproval: .granular(always: ["delete"], never: ["search"]),
                description: "Custom tool server for document management"
            )),

            // Service connector (e.g., Google Calendar)
            .mcp(Tool.MCP(
                label: "calendar",
                connector: .googleCalendar,
                authorization: "google_oauth_token",
                allowedTools: nil, // Allow all tools
                requireApproval: .all(.never)
            ))
        ]

        // Force use of a specific MCP tool
        session.toolChoice = .mcp(server: "my-tools", tool: "search")
    }
}

// Handle MCP tool calls and approval requests
for entry in conversation.entries {
    switch entry {
    case .mcpToolCall(let toolCall):
        print("MCP Tool: \(toolCall.tool) on \(toolCall.server)")
        print("Arguments: \(toolCall.arguments)")
        if let output = toolCall.output {
            print("Output: \(output)")
        }
        if let error = toolCall.error {
            print("Error: \(error.message)")
        }

    case .mcpApprovalRequest(let request):
        print("Approval needed for \(request.tool) on \(request.server)")
        // Create approval response
        let approval = Item.MCPApprovalResponse(
            id: UUID().uuidString,
            approvalRequestId: request.id,
            approve: true,
            reason: "User approved"
        )
        try conversation.send(event: .createConversationItem(.mcpApprovalResponse(approval)))

    default:
        break
    }
}
```

--------------------------------

### Listen for RealtimeAPI Events

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Asynchronously listen for various events from the RealtimeAPI, such as session creation, text and audio deltas, response completion, and errors. Handle each event type appropriately within a Task.

```swift
Task {
    for try await event in api.events {
        switch event {
        case .sessionCreated(let eventId, let session):
            print("Session created: \(session.id ?? \"unknown\")")

        case .responseTextDelta(_, _, _, _, _, let delta):
            print("Text: \(delta)", terminator: "")

        case .responseAudioTranscriptDelta(_, _, _, _, _, let delta):
            print("Transcript: \(delta)", terminator: "")

        case .responseDone(_, let response):
            print("\nResponse complete. Status: \(response.status)")
            if let usage = response.usage {
                print("Tokens - Input: \(usage.inputTokens), Output: \(usage.outputTokens)")
            }

        case .error(_, let error):
            print("Error: \(error.message)")

        case .inputAudioBufferSpeechStarted(_, _, _):
            print("User started speaking")

        case .inputAudioBufferSpeechStopped(_, _, _):
            print("User stopped speaking")

        default:
            break
        }
    }
}
```

--------------------------------

### Connect Conversation to Realtime API

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Establish a connection to OpenAI's Realtime API using either an ephemeral key or a custom URLRequest. The ephemeral key method is recommended for security. The connection process automatically requests microphone permissions.

```swift
import RealtimeAPI

// Method 1: Connect with ephemeral key (recommended)
let conversation = try! Conversation()
try await conversation.connect(ephemeralKey: "ek_abc123...", model: .gptRealtime)

// Method 2: Connect with custom URLRequest
let conversation = try! Conversation()
var request = URLRequest(url: URL(string: "https://api.openai.com/v1/realtime")!)
request.setValue("Bearer \(ephemeralKey)", forHTTPHeaderField: "Authorization")
try await conversation.connect(using: request)

// Wait for connection to be established before configuring
await conversation.waitForConnection()
print("Connected! Session ID: \(conversation.id ?? \"unknown\")")

// Or use whenConnected callback
try await conversation.whenConnected {
    print("Connection established, status: \(conversation.status)")
}
```

--------------------------------

### Add Swift Package Dependency

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Integrate the SDK into your Xcode project using Swift Package Manager by adding the Git repository URL.

```swift
dependencies: [
    .package(url: "https://github.com/m1guelpf/swift-realtime-openai.git", .branch("main"))
]
```

--------------------------------

### Simple AI Chat App

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

A minimal SwiftUI view that establishes a connection to the AI for basic conversational interaction. It displays a placeholder text and connects to the conversation upon view appearance.

```swift
import SwiftUI
import RealtimeAPI

struct ContentView: View {
	@State private var conversation = try! Conversation()

	var body: some View {
		Text("Say something!")
			.task { try! await conversation..connect(ephemeralKey: YOUR_EPHEMERAL_KEY_HERE) }
	}
}

```

--------------------------------

### Configure Conversation Session in Swift

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Updates the current session configuration including system instructions, voice settings, transcription options, and turn detection behavior. This method must be called after the connection is established.

```swift
import RealtimeAPI

let conversation = try! Conversation(debug: true) // Enable debug logging

try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

try await conversation.whenConnected {
    try conversation.updateSession {
        // Set system instructions
        session.instructions = """
        You are a helpful voice assistant. Speak naturally and conversationally.
        Keep responses concise but informative. If you don't know something, say so.
        """

        // Configure input audio transcription
        session.audio.input.transcription = Session.Audio.Input.Transcription(
            model: .gpt4o,
            language: "en",
            prompt: "Expect technical terms related to programming"
        )

        // Configure turn detection (semantic VAD for natural conversation)
        session.audio.input.turnDetection = .semanticVad(
            createResponse: true,
            eagerness: .medium,
            interruptResponse: true
        )

        // Or use server VAD for faster response
        // session.audio.input.turnDetection = .serverVad(
        //     silenceDurationMs: 500,
        //     threshold: 0.5
        // )

        // Enable noise reduction for far-field microphones
        session.audio.input.noiseReduction = .farField

        // Set response token limits
        session.maxResponseOutputTokens = .limited(1024)

        // Set temperature for response variety
        session.temperature = 0.8
    }
}
```

--------------------------------

### Update Conversation Session in Swift

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Customize the current session's instructions or enable input audio transcription within a connected state. Ensure a session is established before calling.

```swift
try await conversation.whenConnected {
    try await conversation.updateSession {
        // update system prompt
        session.instructions = "You are a helpful assistant."

        // enable transcription of users' voice messages
        session.inputAudioTranscription = Session.InputAudioTranscription()

        // ...
    }
}
```

--------------------------------

### Send Events to RealtimeAPI in Swift

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Send various client events to the API, including session updates, audio buffer appends, and response creation requests. Prefer higher-level methods when possible.

```swift
try await api.send(event: .updateSession(session))
```

```swift
try await api.send(event: .appendInputAudioBuffer(encoding: audioData))
```

```swift
try await api.send(event: .createResponse())
```

--------------------------------

### Listen for RealtimeAPI Events in Swift

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Iterate over the `events` property of a RealtimeAPI instance to receive and process incoming API events, such as session creation notifications.

```swift
for try await event in api.events {
    switch event {
        case let .sessionCreated(event):
            print(event.session.id)
    }
}
```

--------------------------------

### Swift Conversation Control UI

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

This SwiftUI view demonstrates how to integrate the `Conversation` class to provide mute controls and display connection and speaking status indicators. It requires an ephemeral key for connection.

```swift
import SwiftUI
import RealtimeAPI

struct ConversationControlView: View {
    @State private var conversation = try! Conversation()

    var body: some View {
        VStack(spacing: 20) {
            // Connection status
            HStack {
                Circle()
                    .fill(statusColor)
                    .frame(width: 12, height: 12)
                Text(statusText)
            }

            // Speaking indicators
            HStack(spacing: 40) {
                VStack {
                    Image(systemName: "mic.fill")
                        .foregroundColor(conversation.isUserSpeaking ? .green : .gray)
                    Text("You")
                }
                VStack {
                    Image(systemName: "speaker.wave.2.fill")
                        .foregroundColor(conversation.isModelSpeaking ? .blue : .gray)
                    Text("AI")
                }
            }

            // Mute toggle
            Button(action: {
                conversation.muted.toggle()
            }) {
                Image(systemName: conversation.muted ? "mic.slash.fill" : "mic.fill")
                    .font(.largeTitle)
                    .foregroundColor(conversation.muted ? .red : .primary)
            }

            Text(conversation.muted ? "Muted" : "Tap to mute")
                .font(.caption)
        }
        .task {
            try? await conversation.connect(ephemeralKey: "YOUR_KEY")
        }
    }

    var statusColor: Color {
        switch conversation.status {
        case .connected: return .green
        case .connecting: return .yellow
        case .disconnected: return .red
        }
    }

    var statusText: String {
        switch conversation.status {
        case .connected: return "Connected"
        case .connecting: return "Connecting..."
        case .disconnected: return "Disconnected"
        }
    }
}
```

--------------------------------

### Send Direct ClientEvent to RealtimeAPI

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Send various client events directly to the RealtimeAPI to control the conversation flow, manage audio buffers, and interact with the session. This provides granular control over API interactions.

```swift
import RealtimeAPI

let api = try await RealtimeAPI.webRTC(ephemeralKey: "YOUR_EPHEMERAL_KEY")

// Update session configuration
var session = Session(/* ... */)
try await api.send(event: .updateSession(session))

// Append audio to input buffer
let audioData: Data = captureAudioFrame()
try await api.send(event: .appendInputAudioBuffer(encoding: audioData))

// Commit input audio buffer (triggers transcription)
try await api.send(event: .commitInputAudioBuffer())

// Clear input audio buffer
try await api.send(event: .clearInputAudioBuffer())

// Create a conversation item (text message)
let message = Item.Message(
    id: UUID().uuidString,
    role: .user,
    content: [.inputText("Hello, how are you?")]
)
try await api.send(event: .createConversationItem(.message(message)))

// Create a response (trigger model inference)
try await api.send(event: .createResponse())

// Cancel an in-progress response
try await api.send(event: .cancelResponse())

// Clear output audio buffer (WebRTC only)
try await api.send(event: .outputAudioBufferClear())

// Delete a conversation item
try await api.send(event: .deleteConversationItem(by: "item_id_here"))

// Truncate assistant audio (for interruptions)
try await api.send(event: .truncateConversationItem(
    forItem: "item_id",
    at: 0,
    atAudioMs: 5000
))
```

--------------------------------

### Manually Sending Events

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Explains how to send events directly to the API using `send(event: RealtimeAPI.ClientEvent)`, cautioning that this bypasses some of the `Conversation` class's built-in logic.

```APIDOC
## Manually sending events

To manually send an event to the API, use the `send(event: RealtimeAPI.ClientEvent)` method. Note that this bypasses some of the logic in the `Conversation` class such as handling interrupts, so you should prefer to use other methods whenever possible.
```

--------------------------------

### Handle Errors in Swift Realtime OpenAI SDK

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Implement robust error handling for connection, API, and runtime errors using the ConversationError enum, WebRTCError, and ServerError. Monitor errors via the conversation.errors stream.

```swift
import RealtimeAPI

let conversation = try! Conversation(debug: true)

// Monitor errors asynchronously
Task {
    for await error in conversation.errors {
        print("Server error: \(error.type) - \(error.message)")
        if let code = error.code {
            print("Error code: \(code)")
        }
    }
}

// Handle connection errors
do {
    try await conversation.connect(ephemeralKey: "YOUR_KEY")
} catch ConversationError.invalidEphemeralKey {
    print("The ephemeral key is invalid or expired")
} catch ConversationError.sessionNotFound {
    print("Session not established yet")
} catch let error as WebRTCConnector.WebRTCError {
    switch error {
    case .missingAudioPermission:
        print("Microphone permission not granted")
    case .failedToCreatePeerConnection:
        print("Could not create WebRTC connection")
    case .badServerResponse(let response):
        print("Bad response: \(response)")
    case .invalidEphemeralKey:
        print("Invalid ephemeral key")
    default:
        print("WebRTC error: \(error)")
    }
} catch {
    print("Unexpected error: \(error)")
}

// Handle send errors
do {
    try conversation.send(from: .user, text: "Hello")
} catch ConversationError.sessionNotFound {
    print("Not connected yet - wait for connection")
}
```

--------------------------------

### Conversation.updateSession - Configuring Session

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Updates the current session configuration including system instructions, voice settings, transcription options, and turn detection behavior. This method must be called after the connection is established.

```APIDOC
## Conversation.updateSession - Configuring Session

### Description
Updates the current session configuration including system instructions, voice settings, transcription options, and turn detection behavior. This method must be called after the connection is established, typically within a `whenConnected` callback or after `waitForConnection()`.

### Method
(Implicitly called within a Swift context, not a direct HTTP method)

### Endpoint
(N/A - This is a client-side SDK method)

### Parameters
(Configuration is done via a closure modifying a `Session` object)

#### Request Body
(N/A - Configuration is done programmatically)

### Request Example
```swift
import RealtimeAPI

let conversation = try! Conversation(debug: true) // Enable debug logging

try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

try await conversation.whenConnected {
    try conversation.updateSession {
        // Set system instructions
        session.instructions = """
        You are a helpful voice assistant. Speak naturally and conversationally.
        Keep responses concise but informative. If you don't know something, say so.
        """

        // Configure input audio transcription
        session.audio.input.transcription = Session.Audio.Input.Transcription(
            model: .gpt4o,
            language: "en",
            prompt: "Expect technical terms related to programming"
        )

        // Configure turn detection (semantic VAD for natural conversation)
        session.audio.input.turnDetection = .semanticVad(
            createResponse: true,
            eagerness: .medium,
            interruptResponse: true
        )

        // Or use server VAD for faster response
        // session.audio.input.turnDetection = .serverVad(
        //     silenceDurationMs: 500,
        //     threshold: 0.5
        // )

        // Enable noise reduction for far-field microphones
        session.audio.input.noiseReduction = .farField

        // Set response token limits
        session.maxResponseOutputTokens = .limited(1024)

        // Set temperature for response variety
        session.temperature = 0.8
    }
}
```

### Response
(N/A - This method modifies the session state and does not return a direct response in the typical API sense.)
```

--------------------------------

### Send Audio Message Delta in Swift

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Send a chunk of audio data for processing. Set `commit` to true to signal the end of the audio message and prompt a response.

```swift
try await conversation.send(audioDelta: audioData, commit: true)
```

--------------------------------

### Send Text and Audio Messages in Swift

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Sends text messages or audio data to the conversation. Text messages are immediately added to the conversation context and trigger a model response. Audio data can be streamed incrementally and optionally committed to trigger response generation.

```swift
import RealtimeAPI
import Foundation

let conversation = try! Conversation()
try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

// Send a text message from the user
try conversation.send(from: .user, text: "What's the weather like today?")

// Send a system message (for context injection)
try conversation.send(from: .system, text: "The user is located in San Francisco, CA")

// Send with custom response configuration
let responseConfig = Response.Config(
    modalities: [.text, .audio],
    instructions: "Respond briefly",
    voice: .alloy,
    outputAudioFormat: Session.AudioFormat(rate: 24000, type: "pcm16"),
    tools: [],
    toolChoice: .auto,
    temperature: 0.7,
    maxResponseOutputTokens: 500,
    conversation: .auto,
    metadata: nil,
    input: nil
)
try conversation.send(from: .user, text: "Tell me a joke", response: responseConfig)

// Send raw audio data (when not using automatic mic recording)
let audioData: Data = getAudioChunk() // Your audio capture logic
try conversation.send(audioDelta: audioData, commit: false) // Keep streaming

// Commit audio to trigger response (when server VAD is disabled)
try conversation.send(audioDelta: finalAudioChunk, commit: true)
```

--------------------------------

### Send Text Message in Swift

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Send a text message with a specified sender role and content. Optionally configure response behavior, such as enabling/disabling function calls.

```swift
try await conversation.send(from: .user, text: "Hello, how are you?")
```

--------------------------------

### Conversation.send - Sending Messages

Source: https://context7.com/m1guelpf/swift-realtime-openai/llms.txt

Sends text messages or audio data to the conversation. Text messages are immediately added to the conversation context and trigger a model response. Audio data can be streamed incrementally and optionally committed to trigger response generation.

```APIDOC
## Conversation.send - Sending Messages

### Description
Sends text messages or audio data to the conversation. Text messages are immediately added to the conversation context and trigger a model response. Audio data can be streamed incrementally and optionally committed to trigger response generation.

### Method
(Implicitly called within a Swift context, not a direct HTTP method)

### Endpoint
(N/A - This is a client-side SDK method)

### Parameters

#### Path Parameters
(N/A)

#### Query Parameters
(N/A)

#### Request Body
(N/A - Data is sent via method parameters)

### Request Example
```swift
import RealtimeAPI
import Foundation

let conversation = try! Conversation()
try await conversation.connect(ephemeralKey: "YOUR_EPHEMERAL_KEY")

// Send a text message from the user
try conversation.send(from: .user, text: "What's the weather like today?")

// Send a system message (for context injection)
try conversation.send(from: .system, text: "The user is located in San Francisco, CA")

// Send with custom response configuration
let responseConfig = Response.Config(
    modalities: [.text, .audio],
    instructions: "Respond briefly",
    voice: .alloy,
    outputAudioFormat: Session.AudioFormat(rate: 24000, type: "pcm16"),
    tools: [],
    toolChoice: .auto,
    temperature: 0.7,
    maxResponseOutputTokens: 500,
    conversation: .auto,
    metadata: nil,
    input: nil
)
try conversation.send(from: .user, text: "Tell me a joke", response: responseConfig)

// Send raw audio data (when not using automatic mic recording)
let audioData: Data = getAudioChunk() // Your audio capture logic
try conversation.send(audioDelta: audioData, commit: false) // Keep streaming

// Commit audio to trigger response (when server VAD is disabled)
try conversation.send(audioDelta: finalAudioChunk, commit: true)
```

### Response
(N/A - Responses are typically received asynchronously via callbacks or event handlers.)
```

--------------------------------

### Display Conversation Messages

Source: https://github.com/m1guelpf/swift-realtime-openai/blob/main/README.md

Renders messages from the conversation in a ScrollView, updating the view as new messages arrive. It automatically scrolls to the latest message.

```swift
ScrollView {
    ScrollViewReader { scrollView in
        VStack(spacing: 12) {
            ForEach(conversation.messages, id: \.id) {
                message in 
                MessageBubble(message: message).id(message.id)
            }
        }
        .onReceive(conversation.messages.publisher) { _ in
            withAnimation { scrollView.scrollTo(conversation.messages.last?.id, anchor: .center) }
        }
    }
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.