Enhance WebSocket session management by requiring assistant_id as a query parameter for connection. Update API reference documentation to reflect changes in message flow and metadata validation rules, including the introduction of whitelists for allowed metadata fields and restrictions on sensitive keys. Refactor client examples to align with the new session initiation process.

engine/app/backend_adapters.py

@@ -157,16 +157,16 @@ class HttpBackendAdapter:
                 async with session.get(url) as resp:
                     if resp.status == 404:
                         logger.warning(f"Assistant config not found: {assistant_id}")
-                        return None
+                        return {"__error_code": "assistant.not_found", "assistantId": assistant_id}
                     resp.raise_for_status()
                     payload = await resp.json()
                     if not isinstance(payload, dict):
                         logger.warning("Assistant config payload is not a dict; ignoring")
-                        return None
+                        return {"__error_code": "assistant.config_unavailable", "assistantId": assistant_id}
                     return payload
         except Exception as exc:
             logger.warning(f"Failed to fetch assistant config ({assistant_id}): {exc}")
-            return None
+            return {"__error_code": "assistant.config_unavailable", "assistantId": assistant_id}
 
     async def create_call_record(
         self,

engine/app/main.py

@@ -163,13 +163,19 @@ async def websocket_endpoint(websocket: WebSocket):
     """
     await websocket.accept()
     session_id = str(uuid.uuid4())
+    assistant_id = str(websocket.query_params.get("assistant_id") or "").strip() or None
 
     # Create transport and session
     transport = SocketTransport(websocket)
-    session = Session(session_id, transport, backend_gateway=backend_gateway)
+    session = Session(
+        session_id,
+        transport,
+        backend_gateway=backend_gateway,
+        assistant_id=assistant_id,
+    )
     active_sessions[session_id] = session
 
-    logger.info(f"WebSocket connection established: {session_id}")
+    logger.info(f"WebSocket connection established: {session_id} assistant_id={assistant_id or '-'}")
 
     last_received_at: List[float] = [time.monotonic()]
     last_heartbeat_at: List[float] = [0.0]
@@ -239,16 +245,22 @@ async def webrtc_endpoint(websocket: WebSocket):
         return
     await websocket.accept()
     session_id = str(uuid.uuid4())
+    assistant_id = str(websocket.query_params.get("assistant_id") or "").strip() or None
 
     # Create WebRTC peer connection
     pc = RTCPeerConnection()
 
     # Create transport and session
     transport = WebRtcTransport(websocket, pc)
-    session = Session(session_id, transport, backend_gateway=backend_gateway)
+    session = Session(
+        session_id,
+        transport,
+        backend_gateway=backend_gateway,
+        assistant_id=assistant_id,
+    )
     active_sessions[session_id] = session
 
-    logger.info(f"WebRTC connection established: {session_id}")
+    logger.info(f"WebRTC connection established: {session_id} assistant_id={assistant_id or '-'}")
 
     last_received_at: List[float] = [time.monotonic()]
     last_heartbeat_at: List[float] = [0.0]