Pass environment on the public-agent handshake and conversation init.

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

Author: renal128

Sources/ElevenLabs/Internal/Authorization/TokenService.swift

@@ -48,11 +48,11 @@ struct TokenService: Sendable {
     ///
     /// Translates internal `TokenError`s into public `ConversationError`s so
     /// callers only ever deal with one error type.
-    func fetchToken(for auth: ConversationAuth.Voice) async throws -> String {
+    func fetchToken(for auth: ConversationAuth.Voice, environment: String?) async throws -> String {
         do {
             switch auth {
             case let .publicAgent(agentId):
-                return try await fetchTokenFromAPI(agentId: agentId)
+                return try await fetchTokenFromAPI(agentId: agentId, environment: environment)
             case let .conversationToken(mint):
                 return try await mint()
             }

Sources/ElevenLabs/Internal/Authorization/TokenServicing.swift

@@ -2,7 +2,7 @@ import Foundation
 
 protocol TokenServicing: Sendable {
     /// Resolve the token a voice conversation authenticates with.
-    func fetchToken(for auth: ConversationAuth.Voice) async throws -> String
+    func fetchToken(for auth: ConversationAuth.Voice, environment: String?) async throws -> String
 }
 
 extension TokenService: TokenServicing {}

Sources/ElevenLabs/Internal/Networking/WebRTCConnectionManager.swift

@@ -101,7 +101,7 @@ final class WebRTCConnectionManager: WebRTCConnectionManaging {
         let token = try await runPhase(
             timing: \.tokenFetch, metrics: &metrics, startTime: startTime
         ) {
-            try await tokenService.fetchToken(for: auth)
+            try await tokenService.fetchToken(for: auth, environment: config.environment)
         }
 
         // 2. Request microphone permission (denial doesn't block startup).

Sources/ElevenLabs/Internal/Networking/WebSocketConnectionManager.swift

@@ -51,7 +51,8 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
         do {
             resolved = try await Self.websocketUrl(
                 for: auth,
-                endpoints: endpoints
+                endpoints: endpoints,
+                environment: config.environment
             )
         } catch is CancellationError {
             throw CancellationError()
@@ -180,7 +181,8 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
 
     static func websocketUrl(
         for auth: ConversationAuth.TextOnly,
-        endpoints: Endpoints
+        endpoints: Endpoints,
+        environment: String? = nil
     ) async throws -> (url: URL, agentId: String) {
         switch auth {
         case let .publicAgent(agentId):
@@ -189,6 +191,9 @@ final class WebSocketConnectionManager: WebSocketConnectionManaging {
             }
             var queryItems = components.queryItems ?? []
             queryItems.append(URLQueryItem(name: "agent_id", value: agentId))
+            if let environment {
+                queryItems.append(URLQueryItem(name: "environment", value: environment))
+            }
             components.queryItems = queryItems
             guard let url = components.url else {
                 throw ConversationError.authenticationFailed("Invalid conversation URL")

Sources/ElevenLabs/Internal/Utilities/EventSerializer.swift

@@ -128,6 +128,10 @@ enum EventSerializer {
             json["user_id"] = userId
         }
 
+        if let environment = config.environment {
+            json["environment"] = environment
+        }
+
         return json
     }
 }

Sources/ElevenLabs/Public/Conversation/ConversationConfig.swift

@@ -8,7 +8,8 @@ public struct ConversationConfig: Sendable {
     public var customLlmExtraBody: [String: String]? // Simplified to be Sendable
     public var dynamicVariables: [String: String]? // Simplified to be Sendable
     public var userId: String?
-    /// Optional environment for the agent (defaults to production when nil)
+    /// Workspace environment (`production` if nil). Applied to the public-agent
+    /// handshake and conversation init.
     public var environment: String?
 
     /// How to handle microphone setup failures during connection.

Tests/ElevenLabsTests/Mocks/MockWebSocketConnectionManager.swift

@@ -37,7 +37,8 @@ final class MockWebSocketConnectionManager: WebSocketConnectionManaging {
         do {
             resolved = try await WebSocketConnectionManager.websocketUrl(
                 for: auth,
-                endpoints: config.endpoints
+                endpoints: config.endpoints,
+                environment: config.environment
             )
             lastConnectedURL = resolved.url
         } catch {

Tests/ElevenLabsTests/Unit/ElevenLabsSDKTests.swift

@@ -56,6 +56,28 @@ final class ElevenLabsSDKTests: XCTestCase {
         XCTAssertEqual(resolved.agentId, "agent-123")
     }
 
+    @MainActor
+    func testWebsocketUrlAppendsPublicAgentEnvironment() async throws {
+        let resolved = try await WebSocketConnectionManager.websocketUrl(
+            for: .publicAgent(id: "agent-123"),
+            endpoints: .production,
+            environment: "staging"
+        )
+        XCTAssertEqual(
+            resolved.url.absoluteString,
+            "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=agent-123&environment=staging"
+        )
+    }
+
+    func testConversationInitIncludesEnvironment() throws {
+        let config = ConversationConfig(environment: "staging")
+        let data = try EventSerializer.serializeOutgoingEvent(
+            .conversationInit(ConversationInitEvent(config: config))
+        )
+        let json = try XCTUnwrap(JSONSerialization.jsonObject(with: data) as? [String: Any])
+        XCTAssertEqual(json["environment"] as? String, "staging")
+    }
+
     func testConversationConfigDefaults() {
         let config = ConversationConfig()