refactor: make conversation endpoints configurable per session

Add Endpoints on ConversationConfig and wire them through TokenService and the connection managers. HTTP requests derive from a single apiBase; ws/wss endpoints stay explicit. Drop ConnectionConstants and the global apiEndpoint/websocketUrl overrides.

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

Author: renal128

README.md

@@ -232,6 +232,16 @@ ElevenLabs.configure(
 )
 ```
 
+### Custom Endpoints
+
+Point the HTTP API base or either WebSocket endpoint at a proxy, regional host, or staging:
+
+```swift
+let config = ConversationConfig(
+    endpoints: Endpoints(apiBase: URL(string: "https://my-proxy.example.com")!)
+)
+```
+
 ### Fine-Grained Callbacks
 
 Want to handle events without Combine? Use `ConversationCallbacks`:

Sources/ElevenLabs/Internal/Authorization/ConnectionConstants.swift

@@ -1,10 +1,9 @@
 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
+    /// Resolve the token a voice conversation authenticates with.
+    /// - Parameter credentials: The credentials to authenticate with
+    func fetchToken(for credentials: ConversationCredentials) async throws -> String
 }
 
 extension TokenService: TokenServicing {}

Sources/ElevenLabs/Internal/Authorization/TokenServicing.swift

@@ -14,15 +14,15 @@ 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),
+            endpoints: endpoints
+        )
+        webSocketConnectionManager = WebSocketConnectionManager(logger: logger, endpoints: endpoints)
     }
 }

Sources/ElevenLabs/Internal/DI/Dependencies.swift

@@ -67,10 +67,12 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
 
     private let logger: any Logging
     private let tokenService: any TokenServicing
+    private let endpoints: Endpoints
 
-    init(logger: any Logging, tokenService: any TokenServicing) {
+    init(logger: any Logging, tokenService: any TokenServicing, endpoints: Endpoints) {
         self.logger = logger
         self.tokenService = tokenService
+        self.endpoints = endpoints
     }
 
     // MARK: – Public API
@@ -92,12 +94,12 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
         var metrics = ConversationStartupMetrics()
         logger.info("Starting conversation startup sequence", context: ["agentId": auth.agentId])
 
-        // 1. Resolve token / connection details.
+        // 1. Resolve the conversation token.
         onStartupStateChange(.resolvingToken)
-        let connectionDetails = try await runPhase(
+        let token = try await runPhase(
             timing: \.tokenFetch, metrics: &metrics, startTime: startTime
         ) {
-            try await tokenService.fetchConnectionDetails(configuration: auth)
+            try await tokenService.fetchToken(for: auth)
         }
 
         // 2. Request microphone permission (denial doesn't block startup).
@@ -110,7 +112,7 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
             timing: \.roomConnect, metrics: &metrics, startTime: startTime
         ) {
             try await connectToRoom(
-                details: connectionDetails,
+                token: token,
                 enableMic: permissionGranted,
                 throwOnMicrophoneFailure: throwOnMicFailure,
                 networkConfiguration: config.networkConfiguration,
@@ -217,12 +219,12 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
     /// used by `connect`).
     ///
     /// - Parameters:
-    ///   - details: Token-service credentials (URL + participant token).
+    ///   - token: Conversation token to authenticate the room with.
     ///   - enableMic: Whether to enable the local microphone immediately.
     ///   - throwOnMicrophoneFailure: If true, throws error when microphone setup fails.
     ///     If false, logs warning and continues.
     private func connectToRoom(
-        details: TokenService.ConnectionDetails,
+        token: String,
         enableMic: Bool,
         throwOnMicrophoneFailure: Bool,
         networkConfiguration: WebRTCConfiguration,
@@ -258,8 +260,8 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
         let connectStart = Date()
         do {
             try await room.connect(
-                url: details.serverUrl,
-                token: details.participantToken,
+                url: endpoints.voiceWebSocket.absoluteString,
+                token: token,
                 connectOptions: connectOptions
             )
             logger.info("LiveKit room.connect completed", context: ["duration": "\(Date().timeIntervalSince(connectStart))"])

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.websocketUrl(for: auth, endpoints: endpoints)
         } catch {
             metrics.total = Date().timeIntervalSince(startTime)
             let convError = error as? ConversationError ?? .authenticationFailed(error.localizedDescription)
@@ -147,12 +149,16 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
         }
     }
 
-    static func url(for auth: ConversationCredentials) throws -> URL {
+    static func websocketUrl(for auth: ConversationCredentials, endpoints: Endpoints) throws -> URL {
         switch auth.authSource {
         case let .publicAgentId(agentId):
-            var components = URLComponents(string: ConnectionConstants.textConversationUrl)
-            components?.queryItems = [URLQueryItem(name: "agent_id", value: agentId)]
-            guard let url = components?.url else {
+            guard var components = URLComponents(url: endpoints.textWebSocket, resolvingAgainstBaseURL: false) else {
+                throw ConversationError.authenticationFailed("Invalid conversation URL")
+            }
+            var queryItems = components.queryItems ?? []
+            queryItems.append(URLQueryItem(name: "agent_id", value: agentId))
+            components.queryItems = queryItems
+            guard let url = components.url else {
                 throw ConversationError.authenticationFailed("Invalid conversation URL")
             }
             return url

Sources/ElevenLabs/Internal/Networking/WebSocketConnectionManager.swift

@@ -17,29 +17,7 @@ import Foundation
 /// Service for managing ElevenLabs authentication
 /// This is designed to be stateless and SDK-friendly
 public struct TokenService: Sendable {
-    public struct ConnectionDetails: Codable, Sendable {
-        public let serverUrl: String
-        public let roomName: String
-        public let participantName: String
-        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,53 +26,45 @@ 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
 
-    /// Fetch connection details for ElevenLabs conversation.
+    /// Resolve the token a voice conversation authenticates with.
     ///
     /// 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 fetchToken(for credentials: ConversationCredentials) async throws -> String {
         do {
-            let token: String = switch configuration.authSource {
+            switch credentials.authSource {
             case let .publicAgentId(agentId):
-                try await fetchTokenFromAPI(agentId: agentId, environment: configuration.environment)
+                return try await fetchTokenFromAPI(
+                    agentId: agentId,
+                    environment: credentials.environment
+                )
             case let .conversationToken(conversationToken):
-                conversationToken
+                return conversationToken
             case .signedWebSocketURL:
                 throw ConversationError.authenticationFailed(
                     "Signed WebSocket URLs are only supported for text-only conversations."
                 )
             case let .customTokenProvider(provider):
-                try await provider()
+                return 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,
-                roomName: "", // LiveKit extracts from JWT
-                participantName: "", // LiveKit extracts from JWT
-                participantToken: token
-            )
         } catch let error as ConversationError {
             throw error
         } catch let error as TokenError {
@@ -104,14 +74,18 @@ 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 = [
+        var queryItems = components.queryItems ?? []
+        queryItems += [
             URLQueryItem(name: "agent_id", value: agentId),
             URLQueryItem(name: "source", value: "swift_sdk"),
             URLQueryItem(name: "version", value: SDKVersion.version)

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,36 @@ 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 `apiBase` is configured.
+public struct Endpoints: Sendable, Equatable {
+    /// Base URL for the HTTP API. Request paths are appended to it.
+    public var apiBase: URL
+    /// WebSocket endpoint for voice conversations.
+    public var voiceWebSocket: URL
+    /// WebSocket endpoint for text-only conversations.
+    public var textWebSocket: URL
+
+    public init(
+        apiBase: URL = Endpoints.production.apiBase,
+        voiceWebSocket: URL = Endpoints.production.voiceWebSocket,
+        textWebSocket: URL = Endpoints.production.textWebSocket
+    ) {
+        self.apiBase = apiBase
+        self.voiceWebSocket = voiceWebSocket
+        self.textWebSocket = textWebSocket
+    }
+
+    public static let production = Endpoints(
+        apiBase: URL(string: "https://api.elevenlabs.io")!,
+        voiceWebSocket: URL(string: "wss://livekit.rtc.elevenlabs.io")!,
+        textWebSocket: URL(string: "wss://api.elevenlabs.io/v1/convai/conversation")!
+    )
+
+    var conversationToken: URL {
+        apiBase.appendingPathComponent("v1/convai/conversation/token")
+    }
+}