ttp-agent-sdk 2.34.14 → 2.35.0

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.18</p>
+            <p class="version" style="margin: 0;">v2.34.9</p>
           </div>
         </div>
       </div>
@@ -157,8 +157,8 @@
               <div class="feature-compact-item">
                 <span class="feature-compact-icon">🔒</span>
                 <div>
-                  <strong>Secure Authentication</strong>
-                  <p>Backend-to-backend signed link authentication with JWT and TTL-based expiration</p>
+                  <strong>Simple Authentication</strong>
+                  <p>Direct connection using agentId and appId with domain whitelist access control</p>
                 </div>
               </div>
               <div class="feature-compact-item">
@@ -228,38 +228,14 @@ const sdk = new window.TTPAgentSDK.VoiceSDK(config);</code></pre>
 
           <div class="step-card">
             <div class="step-number">1</div>
-            <div class="step-content">
-              <h3>Get a Signed URL</h3>
-              <div class="warning-box">
-                <strong>🔒 Backend-to-Backend:</strong> Your frontend requests from YOUR backend, which then communicates with TTP backend. Never expose your API key to the frontend!
-              </div>
-              <p><strong>Frontend → Your Backend:</strong></p>
-              <pre><code>const response = await fetch('/api/get-voice-session', {
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    agentId: 'agent_123'
-  })
-});
-
-const { signedUrl } = await response.json();</code></pre>
-              <p><strong>Your Backend → TTP Backend:</strong> (See Authentication section for details)</p>
-            </div>
-          </div>
-
-          <div class="step-card">
-            <div class="step-number">2</div>
             <div class="step-content">
               <h3>Initialize the SDK</h3>
-              <p>Create a VoiceSDK instance with the signed URL:</p>
+              <p>Create a VoiceSDK instance with your agent ID and app ID:</p>
               <pre><code>import { VoiceSDK } from 'ttp-agent-sdk';
 
 const voiceSDK = new VoiceSDK({
-  signedUrl: signedUrl,  // signedUrl from step 1
-  appId: 'your_app_id',     // Your application ID
   agentId: 'agent_123',     // The AI agent to connect to
+  appId: 'your_app_id',     // Your application ID
   
   // Optional: Configure audio formats (v2 protocol)
   outputContainer: 'raw',      // 'raw' or 'wav'
@@ -287,7 +263,7 @@ voiceSDK.on('message', (msg) => {
           </div>
 
           <div class="step-card">
-            <div class="step-number">3</div>
+            <div class="step-number">2</div>
             <div class="step-content">
               <h3>Connect & Start Recording</h3>
               <p>Connect to the agent and start capturing audio:</p>
@@ -306,203 +282,26 @@ await voiceSDK.stopRecording();</code></pre>
         <!-- Authentication -->
         <section id="authentication" class="doc-section">
           <h1>Authentication</h1>
-          <p>TTP Agent SDK uses signed WebSocket URLs for secure authentication.</p>
+          <p>The SDK connects directly using <code>agentId</code> and <code>appId</code>. No server-side authentication step is needed. Access control is managed via domain whitelist in your agent's admin panel.</p>
 
+          <h2>How It Works</h2>
           <div class="info-box">
-            <strong>🔒 Security First:</strong> All connections require signed URLs obtained from your backend, which authenticates with the TTP backend using an API key.
-          </div>
-
-          <h2>Authentication Flow</h2>
-          <div class="warning-box">
-            <strong>🔐 Critical Security Note:</strong> The signed URL generation happens <strong>Backend-to-Backend</strong>. Your frontend NEVER directly contacts TTP backend. This protects your API key!
-          </div>
-          <div class="flow-diagram">
-            <div class="flow-step">
-              <div class="flow-box" style="background: linear-gradient(135deg, #e0f2fe 0%, #bfdbfe 100%);">
-                <strong>1. 🖥️ Your Frontend</strong>
-                <p>User clicks "Start Voice Chat"</p>
-              </div>
-              <div class="flow-arrow">↓</div>
-              <div class="flow-box" style="background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%);">
-                <strong>2. 🔧 Your Backend</strong>
-                <p>Receives: POST /api/get-voice-session</p>
-              </div>
-              <div class="flow-arrow">↓ 🔒 Backend-to-Backend (API Key)</div>
-              <div class="flow-box" style="background: linear-gradient(135deg, #e9d5ff 0%, #d8b4fe 100%);">
-                <strong>3. 🏢 TTP Backend</strong>
-                <p>Validates API key & generates signed JWT</p>
-              </div>
-              <div class="flow-arrow">↑ Returns signed URL</div>
-              <div class="flow-box" style="background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%);">
-                <strong>4. 🔧 Your Backend</strong>
-                <p>Forwards signed URL to frontend</p>
-              </div>
-              <div class="flow-arrow">↓</div>
-              <div class="flow-box" style="background: linear-gradient(135deg, #e0f2fe 0%, #bfdbfe 100%);">
-                <strong>5. 🖥️ Your Frontend</strong>
-                <p>Uses SDK with signed URL (WebSocket)</p>
-              </div>
-            </div>
-          </div>
-
-          <h2>Backend Implementation (Backend-to-Backend)</h2>
-          <p><strong>Your backend acts as a secure proxy between your frontend and TTP backend:</strong></p>
-          
-          <div class="info-box">
-            <strong>💡 Architecture:</strong> Frontend → Your Backend → TTP Backend → Your Backend → Frontend
+            <strong>💡 Simple Setup:</strong> Just provide your <code>agentId</code> and <code>appId</code> in the SDK configuration. The SDK connects directly to the TTP backend via WebSocket.
           </div>
           
-          <div class="success-box">
-            <strong>⏱️ Configurable TTL:</strong> You can specify <code>expirationMs</code> (in milliseconds) to control how long the signed URL is valid. Default is 1 hour (3600000ms) if not specified.
-            <br><br>
-            <strong>Examples:</strong>
-            <ul style="margin-top: 10px; margin-left: 20px;">
-              <li>5 minutes: <code>300000</code></li>
-              <li>1 hour (default): <code>3600000</code></li>
-              <li>24 hours: <code>86400000</code></li>
-            </ul>
-          </div>
-          
-          <pre><code>// Example: Node.js/Express
-// This endpoint is called by YOUR FRONTEND
-app.post('/api/get-voice-session', async (req, res) => {
-  const { agentId } = req.body;
-  
-  // 1️⃣ Authenticate YOUR user (your auth logic)
-  if (!req.user) {
-    return res.status(401).json({ error: 'Unauthorized' });
-  }
-  
-  // 2️⃣ Backend-to-Backend: Call TTP Backend with YOUR API Key
-  // ⚠️ This happens SERVER-SIDE only - API key never exposed to frontend
-  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}`  // 🔒 Secret - never in frontend!
-    },
-    body: JSON.stringify({
-      agentId: agentId,
-      appId: process.env.TTP_APP_ID,
-      expirationMs: 3600000,  // Optional: Token TTL in milliseconds (default: 1 hour)
-      allowOverride: true     // Optional: Enable agent settings override (default: false)
-    })
-  });
-  
-  const { signedLink } = await response.json();
-  
-  // 3️⃣ Return signed URL to YOUR frontend
-  res.json({ signedUrl: signedLink });
+          <pre><code>const voiceSDK = new VoiceSDK({
+  agentId: 'agent_123',     // Your AI agent ID
+  appId: 'your_app_id'      // Your application ID
 });</code></pre>
 
-          <div class="warning-box">
-            <strong>⚠️ Never expose your API key:</strong> The API key should only be used on your backend server, never in frontend code.
+          <h2>Domain Whitelist</h2>
+          <p>To control which websites can use your agent, configure a domain whitelist in your agent's admin panel. Only requests originating from whitelisted domains will be accepted.</p>
+          
+          <div class="info-box">
+            <strong>💡 Tip:</strong> During development, you can add <code>localhost</code> to the domain whitelist. Remove it before deploying to production.
           </div>
 
-          <h2>Response Format</h2>
-          <p>The signed URL endpoint returns the following response:</p>
-          <pre><code>{
-  "signedLink": "wss://speech.talktopc.com/ws/conv?signed_token=eyJ...",
-  "agentId": "agent_123",
-  "userId": "user_789",
-  "appId": "your_app_id",
-  "expiresAt": "2025-11-11T21:00:00.000+00:00",
-  "expiresIn": 3600000,
-  "generatedAt": "2025-11-11T20:00:00.000+00:00",
-  "availableCredits": 150.5,
-  "authenticationStatus": "SUCCESS"
-}</code></pre>
-
-          <table class="properties-table">
-            <thead>
-              <tr>
-                <th>Property</th>
-                <th>Type</th>
-                <th>Description</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <td><code>signedLink</code></td>
-                <td>string</td>
-                <td>The WebSocket URL with signed JWT token</td>
-              </tr>
-              <tr>
-                <td><code>agentId</code></td>
-                <td>string</td>
-                <td>The AI agent identifier</td>
-              </tr>
-              <tr>
-                <td><code>userId</code></td>
-                <td>string</td>
-                <td>Your user's identifier (ttpId)</td>
-              </tr>
-              <tr>
-                <td><code>appId</code></td>
-                <td>string</td>
-                <td>Your application identifier</td>
-              </tr>
-              <tr>
-                <td><code>expiresAt</code></td>
-                <td>Date</td>
-                <td>When the signed URL expires (ISO 8601 format)</td>
-              </tr>
-              <tr>
-                <td><code>expiresIn</code></td>
-                <td>number</td>
-                <td>Token validity duration in milliseconds</td>
-              </tr>
-              <tr>
-                <td><code>generatedAt</code></td>
-                <td>Date</td>
-                <td>When the signed URL was generated (ISO 8601 format)</td>
-              </tr>
-              <tr>
-                <td><code>availableCredits</code></td>
-                <td>number</td>
-                <td>User's remaining credit balance</td>
-              </tr>
-              <tr>
-                <td><code>authenticationStatus</code></td>
-                <td>string</td>
-                <td>Always "SUCCESS" for successful requests</td>
-              </tr>
-            </tbody>
-          </table>
-
-          <h2>JWT Token Properties</h2>
-          <table class="properties-table">
-            <thead>
-              <tr>
-                <th>Property</th>
-                <th>Description</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <td><code>agentId</code></td>
-                <td>The AI agent identifier</td>
-              </tr>
-              <tr>
-                <td><code>userId</code></td>
-                <td>Your user's identifier</td>
-              </tr>
-              <tr>
-                <td><code>appId</code></td>
-                <td>Your application identifier</td>
-              </tr>
-              <tr>
-                <td><code>allowOverride</code></td>
-                <td>Permission flag for agent settings override (optional)</td>
-              </tr>
-              <tr>
-                <td><code>exp</code></td>
-                <td>Token expiration time (TTL - configurable via <code>expirationMs</code>, defaults to 1 hour)</td>
-              </tr>
-            </tbody>
-          </table>
-          
-          <h2>Request Parameters</h2>
+          <h2>Configuration Parameters</h2>
           <table class="properties-table">
             <thead>
               <tr>
@@ -525,18 +324,6 @@ app.post('/api/get-voice-session', async (req, res) => {
                 <td>Yes</td>
                 <td>Your application identifier</td>
               </tr>
-              <tr>
-                <td><code>expirationMs</code></td>
-                <td>number</td>
-                <td>No</td>
-                <td>Token TTL in milliseconds (default: 3600000 = 1 hour)</td>
-              </tr>
-              <tr>
-                <td><code>allowOverride</code></td>
-                <td>boolean</td>
-                <td>No</td>
-                <td>Enable agent settings override permission (default: false)</td>
-              </tr>
             </tbody>
           </table>
         </section>
@@ -548,25 +335,21 @@ app.post('/api/get-voice-session', async (req, res) => {
           <p>Dynamically customize agent behavior, voice, and personality on a per-session basis.</p>
 
           <div class="info-box">
-            <strong>🔒 Security:</strong> Agent overrides are only available with signed link authentication where <code>allowOverride: true</code> is granted by your backend.
+            <strong>💡 Access Control:</strong> Agent settings override is available when the agent has domain whitelist configured in the admin panel. No additional authentication step is required.
           </div>
 
           <h2>How It Works</h2>
-          <div class="info-box">
-            <strong>🔐 Backend-to-Backend First:</strong> The signed URL with override permission is obtained via backend-to-backend communication before your frontend can use it.
-          </div>
           <ol class="numbered-list">
-            <li><strong>Backend-to-Backend:</strong> Your backend requests a signed URL from TTP backend with <code>allowOverride: true</code></li>
-            <li><strong>Backend → Frontend:</strong> Your backend returns the signed URL to your frontend</li>
-            <li><strong>Frontend:</strong> Your frontend uses the SDK with the signed URL + custom agent settings</li>
-            <li><strong>TTP Backend:</strong> Validates the JWT signature and applies your overrides if permission granted</li>
+            <li><strong>Configure:</strong> Set up a domain whitelist for your agent in the admin panel</li>
+            <li><strong>Initialize:</strong> Pass <code>agentSettingsOverride</code> in the SDK configuration</li>
+            <li><strong>Connect:</strong> The SDK sends overrides in the hello message</li>
+            <li><strong>TTP Backend:</strong> Validates the domain and applies your overrides</li>
           </ol>
 
           <h2>Example</h2>
           <pre><code>const voiceSDK = new VoiceSDK({
-  signedUrl: signedUrl,  // signedUrl from your backend
-  appId: 'your_app_id',     // Your application ID
   agentId: 'agent_123',     // The AI agent to connect to
+  appId: 'your_app_id',     // Your application ID
   
   // Override agent settings
   agentSettingsOverride: {
@@ -649,16 +432,7 @@ app.post('/api/get-voice-session', async (req, res) => {
           <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',
   
@@ -759,16 +533,7 @@ await voiceSDK.connect();</code></pre>
           <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',
   
@@ -1189,9 +954,8 @@ voiceSDK.on('domainError', (error) => {
 
           <h2>Example: High-Quality Audio</h2>
           <pre><code>const voiceSDK = new VoiceSDK({
-  signedUrl: signedUrl,  // signedUrl from backend
-  appId: 'your_app_id',
   agentId: 'agent_123',
+  appId: 'your_app_id',
   
   // Request high-quality audio
   outputContainer: 'raw',        // Raw PCM for lower latency
@@ -1211,9 +975,8 @@ voiceSDK.on('formatNegotiated', (format) => {
 
           <h2>Example: Bandwidth-Optimized Audio</h2>
           <pre><code>const voiceSDK = new VoiceSDK({
-  signedUrl: signedUrl,  // signedUrl from backend
-  appId: 'your_app_id',
   agentId: 'agent_123',
+  appId: 'your_app_id',
   
   // Request compressed, low-bandwidth audio
   outputContainer: 'raw',
@@ -1293,10 +1056,7 @@ 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)
+  // Optional - Agent Settings Override (available when domain whitelist is configured)
   agentSettingsOverride: {
     prompt: "You are a helpful customer service assistant.",
     temperature: 0.8,
@@ -1321,105 +1081,30 @@ 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.
+          <h2>Access Control</h2>
+          <div class="info-box">
+            <strong>💡 Domain Whitelist:</strong> For production applications, configure a domain whitelist in your agent's admin panel to control which websites can connect to your agent.
           </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>
+          <p>The widget connects directly using <code>agentId</code> and <code>appId</code>. No backend authentication step is needed:</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');
+          <pre><code>const widget = new TTPAgentSDK.TTPChatWidget({
+  agentId: 'agent_123',
+  appId: 'your_app_id',
+  variables: {
+    userName: 'John Doe',
+    page: 'homepage'
   }
-  
-  // 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>
+});</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>
+              <li>The widget only needs <code>agentId</code> and <code>appId</code> to connect</li>
+              <li>Access control is managed via domain whitelist in the admin panel</li>
+              <li>Optionally pass <code>websocketUrl</code> to override the default WebSocket endpoint</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>
           
@@ -1466,13 +1151,12 @@ app.post('/api/get-voice-session', async (req, res) => {
 
           <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.
+            <strong>💡 Access Control:</strong> Agent settings override is available when the agent has domain whitelist configured in the admin panel.
           </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: {
@@ -1696,16 +1380,16 @@ document.getElementById('myButton').onclick = () => {
                   <td>Custom variables to pass to agent</td>
                 </tr>
                 <tr>
-                  <td><code>signedUrl</code></td>
-                  <td>string | function</td>
+                  <td><code>websocketUrl</code></td>
+                  <td>string</td>
                   <td>null</td>
-                  <td>Signed URL for secure authentication (string or async function that returns URL)</td>
+                  <td>Optional custom WebSocket base URL (defaults to wss://speech.talktopc.com/ws/conv)</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>
+                  <td>Override agent settings dynamically. See <a href="#agent-override">Agent Settings Override</a> for details.</td>
                 </tr>
                 <tr>
                   <td><code>customStyles</code></td>
@@ -1713,10 +1397,98 @@ document.getElementById('myButton').onclick = () => {
                   <td>''</td>
                   <td>Custom CSS to inject</td>
                 </tr>
+                <tr>
+                  <td><code>useShadowDOM</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>Enable Shadow DOM for CSS isolation. Set to <code>false</code> for Shopify compatibility. See <a href="#shadow-dom-config">Shadow DOM Configuration</a> below.</td>
+                </tr>
               </tbody>
             </table>
           </details>
 
+          <div id="shadow-dom-config" class="info-box" style="margin: 20px 0; padding: 20px; background: #f8f9fa; border-left: 4px solid #7C3AED;">
+            <h3 style="margin-top: 0;">Shadow DOM Configuration (<code>useShadowDOM</code>)</h3>
+            
+            <p><strong>What is Shadow DOM?</strong></p>
+            <p>Shadow DOM is a web standard that provides CSS isolation by creating a separate DOM tree that doesn't inherit styles from the parent page. This prevents theme CSS from interfering with the widget's appearance.</p>
+            
+            <p><strong>When to Use Shadow DOM:</strong></p>
+            <ul style="margin: 10px 0 10px 20px;">
+              <li><strong>✅ WordPress:</strong> Use Shadow DOM (<code>useShadowDOM: true</code> or omit - defaults to <code>true</code>)</li>
+              <li><strong>✅ Most platforms:</strong> Shadow DOM works well on most websites and platforms</li>
+              <li><strong>❌ Shopify:</strong> Disable Shadow DOM (<code>useShadowDOM: false</code>) due to rendering issues</li>
+            </ul>
+            
+            <p><strong>Why We Need This Option:</strong></p>
+            <p>While Shadow DOM provides excellent CSS isolation, some platforms (notably Shopify) have rendering issues where Shadow DOM elements render with 0x0 dimensions, making the widget invisible. By setting <code>useShadowDOM: false</code>, the widget uses regular DOM with targeted CSS resets instead, ensuring visibility while still protecting against most theme conflicts.</p>
+            
+            <p><strong>Platform-Specific Recommendations:</strong></p>
+            <table class="properties-table" style="margin: 15px 0;">
+              <thead>
+                <tr>
+                  <th>Platform</th>
+                  <th>Recommended Setting</th>
+                  <th>Reason</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td><strong>WordPress</strong></td>
+                  <td><code>useShadowDOM: true</code> (default)</td>
+                  <td>Shadow DOM works perfectly and provides better CSS isolation</td>
+                </tr>
+                <tr>
+                  <td><strong>Shopify</strong></td>
+                  <td><code>useShadowDOM: false</code></td>
+                  <td>Shadow DOM elements render with 0x0 dimensions, making widget invisible</td>
+                </tr>
+                <tr>
+                  <td><strong>Wix</strong></td>
+                  <td><code>useShadowDOM: true</code> (default)</td>
+                  <td>Shadow DOM works well on Wix</td>
+                </tr>
+                <tr>
+                  <td><strong>Custom Websites</strong></td>
+                  <td><code>useShadowDOM: true</code> (default)</td>
+                  <td>Use Shadow DOM unless you experience rendering issues</td>
+                </tr>
+              </tbody>
+            </table>
+            
+            <p><strong>Example Usage:</strong></p>
+            <pre><code class="language-javascript">// WordPress (default - Shadow DOM enabled)
+const widget = new TTPChatWidget({
+  agentId: 'your-agent-id',
+  // useShadowDOM defaults to true, so widget is isolated from theme CSS
+});
+
+// Shopify (disable Shadow DOM)
+const widget = new TTPChatWidget({
+  agentId: 'your-agent-id',
+  useShadowDOM: false  // Required for Shopify compatibility
+});
+
+// If widget is invisible, try disabling Shadow DOM
+const widget = new TTPChatWidget({
+  agentId: 'your-agent-id',
+  useShadowDOM: false  // Fallback if Shadow DOM causes rendering issues
+});</code></pre>
+            
+            <p><strong>How It Works:</strong></p>
+            <ul style="margin: 10px 0 10px 20px;">
+              <li><strong>With Shadow DOM (<code>useShadowDOM: true</code>):</strong> Widget is rendered inside a Shadow DOM tree, completely isolated from page CSS. Styles are injected into the shadow root.</li>
+              <li><strong>Without Shadow DOM (<code>useShadowDOM: false</code>):</strong> Widget is rendered in regular DOM. Styles are injected into the document <code>&lt;head&gt;</code> with high-specificity selectors to prevent theme CSS conflicts. Targeted CSS resets protect against common theme issues while preserving widget functionality.</li>
+            </ul>
+            
+            <p><strong>⚠️ Important Notes:</strong></p>
+            <ul style="margin: 10px 0 10px 20px;">
+              <li>When <code>useShadowDOM: false</code>, the widget uses targeted CSS resets instead of aggressive resets to preserve internal widget styles</li>
+              <li>If you experience layout issues with <code>useShadowDOM: false</code>, check if your theme's CSS is overriding widget styles - you may need to add more specific CSS rules</li>
+              <li>The widget automatically handles CSS injection differently based on this setting - no additional configuration needed</li>
+            </ul>
+          </div>
+
           <details>
             <summary><strong>Positioning</strong></summary>
             <table class="properties-table">
@@ -2099,6 +1871,24 @@ document.getElementById('myButton').onclick = () => {
                   <td>'#64748b'</td>
                   <td>Status subtitle text color</td>
                 </tr>
+                <tr>
+                  <td><code>voice.startCallTitle</code></td>
+                  <td>string</td>
+                  <td>null</td>
+                  <td>Custom text for "Click to Start Call" title (bypasses translations)</td>
+                </tr>
+                <tr>
+                  <td><code>voice.startCallSubtitle</code></td>
+                  <td>string</td>
+                  <td>null</td>
+                  <td>Custom text for "Real-time voice conversation" subtitle (bypasses translations)</td>
+                </tr>
+                <tr>
+                  <td><code>voice.startCallButtonText</code></td>
+                  <td>string</td>
+                  <td>null</td>
+                  <td>Custom text for "Start Call" button (bypasses translations)</td>
+                </tr>
                 <tr>
                   <td><code>voice.startCallButtonColor</code></td>
                   <td>string</td>
@@ -2392,10 +2182,10 @@ document.getElementById('myButton').onclick = () => {
               </thead>
               <tbody>
                 <tr>
-                  <td><code>signedUrl</code></td>
+                  <td><code>websocketUrl</code></td>
                   <td>string</td>
                   <td>Optional</td>
-                  <td>Signed WebSocket URL for secure authentication (for voice). If not provided, URL is constructed from agentId/appId.</td>
+                  <td>Custom WebSocket base URL (defaults to wss://speech.talktopc.com/ws/conv). If not provided, URL is constructed from agentId/appId.</td>
                 </tr>
                 <tr>
                   <td><code>demo</code></td>
@@ -2519,14 +2309,9 @@ class VoiceAssistant {
   }
 
   async initialize(agentId, overrides = {}) {
-    // Step 1: Get signed URL
-    const signedUrl = await this.getSignedUrl(agentId);
-
-    // Step 2: Create SDK
     this.sdk = new VoiceSDK({
-      signedUrl: signedUrl,  // signedUrl from backend
-      appId: 'your_app_id',
       agentId: agentId,
+      appId: 'your_app_id',
       agentSettingsOverride: overrides
     });
 
@@ -2570,21 +2355,6 @@ class VoiceAssistant {
     });
   }
 
-  async getSignedUrl(agentId) {
-    const response = await fetch('/api/get-voice-session', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify({
-        agentId: agentId
-      })
-    });
-    
-    const { signedUrl } = await response.json();
-    return signedUrl;
-  }
-
   async toggleRecording() {
     if (!this.isConnected) return;
 
@@ -2642,24 +2412,9 @@ function VoiceChat() {
   // Initialize SDK
   useEffect(() => {
     async function initSDK() {
-      // Get signed URL
-      const response = await fetch('/api/get-voice-session', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-          agentId: 'agent_123'
-        })
-      });
-      
-      const { signedUrl } = await response.json();
-
-      // Create SDK
       const sdk = new VoiceSDK({
-        signedUrl: signedUrl,  // signedUrl from backend
-        appId: 'your_app_id',
         agentId: 'agent_123',
+        appId: 'your_app_id',
         agentSettingsOverride: {
           language: 'es',
           temperature: 0.9
@@ -2730,38 +2485,14 @@ export default VoiceChat;</code></pre>
           <pre><code>import { VoiceButton } from 'ttp-agent-sdk/react';</code></pre>
 
           <h2>Basic Usage</h2>
-          <pre><code>import React, { useState, useEffect } from 'react';
+          <pre><code>import React from 'react';
 import { VoiceButton } from 'ttp-agent-sdk/react';
 
 function App() {
-  const [signedUrl, setSignedUrl] = useState(null);
-
-  useEffect(() => {
-    async function fetchSignedUrl() {
-      const response = await fetch('/api/get-voice-session', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-          agentId: 'agent_123'
-        })
-      });
-      
-      const { signedUrl } = await response.json();
-      setSignedUrl(signedUrl);
-    }
-    
-    fetchSignedUrl();
-  }, []);
-
-  if (!signedUrl) return &lt;div&gt;Loading...&lt;/div&gt;;
-
   return (
     &lt;VoiceButton
-      signedUrl={signedUrl}  {/* signedUrl from backend */}
-      appId="your_app_id"
       agentId="agent_123"
+      appId="your_app_id"
       agentSettingsOverride={{
         language: 'es',
         temperature: 0.9
@@ -2785,10 +2516,10 @@ function App() {
             </thead>
             <tbody>
               <tr>
-                <td><code>signedUrl</code></td>
+                <td><code>agentId</code></td>
                 <td>string</td>
                 <td>Yes</td>
-                <td>Signed WebSocket URL</td>
+                <td>The AI agent identifier</td>
               </tr>
               <tr>
                 <td><code>appId</code></td>
@@ -2797,10 +2528,10 @@ function App() {
                 <td>Your application ID</td>
               </tr>
               <tr>
-                <td><code>agentId</code></td>
+                <td><code>websocketUrl</code></td>
                 <td>string</td>
-                <td>Yes</td>
-                <td>The AI agent identifier</td>
+                <td>No</td>
+                <td>Optional custom WebSocket base URL (defaults to wss://speech.talktopc.com/ws/conv)</td>
               </tr>
               <tr>
                 <td><code>agentSettingsOverride</code></td>
@@ -2931,10 +2662,10 @@ function App() {
             </thead>
             <tbody>
               <tr>
-                <td><code>signedUrl</code></td>
+                <td><code>agentId</code></td>
                 <td>string</td>
                 <td>Yes</td>
-                <td>Signed WebSocket URL from your backend</td>
+                <td>The AI agent identifier to connect to</td>
               </tr>
               <tr>
                 <td><code>appId</code></td>
@@ -2943,10 +2674,10 @@ function App() {
                 <td>Your application identifier</td>
               </tr>
               <tr>
-                <td><code>agentId</code></td>
+                <td><code>websocketUrl</code></td>
                 <td>string</td>
-                <td>Yes</td>
-                <td>The AI agent identifier to connect to</td>
+                <td>No</td>
+                <td>Optional custom WebSocket base URL (defaults to wss://speech.talktopc.com/ws/conv)</td>
               </tr>
               <tr>
                 <td><code>agentSettingsOverride</code></td>
@@ -3053,9 +2784,8 @@ function App() {
 
           <h4>Example: Custom Audio Format</h4>
           <pre><code>const voiceSDK = new VoiceSDK({
-  signedUrl: signedUrl,  // signedUrl from backend
-  appId: 'your_app_id',
   agentId: 'agent_123',
+  appId: 'your_app_id',
   
   // Input format (what we send to server)
   sampleRate: 16000,