feat: widget conversation modes

Add WidgetConversationMode so a host can run the widget as voice-only,
text-only, or both. Text-only conversations connect with audio disabled and
start implicitly on the first message; voice-only drops the composer and keeps
the orb above the transcript. The demo switches modes at runtime.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: renal128

Examples/DemoApp/DemoApp/ContentView.swift

@@ -8,6 +8,7 @@ struct ContentView: View {
     private static let agentId = ""
 
     @StateObject private var chat = ChatWidgetController()
+    @State private var conversationMode: WidgetConversationMode = .voiceAndText
 
     private var hasAgentId: Bool {
         !Self.agentId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
@@ -50,6 +51,7 @@ struct ContentView: View {
             if hasAgentId {
                 ChatWidget(
                     authProvider: { .publicAgent(id: Self.agentId) },
+                    widgetConfig: ChatWidgetConfig(conversationMode: conversationMode),
                     controller: chat
                 )
             }
@@ -62,6 +64,13 @@ struct ContentView: View {
                 .font(.caption)
                 .foregroundStyle(.secondary)
 
+            Picker("Mode", selection: $conversationMode) {
+                Text("Voice + text").tag(WidgetConversationMode.voiceAndText)
+                Text("Voice only").tag(WidgetConversationMode.voiceOnly)
+                Text("Text only").tag(WidgetConversationMode.textOnly)
+            }
+            .pickerStyle(.segmented)
+
             HStack(spacing: 12) {
                 Button("Open chat") { chat.open() }
                 Button("Close chat") { chat.close() }

Sources/ElevenLabsWidget/Configuration/ChatWidgetConfig.swift

@@ -3,6 +3,8 @@ import Foundation
 
 /// Behavior and appearance of ``ChatWidget``.
 public struct ChatWidgetConfig: Equatable, Sendable {
+    /// Whether the user talks, types, or both.
+    public var conversationMode: WidgetConversationMode
     /// Dim the host UI behind the open drawer.
     public var showBackdrop: Bool
     /// Show the microphone mute button while a conversation is live.
@@ -11,11 +13,13 @@ public struct ChatWidgetConfig: Equatable, Sendable {
     public var theme: ChatWidgetTheme
 
     public init(
+        conversationMode: WidgetConversationMode = .voiceAndText,
         showBackdrop: Bool = true,
         enableMicMuteControl: Bool = true,
         strings: ChatWidgetStrings = .default,
         theme: ChatWidgetTheme = .default
     ) {
+        self.conversationMode = conversationMode
         self.showBackdrop = showBackdrop
         self.enableMicMuteControl = enableMicMuteControl
         self.strings = strings

Sources/ElevenLabsWidget/Configuration/WidgetConversationMode.swift

@@ -0,0 +1,25 @@
+#if canImport(UIKit)
+import Foundation
+
+/// Which ways the user can talk to the agent through ``ChatWidget``.
+public enum WidgetConversationMode: String, CaseIterable, Identifiable, Sendable {
+    /// Typed messages only; the conversation runs without audio.
+    case textOnly
+    /// A voice call with no composer.
+    case voiceOnly
+    /// A voice call the user can also type into.
+    case voiceAndText
+
+    public var id: String {
+        rawValue
+    }
+
+    public var supportsVoice: Bool {
+        self != .textOnly
+    }
+
+    public var supportsTextInput: Bool {
+        self != .voiceOnly
+    }
+}
+#endif

Sources/ElevenLabsWidget/ViewModels/ChatWidgetViewModel.swift

@@ -16,7 +16,9 @@ final class ChatWidgetViewModel: ObservableObject {
     @Published private(set) var isMicMuted = false
     @Published private(set) var isSending = false
 
-    let widgetConfig: ChatWidgetConfig
+    /// Mirrors the config the host passes to ``ChatWidget``, so changes take
+    /// effect without recreating the conversation.
+    @Published var widgetConfig: ChatWidgetConfig
     let client: ConversationClient
     let audioLevels = OrbAudioLevels()
 
@@ -79,7 +81,27 @@ final class ChatWidgetViewModel: ObservableObject {
     }
 
     var canToggleMicMute: Bool {
-        widgetConfig.enableMicMuteControl && conversationState.isConnected
+        widgetConfig.enableMicMuteControl && mode.supportsVoice && conversationState.isConnected
+    }
+
+    var canShowTextInput: Bool {
+        mode.supportsTextInput
+    }
+
+    var canStartVoiceConversation: Bool {
+        mode.supportsVoice && !hasActiveConversation
+    }
+
+    private var mode: WidgetConversationMode {
+        widgetConfig.conversationMode
+    }
+
+    /// Text-only widgets run the conversation without audio.
+    private var effectiveConversationConfig: ConversationConfig {
+        guard !mode.supportsVoice else { return conversationConfig }
+        var config = conversationConfig
+        config.conversationOverrides.textOnly = true
+        return config
     }
 
     var orbState: ChatOrbState {
@@ -133,7 +155,7 @@ final class ChatWidgetViewModel: ObservableObject {
         if let startTask { return try await startTask.value }
         guard !hasActiveConversation else { return }
         let task = Task {
-            _ = try await client.startConversation(auth: authProvider(), config: conversationConfig)
+            _ = try await client.startConversation(auth: authProvider(), config: effectiveConversationConfig)
         }
         startTask = task
         defer { startTask = nil }

Sources/ElevenLabsWidget/Views/ChatInputBar.swift

@@ -17,25 +17,34 @@ struct ChatInputBar: View {
 
     var body: some View {
         VStack(spacing: 10) {
-            TextField(strings.inputPlaceholder, text: $vm.input, axis: .vertical)
-                .textFieldStyle(.plain)
-                .lineLimit(1 ... 3)
-                .padding(.horizontal, 8)
-                .frame(minHeight: 36)
-                .focused(isInputFocused)
-                .onSubmit(vm.send)
+            if vm.canShowTextInput {
+                TextField(strings.inputPlaceholder, text: $vm.input, axis: .vertical)
+                    .textFieldStyle(.plain)
+                    .lineLimit(1 ... 3)
+                    .padding(.horizontal, 8)
+                    .frame(minHeight: 36)
+                    .focused(isInputFocused)
+                    .onSubmit(vm.send)
+            }
 
             HStack(spacing: 10) {
                 if vm.canToggleMicMute {
                     ChatMicButton(vm: vm, levels: vm.audioLevels, diameter: 38, theme: theme)
                 }
+                // Without a composer there is nothing to push the call controls
+                // away from, so they sit centered instead.
                 Spacer(minLength: 0)
                 if vm.hasActiveConversation {
                     endConversationButton
-                } else {
+                } else if vm.canStartVoiceConversation {
                     startConversationButton
                 }
-                sendButton
+                if vm.canShowTextInput {
+                    sendButton
+                }
+                if !vm.canShowTextInput {
+                    Spacer(minLength: 0)
+                }
             }
         }
         .padding(.horizontal, 14)
@@ -50,7 +59,7 @@ struct ChatInputBar: View {
                 .strokeBorder(theme.border, lineWidth: 1)
         )
         .contentShape(Rectangle())
-        .onTapGesture { isInputFocused.wrappedValue = true }
+        .onTapGesture { if vm.canShowTextInput { isInputFocused.wrappedValue = true } }
     }
 
     private var startConversationButton: some View {

Sources/ElevenLabsWidget/Views/ChatPopupView.swift

@@ -19,9 +19,14 @@ struct ChatPopupView: View {
             Divider()
             if vm.messages.isEmpty {
                 Spacer(minLength: 0)
-                ChatOrbView(levels: vm.audioLevels, state: vm.orbState, size: 128, theme: vm.widgetConfig.theme)
+                orb(size: 128)
                 Spacer(minLength: 0)
             } else {
+                // A voice-only drawer has no composer to anchor it, so the orb
+                // stays visible above the transcript.
+                if !vm.canShowTextInput {
+                    orb(size: 96).padding(.vertical, 12)
+                }
                 ChatTranscriptView(vm: vm)
             }
             ChatInputBar(vm: vm, isInputFocused: $isInputFocused)
@@ -39,9 +44,13 @@ struct ChatPopupView: View {
         .padding(.bottom, 8)
     }
 
+    private func orb(size: CGFloat) -> some View {
+        ChatOrbView(levels: vm.audioLevels, state: vm.orbState, size: size, theme: vm.widgetConfig.theme)
+    }
+
     private var header: some View {
         HStack(spacing: 12) {
-            ChatOrbView(levels: vm.audioLevels, state: vm.orbState, size: 36, theme: vm.widgetConfig.theme)
+            orb(size: 36)
             Text(strings.title)
                 .font(.headline)
             Spacer(minLength: 0)

Sources/ElevenLabsWidget/Views/ChatWidget.swift

@@ -14,6 +14,7 @@ import SwiftUI
 public struct ChatWidget: View {
     @StateObject private var vm: ChatWidgetViewModel
     private let controller: ChatWidgetController?
+    private let widgetConfig: ChatWidgetConfig
     private let launcher: (() -> AnyView)?
 
     /// - Parameters:
@@ -31,6 +32,7 @@ public struct ChatWidget: View {
         onClientToolCall: (@MainActor (ClientToolCallEvent) async -> ClientToolResultEvent)? = nil
     ) {
         self.controller = controller
+        self.widgetConfig = widgetConfig
         self.launcher = launcher
         // Built inside the autoclosure so SwiftUI only creates it once, rather
         // than on every re-init of this view.
@@ -69,6 +71,8 @@ public struct ChatWidget: View {
         // view update — otherwise the host's controller invalidates the view that
         // is still being built.
         .task { if let controller { vm.attach(to: controller) } }
+        // The view model outlives every re-init, so config changes are pushed to it.
+        .onChange(of: widgetConfig) { vm.widgetConfig = $0 }
     }
 
     @ViewBuilder