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/examples/web_client.html

@@ -401,9 +401,14 @@
 
       const targetSampleRate = 16000;
       const playbackStopRampSec = 0.008;
-      const appId = "assistant_demo";
+      const assistantId = "assistant_demo";
       const channel = "web_client";
-      const configVersionId = "local-dev";
+
+      function buildSessionWsUrl(baseUrl) {
+        const parsed = new URL(baseUrl);
+        parsed.searchParams.set("assistant_id", assistantId);
+        return parsed.toString();
+      }
 
       function logLine(type, text, data) {
         const time = new Date().toLocaleTimeString();
@@ -556,14 +561,25 @@
 
       async function connect() {
         if (ws && ws.readyState === WebSocket.OPEN) return;
-        ws = new WebSocket(wsUrl.value.trim());
+        const sessionWsUrl = buildSessionWsUrl(wsUrl.value.trim());
+        ws = new WebSocket(sessionWsUrl);
         ws.binaryType = "arraybuffer";
 
         ws.onopen = () => {
           setStatus(true, "Session open");
           logLine("sys", "WebSocket connected");
           ensureAudioContext();
-          sendCommand({ type: "hello", version: "v1" });
+          sendCommand({
+            type: "session.start",
+            audio: { encoding: "pcm_s16le", sample_rate_hz: targetSampleRate, channels: 1 },
+            metadata: {
+              channel,
+              source: "web_client",
+              overrides: {
+                output: { mode: "audio" },
+              },
+            },
+          });
         };
 
         ws.onclose = () => {
@@ -622,17 +638,6 @@
         const type = event.type || "unknown";
         const ids = eventIdsSuffix(event);
         logLine("event", `${type}${ids}`, event);
-        if (type === "hello.ack") {
-          sendCommand({
-            type: "session.start",
-            audio: { encoding: "pcm_s16le", sample_rate_hz: targetSampleRate, channels: 1 },
-            metadata: {
-              appId,
-              channel,
-              configVersionId,
-            },
-          });
-        }
         if (type === "config.resolved") {
           logLine("sys", "config.resolved", event.config || {});
         }