ttp-agent-sdk 2.5.6 → 2.5.7

package/dist/index.html

@@ -23,7 +23,7 @@
           <img src="https://talktopc.com/logo192.png" alt="TTP Logo" style="width: 40px; height: 40px; border-radius: 8px;">
           <div>
             <h1 style="margin: 0; font-size: 1.4rem;">TTP Agent SDK</h1>
-            <p class="version" style="margin: 0;">v2.3.19</p>
+            <p class="version" style="margin: 0;">v2.3.18</p>
           </div>
         </div>
       </div>
@@ -43,6 +43,7 @@
           <ul>
             <li><a href="#authentication" class="nav-link">Authentication</a></li>
             <li><a href="#agent-override" class="nav-link">Agent Override</a></li>
+            <li><a href="#variables" class="nav-link">Variables in Hello Request</a></li>
             <li><a href="#events" class="nav-link">Events & Callbacks</a></li>
             <li><a href="#protocol-v2" class="nav-link">Protocol v2 - Format Negotiation</a></li>
           </ul>
@@ -133,19 +134,19 @@
                 <span class="quick-link-arrow">→</span>
               </a>
               
-              <a href="#java-sdk" class="quick-link-card">
-                <div class="quick-link-icon">☕</div>
-                <h3>Java SDK</h3>
-                <p>Backend SDK for server-side TTS</p>
-                <span class="quick-link-arrow">→</span>
-              </a>
-              
               <a href="#text-to-speech" class="quick-link-card">
                 <div class="quick-link-icon">🔊</div>
                 <h3>Text To Speech</h3>
                 <p>REST API for voice synthesis</p>
                 <span class="quick-link-arrow">→</span>
               </a>
+              
+              <a href="#java-sdk" class="quick-link-card">
+                <div class="quick-link-icon">☕</div>
+                <h3>Java SDK</h3>
+                <p>Backend SDK for server-side TTS</p>
+                <span class="quick-link-arrow">→</span>
+              </a>
             </div>
           </div>
 
@@ -256,7 +257,7 @@ const { signedUrl } = await response.json();</code></pre>
               <pre><code>import { VoiceSDK } from 'ttp-agent-sdk';
 
 const voiceSDK = new VoiceSDK({
-  websocketUrl: signedUrl,  // Signed URL from step 1
+  signedUrl: signedUrl,  // signedUrl from step 1
   appId: 'your_app_id',     // Your application ID
   agentId: 'agent_123',     // The AI agent to connect to
   
@@ -563,7 +564,7 @@ app.post('/api/get-voice-session', async (req, res) => {
 
           <h2>Example</h2>
           <pre><code>const voiceSDK = new VoiceSDK({
-  websocketUrl: signedUrl,  // Signed URL from your backend
+  signedUrl: signedUrl,  // signedUrl from your backend
   appId: 'your_app_id',     // Your application ID
   agentId: 'agent_123',     // The AI agent to connect to
   
@@ -635,6 +636,371 @@ app.post('/api/get-voice-session', async (req, res) => {
           </div>
         </section>
 
+        <!-- Variables in Hello Request -->
+        <section id="variables" class="doc-section">
+          <h1>Variables in Hello Request</h1>
+          
+          <h2>Overview</h2>
+          <p>Variables allow you to pass dynamic values to your agent that will be used to replace placeholders in the system prompt and first message. Variables sent in the hello request take precedence over default variables stored in the agent configuration.</p>
+
+          <h2>Hello Message Format</h2>
+
+          <h3>SDK v2 Format (Recommended)</h3>
+          <p>When using VoiceSDK v2, variables are passed in the SDK constructor:</p>
+          <pre><code>import { VoiceSDK_v2 } from 'ttp-agent-sdk';
+
+// Get signed URL from your backend first
+const response = await fetch('/api/get-voice-session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ agentId: 'agent_5a2b984c1', appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC' })
+});
+const { signedUrl } = await response.json();
+
+const voiceSDK = new VoiceSDK_v2({
+  signedUrl: signedUrl,  // Use signedUrl from backend
+  agentId: 'agent_5a2b984c1',
+  appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC',
+  
+  // Variables (optional)
+  variables: {
+    USER_NAME: 'John',
+    ACCOUNT_TYPE: 'premium',
+    LANGUAGE: 'en-US'
+  },
+  
+  // Audio format configuration
+  sampleRate: 44100,
+  channels: 1,
+  bitDepth: 16,
+  outputContainer: 'raw',
+  outputEncoding: 'pcm',
+  outputSampleRate: 44100,
+  outputChannels: 1,
+  outputBitDepth: 16,
+  outputFrameDurationMs: 600
+});
+
+await voiceSDK.connect();</code></pre>
+
+          <h3>Raw WebSocket Format</h3>
+          <p>If connecting via raw WebSocket (without SDK), send variables in the hello message:</p>
+          <pre><code>{
+  "t": "hello",
+  "v": 2,
+  "variables": {
+    "USER_NAME": "John",
+    "ACCOUNT_TYPE": "premium",
+    "LANGUAGE": "en-US"
+  },
+  "inputFormat": {
+    "encoding": "pcm",
+    "sampleRate": 44100,
+    "channels": 1,
+    "bitDepth": 16
+  },
+  "requestedOutputFormat": {
+    "encoding": "pcm",
+    "sampleRate": 44100,
+    "channels": 1,
+    "bitDepth": 16,
+    "container": "raw"
+  },
+  "outputFrameDurationMs": 600
+}</code></pre>
+
+          <h2>Variable Format</h2>
+          <p>Variables are sent as a JSON object where:</p>
+          <ul>
+            <li><strong>Keys</strong>: Variable names (case-sensitive, e.g., <code>USER_NAME</code>)</li>
+            <li><strong>Values</strong>: String values that will replace <code>{{VARIABLE_NAME}}</code> in the prompt</li>
+          </ul>
+
+          <h3>Example</h3>
+          <pre><code>{
+  "variables": {
+    "USER_NAME": "John",
+    "ACCOUNT_TYPE": "premium",
+    "LANGUAGE": "en-US",
+    "COMPANY": "Acme Corp"
+  }
+}</code></pre>
+
+          <h2>Variable Replacement Priority</h2>
+          <p>Variables are replaced in the following priority order:</p>
+          <ol>
+            <li><strong>Hello Variables</strong> (highest priority) - Variables sent in the hello request</li>
+            <li><strong>Default Variables</strong> - Variables stored in agent configuration (Redis)</li>
+            <li><strong>Leave as-is</strong> - If no value found, <code>{{VARIABLE_NAME}}</code> remains unchanged</li>
+          </ol>
+
+          <h3>Example Priority</h3>
+          <p><strong>Agent Configuration (Redis):</strong></p>
+          <pre><code>{
+  "USER_NAME": "David",
+  "ACCOUNT_TYPE": "premium"
+}</code></pre>
+
+          <p><strong>Hello Request:</strong></p>
+          <pre><code>{
+  "variables": {
+    "USER_NAME": "John"
+  }
+}</code></pre>
+
+          <p><strong>Result:</strong></p>
+          <ul>
+            <li><code>{{USER_NAME}}</code> → <code>"John"</code> (from hello - takes precedence)</li>
+            <li><code>{{ACCOUNT_TYPE}}</code> → <code>"premium"</code> (from defaults - hello doesn't override)</li>
+          </ul>
+
+          <h2>Usage Examples</h2>
+
+          <h3>Example 1: JavaScript/TypeScript with SDK v2</h3>
+          <pre><code>import { VoiceSDK_v2 } from 'ttp-agent-sdk';
+
+// Get signed URL from your backend first
+const response = await fetch('/api/get-voice-session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ agentId: 'agent_5a2b984c1', appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC' })
+});
+const { signedUrl } = await response.json();
+
+const voiceSDK = new VoiceSDK_v2({
+  signedUrl: signedUrl,  // Use signedUrl from backend
+  agentId: 'agent_5a2b984c1',
+  appId: 'app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC',
+  
+  variables: {
+    USER_NAME: 'John Doe',
+    ACCOUNT_TYPE: 'premium',
+    LANGUAGE: 'en-US'
+  },
+  
+  // ... audio format config
+});
+
+await voiceSDK.connect();</code></pre>
+
+          <h3>Example 2: Raw WebSocket (JavaScript)</h3>
+          <pre><code>const ws = new WebSocket('wss://speech.talktopc.com/ws/conv?agentId=agent_5a2b984c1&appId=app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC');
+
+ws.onopen = () => {
+  const helloMessage = {
+    t: 'hello',
+    v: 2,
+    variables: {
+      USER_NAME: 'John',
+      ACCOUNT_TYPE: 'premium',
+      LANGUAGE: 'en-US'
+    },
+    inputFormat: {
+      encoding: 'pcm',
+      sampleRate: 44100,
+      channels: 1,
+      bitDepth: 16
+    },
+    requestedOutputFormat: {
+      encoding: 'pcm',
+      sampleRate: 44100,
+      channels: 1,
+      bitDepth: 16,
+      container: 'raw'
+    },
+    outputFrameDurationMs: 600
+  };
+  
+  ws.send(JSON.stringify(helloMessage));
+};</code></pre>
+
+          <h3>Example 3: Python WebSocket</h3>
+          <pre><code>import websocket
+import json
+
+def on_open(ws):
+    hello_message = {
+        "t": "hello",
+        "v": 2,
+        "variables": {
+            "USER_NAME": "John",
+            "ACCOUNT_TYPE": "premium",
+            "LANGUAGE": "en-US"
+        },
+        "inputFormat": {
+            "encoding": "pcm",
+            "sampleRate": 44100,
+            "channels": 1,
+            "bitDepth": 16
+        },
+        "requestedOutputFormat": {
+            "encoding": "pcm",
+            "sampleRate": 44100,
+            "channels": 1,
+            "bitDepth": 16,
+            "container": "raw"
+        },
+        "outputFrameDurationMs": 600
+    }
+    
+    ws.send(json.dumps(hello_message))
+
+ws = websocket.WebSocketApp(
+    "wss://speech.talktopc.com/ws/conv?agentId=agent_5a2b984c1&appId=app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC",
+    on_open=on_open
+)
+ws.run_forever()</code></pre>
+
+          <h3>Example 4: cURL / wscat</h3>
+          <pre><code># Using wscat
+wscat -c "wss://speech.talktopc.com/ws/conv?agentId=agent_5a2b984c1&appId=app_Bc01EqMQt2Euehl4qqZSi6l3FJP42Q9vJ0pC"
+
+# Then send:
+{"t":"hello","v":2,"variables":{"USER_NAME":"John","ACCOUNT_TYPE":"premium"},"inputFormat":{"encoding":"pcm","sampleRate":44100,"channels":1,"bitDepth":16},"requestedOutputFormat":{"encoding":"pcm","sampleRate":44100,"channels":1,"bitDepth":16,"container":"raw"},"outputFrameDurationMs":600}</code></pre>
+
+          <h2>Agent Prompt Setup</h2>
+          <p>To use variables in your agent, include placeholders in the system prompt or first message:</p>
+
+          <h3>System Prompt Example</h3>
+          <pre><code>Your name is {{AGENT_NAME}}.
+You are helping {{USER_NAME}} who has a {{ACCOUNT_TYPE}} account.
+Speak in {{LANGUAGE}}.</code></pre>
+
+          <h3>First Message Example</h3>
+          <pre><code>Hello {{USER_NAME}}! Welcome to our {{ACCOUNT_TYPE}} service.</code></pre>
+
+          <h2>Backend Processing</h2>
+          <p>When the hello request is received with variables:</p>
+          <ol>
+            <li><strong>Variables are extracted</strong> from the hello message</li>
+            <li><strong>Default variables are loaded</strong> from agent configuration (Redis)</li>
+            <li><strong>Variables are merged</strong> (hello variables take precedence)</li>
+            <li><strong>Prompt is processed</strong> - <code>{{VARIABLE_NAME}}</code> placeholders are replaced</li>
+            <li><strong>First message is processed</strong> - Variables are replaced here too</li>
+            <li><strong>Metadata is added</strong> - Variables metadata section is appended to prompt</li>
+          </ol>
+
+          <h3>Server Logs</h3>
+          <p>After sending hello with variables, check server logs for:</p>
+          <pre><code>📝 Processing variables from hello message: [USER_NAME, ACCOUNT_TYPE, LANGUAGE]
+✅ Variables processed and prompt updated
+📝 FINAL PROCESSED PROMPT (agentId: ...):
+[Prompt with variables replaced]
+✅ Processed variables: 3 hello variables, 2 default variables, metadata: added</code></pre>
+
+          <h2>Variable Naming Conventions</h2>
+          <ul>
+            <li>Use <strong>UPPERCASE</strong> with underscores: <code>USER_NAME</code>, <code>ACCOUNT_TYPE</code></li>
+            <li>Variable names are <strong>case-sensitive</strong></li>
+            <li>Avoid special characters except underscores</li>
+            <li>Recommended format: <code>{{VARIABLE_NAME}}</code> in prompts</li>
+          </ul>
+
+          <h2>Common Use Cases</h2>
+
+          <h3>1. User Personalization</h3>
+          <pre><code>{
+  "variables": {
+    "USER_NAME": "John Doe",
+    "USER_EMAIL": "john@example.com"
+  }
+}</code></pre>
+
+          <h3>2. Account Context</h3>
+          <pre><code>{
+  "variables": {
+    "ACCOUNT_TYPE": "premium",
+    "SUBSCRIPTION_STATUS": "active"
+  }
+}</code></pre>
+
+          <h3>3. Language/Localization</h3>
+          <pre><code>{
+  "variables": {
+    "LANGUAGE": "en-US",
+    "CURRENCY": "USD"
+  }
+}</code></pre>
+
+          <h3>4. Session Context</h3>
+          <pre><code>{
+  "variables": {
+    "SESSION_ID": "abc123",
+    "PAGE_URL": "https://example.com/products"
+  }
+}</code></pre>
+
+          <h2>Error Handling</h2>
+
+          <h3>Missing Variables</h3>
+          <p>If a variable is referenced in the prompt but not provided:</p>
+          <ul>
+            <li><strong>Has default value</strong>: Uses default from agent configuration</li>
+            <li><strong>No default value</strong>: Placeholder remains unchanged (<code>{{VARIABLE_NAME}}</code>)</li>
+          </ul>
+
+          <h3>Invalid Variable Format</h3>
+          <ul>
+            <li>Variables must be a JSON object</li>
+            <li>Values should be strings (will be converted to string if needed)</li>
+            <li>Empty object <code>{}</code> or <code>null</code> is valid (will use defaults only)</li>
+          </ul>
+
+          <h2>Best Practices</h2>
+          <ol>
+            <li><strong>Set defaults</strong> in agent configuration for all variables</li>
+            <li><strong>Override with hello variables</strong> only when you have dynamic values</li>
+            <li><strong>Use descriptive names</strong> that clearly indicate the variable's purpose</li>
+            <li><strong>Document variables</strong> in your agent's description or notes</li>
+            <li><strong>Test variables</strong> by checking server logs for "FINAL PROCESSED PROMPT"</li>
+          </ol>
+
+          <h2>API Reference</h2>
+
+          <h3>Hello Message Structure</h3>
+          <pre><code>interface HelloMessage {
+  t: "hello";                    // Message type
+  v?: number;                    // SDK version (2 for v2)
+  variables?: {                   // Optional variables object
+    [key: string]: string;        // Variable name -> value mapping
+  };
+  inputFormat?: AudioFormat;     // Input audio format
+  requestedOutputFormat?: AudioFormat; // Output audio format
+  outputFrameDurationMs?: number; // Frame duration for streaming
+}
+
+interface AudioFormat {
+  encoding: "pcm" | "pcmu" | "pcma";
+  sampleRate: number;
+  channels: number;
+  bitDepth: number;
+  container?: "raw" | "wav";      // For output format only
+}</code></pre>
+
+          <h2>Troubleshooting</h2>
+
+          <h3>Variables Not Being Replaced</h3>
+          <ol>
+            <li>Check variable names match exactly (case-sensitive)</li>
+            <li>Verify variables are sent in hello message (check logs)</li>
+            <li>Check server logs for "FINAL PROCESSED PROMPT" to see actual replacement</li>
+          </ol>
+
+          <h3>Variables Not in Hello Message</h3>
+          <ul>
+            <li>SDK v2: Check if SDK supports <code>variables</code> in constructor</li>
+            <li>Raw WebSocket: Ensure <code>variables</code> field is included in JSON</li>
+            <li>Check WebSocket message is sent after connection opens</li>
+          </ul>
+
+          <h3>Default Variables Not Used</h3>
+          <ul>
+            <li>Verify variables are stored in Redis (check agent configuration)</li>
+            <li>Check <code>extractVariablesFromAgentConfig</code> is working</li>
+            <li>Look for "Default variables not found in state" warnings in logs</li>
+          </ul>
+        </section>
+
         <!-- Events -->
         <section id="events" class="doc-section">
           <h1>Events & Callbacks</h1>
@@ -823,7 +1189,7 @@ voiceSDK.on('domainError', (error) => {
 
           <h2>Example: High-Quality Audio</h2>
           <pre><code>const voiceSDK = new VoiceSDK({
-  websocketUrl: signedUrl,
+  signedUrl: signedUrl,  // signedUrl from backend
   appId: 'your_app_id',
   agentId: 'agent_123',
   
@@ -845,7 +1211,7 @@ voiceSDK.on('formatNegotiated', (format) => {
 
           <h2>Example: Bandwidth-Optimized Audio</h2>
           <pre><code>const voiceSDK = new VoiceSDK({
-  websocketUrl: signedUrl,
+  signedUrl: signedUrl,  // signedUrl from backend
   appId: 'your_app_id',
   agentId: 'agent_123',
   
@@ -927,6 +1293,20 @@ voiceSDK.on('formatNegotiated', (format) => {
   agentId: 'agent_123',       // Your AI agent ID
   appId: 'your_app_id',       // Your application ID
   
+  // Optional - Signed URL (recommended for production)
+  signedUrl: 'wss://speech.talktopc.com/ws/conv?signed_token=...', // Signed URL from your backend
+  
+  // Optional - Agent Settings Override (requires signed URL with allowOverride=true)
+  agentSettingsOverride: {
+    prompt: "You are a helpful customer service assistant.",
+    temperature: 0.8,
+    voiceId: "F2",
+    voiceSpeed: 1.2,
+    firstMessage: "Hello! How can I help you today?",
+    disableInterruptions: false,
+    maxCallDuration: 600
+  },
+  
   // Optional - Appearance
   primaryColor: '#7C3AED',    // Widget theme color
   position: 'bottom-right',   // 'bottom-right', 'bottom-left'
@@ -941,6 +1321,106 @@ voiceSDK.on('formatNegotiated', (format) => {
   }
 });</code></pre>
 
+          <h2>Signed Link Authentication (Production)</h2>
+          <div class="warning-box">
+            <strong>🔒 Security Best Practice:</strong> For production applications, use signed links instead of exposing agent IDs directly. Signed links provide secure, time-limited authentication.
+          </div>
+          
+          <p>To use signed links with the widget, provide a <code>signedUrl</code> parameter. You should fetch this signed URL from your backend before initializing the widget:</p>
+          
+          <pre><code>// Step 1: Get signed URL from your backend
+async function initializeWidget() {
+  // Request signed URL from your backend
+  const response = await fetch('/api/get-voice-session', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${getAuthToken()}` // Your auth token
+    },
+    body: JSON.stringify({
+      agentId: 'agent_123',
+      appId: 'your_app_id',
+      variables: {
+        userName: 'John Doe',
+        page: 'homepage'
+      }
+    })
+  });
+  
+  if (!response.ok) {
+    throw new Error(`Backend API error: ${response.status}`);
+  }
+  
+  const data = await response.json();
+  
+  // Backend must return signedUrl field
+  if (!data.signedUrl) {
+    throw new Error('Backend response must contain "signedUrl" field');
+  }
+  
+  // Step 2: Initialize widget with signedUrl
+  const widget = new TTPAgentSDK.TTPChatWidget({
+    agentId: 'agent_123',
+    appId: 'your_app_id',
+    signedUrl: data.signedUrl,  // Use signed URL from backend
+    variables: {
+      userName: 'John Doe',
+      page: 'homepage'
+    }
+  });
+}
+
+// Initialize when ready
+initializeWidget();</code></pre>
+          
+          <div class="info-box">
+            <strong>📋 Important:</strong>
+            <ul style="margin-top: 10px; margin-left: 20px;">
+              <li>The widget accepts <code>signedUrl</code> as a direct parameter (not <code>getSessionUrl</code>)</li>
+              <li>You must fetch the signed URL from your backend before initializing the widget</li>
+              <li>Your backend must return a response with a <code>signedUrl</code> field (not <code>websocketUrl</code>, <code>url</code>, or any other field)</li>
+              <li>If <code>signedUrl</code> is not provided, the widget will construct a URL from <code>agentId</code> and <code>appId</code> (less secure)</li>
+              <li>Your backend should authenticate with TTP backend using your API key (see <a href="#authentication">Authentication</a> section)</li>
+            </ul>
+          </div>
+          
+          <h3>Backend Implementation Example</h3>
+          <p>Your backend endpoint should request signed URLs from TTP:</p>
+          <pre><code>// Your Backend (Node.js/Express example)
+app.post('/api/get-voice-session', async (req, res) => {
+  const { agentId, appId, variables } = req.body;
+  
+  // Authenticate your user
+  if (!req.user) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+  
+  // Backend-to-Backend: Request signed URL from TTP
+  const response = await fetch('https://backend.talktopc.com/api/public/agents/signed-url', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${process.env.TTP_API_KEY}` // Your TTP API key
+    },
+    body: JSON.stringify({
+      agentId,
+      appId,
+      variables
+    })
+  });
+  
+  if (!response.ok) {
+    return res.status(500).json({ error: 'Failed to get signed URL' });
+  }
+  
+  const data = await response.json();
+  
+  // Return signedUrl to frontend
+  res.json({
+    signedUrl: data.signedUrl
+  });
+});</code></pre>
+
           <h2>Advanced Customization</h2>
           
           <h3>Icon Customization</h3>
@@ -984,6 +1464,39 @@ voiceSDK.on('formatNegotiated', (format) => {
   }
 });</code></pre>
 
+          <h3>Agent Settings Override</h3>
+          <div class="info-box">
+            <strong>🔒 Security:</strong> Agent settings override requires a signed URL with <code>allowOverride: true</code> granted by your backend.
+          </div>
+          <p>Dynamically customize agent behavior, voice, and personality on a per-session basis:</p>
+          <pre><code>const widget = new TTPAgentSDK.TTPChatWidget({
+  agentId: 'agent_123',
+  appId: 'your_app_id',
+  signedUrl: 'wss://speech.talktopc.com/ws/conv?signed_token=...', // Required: signed URL with allowOverride=true
+  
+  // Override agent settings dynamically
+  agentSettingsOverride: {
+    // Core settings
+    prompt: "You are a friendly customer service assistant",
+    temperature: 0.8,
+    maxTokens: 200,
+    
+    // Voice settings
+    voiceId: "F2",
+    voiceSpeed: 1.2,
+    
+    // Behavior
+    firstMessage: "Hello! How can I help you today?",
+    disableInterruptions: false,
+    maxCallDuration: 600,
+    
+    // Language
+    language: "en",
+    autoDetectLanguage: false
+  }
+});</code></pre>
+          <p>See the <a href="#agent-override">Agent Settings Override</a> section for complete documentation of all available override settings.</p>
+
           <h3>RTL (Right-to-Left) Support</h3>
           <pre><code>// For Hebrew, Arabic, etc.
 const widget = new TTPAgentSDK.TTPChatWidget({
@@ -1182,6 +1695,18 @@ document.getElementById('myButton').onclick = () => {
                   <td>{}</td>
                   <td>Custom variables to pass to agent</td>
                 </tr>
+                <tr>
+                  <td><code>signedUrl</code></td>
+                  <td>string | function</td>
+                  <td>null</td>
+                  <td>Signed URL for secure authentication (string or async function that returns URL)</td>
+                </tr>
+                <tr>
+                  <td><code>agentSettingsOverride</code></td>
+                  <td>object</td>
+                  <td>null</td>
+                  <td>Override agent settings dynamically (requires signed URL with allowOverride=true). See <a href="#agent-override">Agent Settings Override</a> for details.</td>
+                </tr>
                 <tr>
                   <td><code>customStyles</code></td>
                   <td>string</td>
@@ -1867,16 +2392,10 @@ document.getElementById('myButton').onclick = () => {
               </thead>
               <tbody>
                 <tr>
-                  <td><code>websocketUrl</code></td>
-                  <td>string</td>
-                  <td>Auto-detected</td>
-                  <td>Custom WebSocket URL for text chat</td>
-                </tr>
-                <tr>
-                  <td><code>voice.websocketUrl</code></td>
+                  <td><code>signedUrl</code></td>
                   <td>string</td>
-                  <td>Auto-detected</td>
-                  <td>Custom WebSocket URL for voice chat</td>
+                  <td>Optional</td>
+                  <td>Signed WebSocket URL for secure authentication (for voice). If not provided, URL is constructed from agentId/appId.</td>
                 </tr>
                 <tr>
                   <td><code>demo</code></td>
@@ -2005,7 +2524,7 @@ class VoiceAssistant {
 
     // Step 2: Create SDK
     this.sdk = new VoiceSDK({
-      websocketUrl: signedUrl,
+      signedUrl: signedUrl,  // signedUrl from backend
       appId: 'your_app_id',
       agentId: agentId,
       agentSettingsOverride: overrides
@@ -2138,7 +2657,7 @@ function VoiceChat() {
 
       // Create SDK
       const sdk = new VoiceSDK({
-        websocketUrl: signedUrl,
+        signedUrl: signedUrl,  // signedUrl from backend
         appId: 'your_app_id',
         agentId: 'agent_123',
         agentSettingsOverride: {
@@ -2240,7 +2759,7 @@ function App() {
 
   return (
     &lt;VoiceButton
-      websocketUrl={signedUrl}
+      signedUrl={signedUrl}  {/* signedUrl from backend */}
       appId="your_app_id"
       agentId="agent_123"
       agentSettingsOverride={{
@@ -2266,7 +2785,7 @@ function App() {
             </thead>
             <tbody>
               <tr>
-                <td><code>websocketUrl</code></td>
+                <td><code>signedUrl</code></td>
                 <td>string</td>
                 <td>Yes</td>
                 <td>Signed WebSocket URL</td>
@@ -2412,7 +2931,7 @@ function App() {
             </thead>
             <tbody>
               <tr>
-                <td><code>websocketUrl</code></td>
+                <td><code>signedUrl</code></td>
                 <td>string</td>
                 <td>Yes</td>
                 <td>Signed WebSocket URL from your backend</td>
@@ -2534,7 +3053,7 @@ function App() {
 
           <h4>Example: Custom Audio Format</h4>
           <pre><code>const voiceSDK = new VoiceSDK({
-  websocketUrl: signedUrl,
+  signedUrl: signedUrl,  // signedUrl from backend
   appId: 'your_app_id',
   agentId: 'agent_123',
   
@@ -3404,6 +3923,20 @@ app.post('/api/generate-speech', async (req, res) => {
     &lt;/dependency&gt;
 &lt;/dependencies&gt;</code></pre>
 
+          <div class="warning-box">
+            <strong>⚠️ GitHub Packages Authentication:</strong>
+            <p>You'll need to authenticate with GitHub Packages. Add credentials to your <code>~/.m2/settings.xml</code>:</p>
+            <pre><code>&lt;settings&gt;
+    &lt;servers&gt;
+        &lt;server&gt;
+            &lt;id&gt;github&lt;/id&gt;
+            &lt;username&gt;YOUR_GITHUB_USERNAME&lt;/username&gt;
+            &lt;password&gt;YOUR_GITHUB_TOKEN&lt;/password&gt;
+        &lt;/server&gt;
+    &lt;/servers&gt;
+&lt;/settings&gt;</code></pre>
+          </div>
+
           <h3>Gradle</h3>
           <pre><code>repositories {
     maven {
@@ -3429,6 +3962,7 @@ String apiKey = System.getenv("TALKTOPC_API_KEY");
 
 VoiceSDK sdk = VoiceSDK.builder()
     .apiKey(apiKey)
+    .baseUrl("https://api.talktopc.com")  // Optional
     .build();</code></pre>
 
           <h3>2. Simple TTS (Blocking)</h3>
@@ -3858,4 +4392,3 @@ Files.write(Paths.get("output.wav"), response.getAudio());</code></pre>
 </html>
 
 
-<!-- Cloudflare Pages rebuild trigger -->