Elevenlabs Swift Sdk 4.0.0-alpha.1

v4 is a redesign of the SDK's public API. Instead of one-shot Conversation objects created by static functions, there is now a single small entry point - ConversationClient - that you create once, observe from SwiftUI, and reuse for as many conversations as you like. On top of it sits a brand-new drop-in chat widget, so you can ship an agent UI without building one.

Alpha. Pin the exact version - SwiftPM's from: ranges do not resolve prerelease tags.

.package(url: "https://github.com/elevenlabs/elevenlabs-swift-sdk.git", exact: "4.0.0-alpha.1")

Highlights

• One client, many conversations. In v3 every conversation was a new object, so screens had to re-wire their observers on every call. ConversationClient keeps stable @Published state (state, chatHistory, agentState, mute flags) across sessions - bind your UI once and just call start again.
• A drop-in UI. The new ElevenLabsWidget library ships ChatWidget (iOS 16+): a floating launcher that opens a chat drawer with voice calls, text input, a live transcript, and an audio-reactive orb. Theming, strings, and a host-side ChatWidgetController included; Examples/DemoApp shows every mode. One line to add.
• Credentials you can't mix up. Voice and text-only conversations authenticate differently, and the API now says so: startVoiceConversation takes a ConversationAuth.Voice (public agent ID or conversation token), startTextOnlyConversation takes a ConversationAuth.TextOnly (public agent ID or signed WebSocket URL). The textOnly config flag is gone - wrong combinations no longer compile.
• More robust transcript. chatHistory replaces messages. Streamed agent replies are keyed by the server's response ID and update in place instead of duplicating, each message carries an isFinal flag, and tool calls now appear in the timeline alongside messages.
• Startup you can see - and cancel. While connecting, state reports the exact stage (fetching a token, joining the room, waiting for the agent). Starting returns a ConversationStartResult with the conversation info and timing metrics. Cancelling the enclosing Task (or calling endConversation()) aborts startup cleanly at any stage, and the latest start always wins.
• More control over audio. Silence the agent's voice without ending the call (setAgentMuted), and tap the raw PCM of the agent or the local microphone with ConversationAudioObserver for visualizers, recording, or analysis. Both mute flags and observers persist across sessions.
• Swift 6 ready. The package builds with strict concurrency checking, ships Swift 6.0 and 6.2 manifests, and the public surface is Sendable-audited.

Breaking changes

Migrating from v3? The SDK ships an agent skill for the v3 v4 migration with before/after code for every change below, and the README covers the new API. In short:

• ElevenLabs.startConversation(...) and the ElevenLabs namespace are removed create a ConversationClient and call startVoiceConversation / startTextOnlyConversation.
• Global ElevenLabs.configure(...) is removed log level is set per client, everything else per session via ConversationConfig.
• Event callbacks moved from ConversationConfig to a ConversationCallbacks struct passed to ConversationClient(callbacks:). onDisconnect now receives an EndReason (userEnded, agentEnded, remoteDisconnected); the agent's end_call is reported as agentEnded.
• messages: [Message] chatHistory: [any ChatHistoryItem] (use .compactMap(\.message) for plain messages).
• ConversationState.active .connected; .connecting now carries the startup stage. The separate startupState / startupMetrics properties are gone - metrics are returned by the start call instead.
• Mic mute API: isMuted / toggleMute() / setMuted(_:) isMicMuted / setMicMuted(_:). The muted state now persists across conversations on the same client.
• sendToolResult(for:result:isError:) sendToolResult(_ result: ClientToolResultEvent).
• LiveKit types are no longer re-exported and the raw audio tracks (inputTrack, agentAudioTrack) are no longer exposed use ConversationAudioObserver.
• Removed: audioDevices / selectedAudioDeviceID, latestAudioEvent / latestAudioAlignment (use the onAudioAlignment callback), and the feedback-availability callback.
• Signed WebSocket URLs no longer need to embed an agent_id.

What's Changed

feat(events): client_error parsing, expects_response, type-safe tool results by @renal128 in #191 fix(networking): URL hardening and quieter unknown events by @renal128 in #192 optimization(audio): drop realtime-thread allocation in SoftwareMuteProcessor by @renal128 in #193 refactor(startup): Simplify WebRTC conversation startup by @renal128 in #195 refactor: Simplify Dependencies by @renal128 in #183 Gate startup readiness on agent join, not audio-track subscription by @renal128 in #197 chore: remove deprecated items (breaking) by @renal128 in #198 chore: event cleanup (breaking) by @renal128 in #199 Rename ElevenLabsConfiguration -> ConversationCredentials (breaking) by @renal128 in #201 Move callbacks out of ConversationConfig into ConversationCallbacks (breaking) by @renal128 in #202 Merge ConversationOptions into ConversationConfig (breaking) by @renal128 in #203 test: remove _testing_* backdoors from Conversation by @renal128 in #204 fix: resume agent-ready waiter on timeout by @renal128 in #207 refactor: clean up microphone mute API by @renal128 in #208 refactor: rename conversation active state to connected by @renal128 in #209 refactor: remove misleading local network permission detection by @renal128 in #214 refactor: simplify WebRTC configuration by @renal128 in #212 refactor: nest startup progress under ConversationState by @renal128 in #210 feat: wait for conversation initiation metadata (duplicate of #213) by @renal128 in <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="5062417831" data-permission-text="Title is private" data-url="https://github.com/elevenlabs/elevenlabs-swift-sdk/issues/228" data-hovercard-type="pull_request" data-hovercard-url="/elevenlabs/elevenlabs-swift-sdk/pull/228/hovercard" href="https://github.com/ele