refactor: make conversation endpoints configurable per session

Add Endpoints on ConversationConfig and wire them through TokenService and the connection managers. Drop ConnectionConstants and the global apiEndpoint/websocketUrl overrides.

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

Author: renal128

README.md

@@ -232,6 +232,18 @@ ElevenLabs.configure(
 )
 ```
 
+### Custom Endpoints
+
+Override any of the three endpoints for a proxy, regional host, or staging:
+
+```swift
+let config = ConversationConfig(
+    endpoints: Endpoints(
+        conversationToken: URL(string: "https://my-proxy.example.com/v1/convai/conversation/token")!
+    )
+)
+```
+
 ### Fine-Grained Callbacks
 
 Want to handle events without Combine? Use `ConversationCallbacks`:

Sources/ElevenLabs/Internal/Authorization/ConnectionConstants.swift

@@ -2,9 +2,10 @@ import Foundation
 
 protocol TokenServicing: Sendable {
     /// Fetch connection details for ElevenLabs conversation
-    /// - Parameter configuration: The configuration to use for fetching connection details
-    /// - Returns: The connection details for the ElevenLabs conversation
-    func fetchConnectionDetails(configuration: ConversationCredentials) async throws -> TokenService.ConnectionDetails
+    /// - Parameter credentials: The credentials to authenticate with
+    func fetchConnectionDetails(
+        credentials: ConversationCredentials
+    ) async throws -> TokenService.ConnectionDetails
 }
 
 extension TokenService: TokenServicing {}

Sources/ElevenLabs/Internal/Authorization/TokenServicing.swift

@@ -14,15 +14,14 @@ final class Dependencies: ConversationDependencyProvider {
     let webRTCConnectionManager: any WebRTCConnectionManaging
     let webSocketConnectionManager: any WebSocketConnectionManaging
 
-    init() {
+    init(endpoints: Endpoints = .production) {
         let globalConfig = ElevenLabs.Global.shared.configuration
-        let tokenService = TokenService(configuration: TokenService.Configuration(
-            apiEndpoint: globalConfig.apiEndpoint?.absoluteString,
-            websocketURL: globalConfig.websocketUrl
-        ))
         let logger = SDKLogger(logLevel: globalConfig.logLevel)
         self.logger = logger
-        webRTCConnectionManager = WebRTCConnectionManager(logger: logger, tokenService: tokenService)
-        webSocketConnectionManager = WebSocketConnectionManager(logger: logger)
+        webRTCConnectionManager = WebRTCConnectionManager(
+            logger: logger,
+            tokenService: TokenService(endpoints: endpoints)
+        )
+        webSocketConnectionManager = WebSocketConnectionManager(logger: logger, endpoints: endpoints)
     }
 }

Sources/ElevenLabs/Internal/DI/Dependencies.swift

@@ -97,7 +97,7 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
         let connectionDetails = try await runPhase(
             timing: \.tokenFetch, metrics: &metrics, startTime: startTime
         ) {
-            try await tokenService.fetchConnectionDetails(configuration: auth)
+            try await tokenService.fetchConnectionDetails(credentials: auth)
         }
 
         // 2. Request microphone permission (denial doesn't block startup).

Sources/ElevenLabs/Internal/Networking/WebRTCConnectionManager.swift

@@ -17,12 +17,14 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
 
     private let urlSession: URLSession
     private let logger: any Logging
+    private let endpoints: Endpoints
     private var task: URLSessionWebSocketTask?
     private var receiveTask: Task<Void, Never>?
     private var initiationMetadataWaiter: ConversationInitiationMetadataWaiter?
 
-    init(logger: any Logging) {
+    init(logger: any Logging, endpoints: Endpoints = .production) {
         self.logger = logger
+        self.endpoints = endpoints
         urlSession = URLSession(configuration: .default)
     }
 
@@ -46,7 +48,7 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
 
         let url: URL
         do {
-            url = try Self.url(for: auth)
+            url = try Self.url(for: auth, endpoints: endpoints)
         } catch {
             metrics.total = Date().timeIntervalSince(startTime)
             let convError = error as? ConversationError ?? .authenticationFailed(error.localizedDescription)
@@ -147,10 +149,10 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
         }
     }
 
-    static func url(for auth: ConversationCredentials) throws -> URL {
+    static func url(for auth: ConversationCredentials, endpoints: Endpoints) throws -> URL {
         switch auth.authSource {
         case let .publicAgentId(agentId):
-            var components = URLComponents(string: ConnectionConstants.textConversationUrl)
+            var components = URLComponents(url: endpoints.textWebSocket, resolvingAgainstBaseURL: false)
             components?.queryItems = [URLQueryItem(name: "agent_id", value: agentId)]
             guard let url = components?.url else {
                 throw ConversationError.authenticationFailed("Invalid conversation URL")

Sources/ElevenLabs/Internal/Networking/WebSocketConnectionManager.swift

@@ -24,22 +24,7 @@ public struct TokenService: Sendable {
         public let participantToken: String
     }
 
-    /// Optional configuration for advanced use cases
-    public struct Configuration: Sendable {
-        /// Custom API endpoint (for testing or enterprise deployments)
-        public let apiEndpoint: String?
-        /// Custom WebSocket URL (for testing or enterprise deployments)
-        public let websocketURL: String?
-
-        public init(apiEndpoint: String? = nil, websocketURL: String? = nil) {
-            self.apiEndpoint = apiEndpoint
-            self.websocketURL = websocketURL
-        }
-
-        public static let `default` = Configuration()
-    }
-
-    private let configuration: Configuration
+    private let endpoints: Endpoints
     private let urlSession: URLSession
 
     // Development-only API key for testing private agents
@@ -48,20 +33,20 @@ public struct TokenService: Sendable {
     public let debugApiKey: String?
 
     public init(
-        configuration: Configuration = .default,
+        endpoints: Endpoints = .production,
         urlSession: URLSession = .shared,
         debugApiKey: String? = nil
     ) {
-        self.configuration = configuration
+        self.endpoints = endpoints
         self.urlSession = urlSession
         self.debugApiKey = debugApiKey
     }
     #else
     public init(
-        configuration: Configuration = .default,
+        endpoints: Endpoints = .production,
         urlSession: URLSession = .shared
     ) {
-        self.configuration = configuration
+        self.endpoints = endpoints
         self.urlSession = urlSession
     }
     #endif
@@ -70,11 +55,16 @@ public struct TokenService: Sendable {
     ///
     /// Translates internal `TokenError`s into public `ConversationError`s so
     /// callers only ever deal with one error type.
-    public func fetchConnectionDetails(configuration: ConversationCredentials) async throws -> ConnectionDetails {
+    public func fetchConnectionDetails(
+        credentials: ConversationCredentials
+    ) async throws -> ConnectionDetails {
         do {
-            let token: String = switch configuration.authSource {
+            let token: String = switch credentials.authSource {
             case let .publicAgentId(agentId):
-                try await fetchTokenFromAPI(agentId: agentId, environment: configuration.environment)
+                try await fetchTokenFromAPI(
+                    agentId: agentId,
+                    environment: credentials.environment
+                )
             case let .conversationToken(conversationToken):
                 conversationToken
             case .signedWebSocketURL:
@@ -85,12 +75,10 @@ public struct TokenService: Sendable {
                 try await provider()
             }
 
-            let websocketURL = self.configuration.websocketURL ?? ConnectionConstants.voiceConversationUrl
-
             // ElevenLabs tokens contain room name and participant identity in the JWT
             // LiveKit will extract these automatically, so we provide empty values
             return ConnectionDetails(
-                serverUrl: websocketURL,
+                serverUrl: endpoints.voiceWebSocket.absoluteString,
                 roomName: "", // LiveKit extracts from JWT
                 participantName: "", // LiveKit extracts from JWT
                 participantToken: token
@@ -104,11 +92,14 @@ public struct TokenService: Sendable {
         }
     }
 
-    private func fetchTokenFromAPI(agentId: String, environment: String? = nil) async throws -> String {
-        // Build URL with agent ID as query parameter
-        let apiUrl = configuration.apiEndpoint ?? ConnectionConstants.tokenUrl
-
-        guard var components = URLComponents(string: apiUrl) else {
+    private func fetchTokenFromAPI(
+        agentId: String,
+        environment: String? = nil
+    ) async throws -> String {
+        guard var components = URLComponents(
+            url: endpoints.conversationToken,
+            resolvingAgainstBaseURL: false
+        ) else {
             throw TokenError.invalidURL
         }
         var queryItems = [

Sources/ElevenLabs/Public/Authorization/TokenService.swift

@@ -104,7 +104,7 @@ public final class ConversationClient: ObservableObject {
     ) async throws -> ConversationStartResult {
         let previousConversation = session
         let conversation = Conversation(
-            dependencyProvider: dependencyProvider ?? Dependencies(),
+            dependencyProvider: dependencyProvider ?? Dependencies(endpoints: config.endpoints),
             config: config,
             callbacks: callbacks,
             initialMicMuted: isMicMuted

Sources/ElevenLabs/Public/Conversation/ConversationClient.swift

@@ -35,6 +35,9 @@ public struct ConversationConfig: Sendable {
     /// instead of relying on LiveKit's isSpeaking detection.
     public var agentStateConfiguration: AgentStateConfiguration?
 
+    /// Network endpoints to connect to. Override for proxies, regional hosts, or staging.
+    public var endpoints: Endpoints
+
     public init(
         agentOverrides: AgentOverrides? = nil,
         ttsOverrides: TTSOverrides? = nil,
@@ -47,7 +50,8 @@ public struct ConversationConfig: Sendable {
         startupConfiguration: ConversationStartupConfiguration = .default,
         audioConfiguration: AudioPipelineConfiguration? = nil,
         networkConfiguration: WebRTCConfiguration = .default,
-        agentStateConfiguration: AgentStateConfiguration? = nil
+        agentStateConfiguration: AgentStateConfiguration? = nil,
+        endpoints: Endpoints = .production
     ) {
         self.agentOverrides = agentOverrides
         self.ttsOverrides = ttsOverrides
@@ -61,6 +65,7 @@ public struct ConversationConfig: Sendable {
         self.audioConfiguration = audioConfiguration
         self.networkConfiguration = networkConfiguration
         self.agentStateConfiguration = agentStateConfiguration
+        self.endpoints = endpoints
     }
 }
 
@@ -114,3 +119,33 @@ public struct ConversationOverrides: Sendable {
         self.clientEvents = clientEvents
     }
 }
+
+/// The network endpoints the SDK talks to. Defaults to ``production``.
+///
+/// Override for proxies, regional hosts, or staging. Credentials follow these
+/// endpoints — conversation tokens are sent to whichever `conversationToken`
+/// URL is configured.
+public struct Endpoints: Sendable, Equatable {
+    /// LiveKit signaling endpoint for voice conversations.
+    public var voiceWebSocket: URL
+    /// WebSocket endpoint for text-only conversations.
+    public var textWebSocket: URL
+    /// HTTP endpoint that issues conversation tokens.
+    public var conversationToken: URL
+
+    public init(
+        voiceWebSocket: URL = Endpoints.production.voiceWebSocket,
+        textWebSocket: URL = Endpoints.production.textWebSocket,
+        conversationToken: URL = Endpoints.production.conversationToken
+    ) {
+        self.voiceWebSocket = voiceWebSocket
+        self.textWebSocket = textWebSocket
+        self.conversationToken = conversationToken
+    }
+
+    public static let production = Endpoints(
+        voiceWebSocket: URL(string: "wss://livekit.rtc.elevenlabs.io")!,
+        textWebSocket: URL(string: "wss://api.elevenlabs.io/v1/convai/conversation")!,
+        conversationToken: URL(string: "https://api.elevenlabs.io/v1/convai/conversation/token")!
+    )
+}

Sources/ElevenLabs/Public/Conversation/ConversationConfig.swift

@@ -3,19 +3,13 @@ import Foundation
 extension ElevenLabs {
     /// Global SDK configuration.
     public struct Configuration: Sendable {
-        public let apiEndpoint: URL?
-        public let websocketUrl: String?
         public let logLevel: LogLevel
         public let debugMode: Bool
 
         public init(
-            apiEndpoint: URL? = nil,
-            websocketUrl: String? = nil,
             logLevel: LogLevel = .warning,
             debugMode: Bool = false
         ) {
-            self.apiEndpoint = apiEndpoint
-            self.websocketUrl = websocketUrl
             self.logLevel = logLevel
             self.debugMode = debugMode
         }
@@ -24,14 +18,10 @@ extension ElevenLabs {
 
         /// Create a new configuration with updated values (builder pattern)
         public func with(
-            apiEndpoint: URL? = nil,
-            websocketUrl: String? = nil,
             logLevel: LogLevel? = nil,
             debugMode: Bool? = nil
         ) -> Configuration {
             Configuration(
-                apiEndpoint: apiEndpoint ?? self.apiEndpoint,
-                websocketUrl: websocketUrl ?? self.websocketUrl,
                 logLevel: logLevel ?? self.logLevel,
                 debugMode: debugMode ?? self.debugMode
             )