ttp-agent-sdk 2.45.7 → 2.45.12

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.34.9</p>
+            <p class="version" style="margin: 0;">v2.45.11</p>
           </div>
         </div>
       </div>
@@ -46,6 +46,7 @@
             <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>
+            <li><a href="#server-driven-disclaimer" class="nav-link">Server-driven disclaimer (voice)</a></li>
           </ul>
         </div>
 
@@ -56,6 +57,9 @@
             <li><a href="#vanilla-js" class="nav-link">Vanilla JavaScript</a></li>
             <li><a href="#react" class="nav-link">React Integration</a></li>
             <li><a href="#voice-button" class="nav-link">VoiceButton Component</a></li>
+            <li><a href="#fly-to-cart" class="nav-link">Fly-to-Cart Animation</a></li>
+            <li><a href="#ecommerce-cart-flow" class="nav-link">E-commerce cart flows</a></li>
+            <li><a href="#widget-flavors" class="nav-link">Widget Flavors</a></li>
             <li><a href="#client-script-tools" class="nav-link">Client-Script Tools</a></li>
             <li><a href="#chain-tools" class="nav-link">Chain Tools</a></li>
           </ul>
@@ -242,7 +246,7 @@ const voiceSDK = new VoiceSDK({
   // Optional: Configure audio formats (v2 protocol)
   outputContainer: 'raw',      // 'raw' or 'wav'
   outputEncoding: 'pcm',       // 'pcm', 'pcmu', 'pcma'
-  outputSampleRate: 44100,     // Higher quality audio
+  outputSampleRate: 24000,     // Typical server/TTS output (default)
   protocolVersion: 2           // Use v2 protocol for format negotiation
 });
 
@@ -268,7 +272,7 @@ voiceSDK.on('message', (msg) => {
             <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>
+              <p>Connect to the agent and start capturing audio. If your agent uses a <a href="#server-driven-disclaimer">server-driven disclaimer</a>, listen for <code>disclaimersRequired</code>, call <code>sendDisclaimerAck(true)</code> after the user accepts, then call <code>startRecording()</code>.</p>
               <pre><code>// Connect
 await voiceSDK.connect();
 
@@ -446,12 +450,12 @@ const voiceSDK = new VoiceSDK_v2({
   },
   
   // Audio format configuration
-  sampleRate: 44100,
+  sampleRate: 16000,
   channels: 1,
   bitDepth: 16,
   outputContainer: 'raw',
   outputEncoding: 'pcm',
-  outputSampleRate: 44100,
+  outputSampleRate: 24000,
   outputChannels: 1,
   outputBitDepth: 16,
   outputFrameDurationMs: 600
@@ -471,13 +475,13 @@ await voiceSDK.connect();</code></pre>
   },
   "inputFormat": {
     "encoding": "pcm",
-    "sampleRate": 44100,
+    "sampleRate": 16000,
     "channels": 1,
     "bitDepth": 16
   },
   "requestedOutputFormat": {
     "encoding": "pcm",
-    "sampleRate": 44100,
+    "sampleRate": 24000,
     "channels": 1,
     "bitDepth": 16,
     "container": "raw"
@@ -564,13 +568,13 @@ ws.onopen = () => {
     },
     inputFormat: {
       encoding: 'pcm',
-      sampleRate: 44100,
+      sampleRate: 16000,
       channels: 1,
       bitDepth: 16
     },
     requestedOutputFormat: {
       encoding: 'pcm',
-      sampleRate: 44100,
+      sampleRate: 24000,
       channels: 1,
       bitDepth: 16,
       container: 'raw'
@@ -596,13 +600,13 @@ def on_open(ws):
         },
         "inputFormat": {
             "encoding": "pcm",
-            "sampleRate": 44100,
+            "sampleRate": 16000,
             "channels": 1,
             "bitDepth": 16
         },
         "requestedOutputFormat": {
             "encoding": "pcm",
-            "sampleRate": 44100,
+            "sampleRate": 24000,
             "channels": 1,
             "bitDepth": 16,
             "container": "raw"
@@ -623,7 +627,7 @@ ws.run_forever()</code></pre>
 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>
+{"t":"hello","v":2,"variables":{"USER_NAME":"John","ACCOUNT_TYPE":"premium"},"inputFormat":{"encoding":"pcm","sampleRate":16000,"channels":1,"bitDepth":16},"requestedOutputFormat":{"encoding":"pcm","sampleRate":24000,"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>
@@ -824,6 +828,22 @@ voiceSDK.on('audioData', (audioData) => {
   // Raw audio data (Uint8Array)
 });</code></pre>
 
+          <h3>Pause Events</h3>
+          <pre><code>// Call paused (server acknowledged)
+voiceSDK.on('callPaused', (data) => {
+  console.log('⏸️ Call paused, timeout:', data.timeoutSeconds, 'seconds');
+});
+
+// Call resumed (server acknowledged, STT ready)
+voiceSDK.on('callResumed', () => {
+  console.log('▶️ Call resumed');
+});
+
+// Pause timeout (call auto-ended because pause lasted too long)
+voiceSDK.on('pauseTimeout', () => {
+  console.log('⏱️ Pause timeout — call ended');
+});</code></pre>
+
           <h3>Special Events</h3>
           <pre><code>// Barge-in (user interrupts agent)
 voiceSDK.on('bargeIn', (message) => {
@@ -844,6 +864,14 @@ voiceSDK.on('greetingStarted', () => {
 // Domain whitelist error
 voiceSDK.on('domainError', (error) => {
   console.error('Domain not whitelisted:', error.reason);
+});
+
+// Server-driven disclaimer (voice v2) — see #server-driven-disclaimer
+voiceSDK.on('disclaimersRequired', (payload) => {
+  // Show your UI, then call voiceSDK.sendDisclaimerAck(true|false)
+});
+voiceSDK.on('disclaimerRejected', ({ code, message }) => {
+  // DISCLAIMER_DECLINED, DISCLAIMER_TIMEOUT, DISCLAIMER_HASH_MISMATCH, etc.
 });</code></pre>
         </section>
 
@@ -852,6 +880,149 @@ voiceSDK.on('domainError', (error) => {
           <h1>Protocol v2 - Format Negotiation</h1>
           <p>The SDK v2 introduces format negotiation, allowing you to specify exactly what audio format you want to receive from the server.</p>
 
+          <h2 id="server-driven-disclaimer">Server-driven disclaimer (voice)</h2>
+          <p>Some deployments must show <strong>exact legal or policy copy</strong> from the server before speech recognition and the agent greeting run. The conversation server can require an explicit acknowledgement step after <code>hello_ack</code>. This applies to <strong>VoiceSDK v2</strong> (protocol version 2) and the <strong>Voice &amp; Chat Widget</strong> voice path.</p>
+
+          <h3>When the gate is active</h3>
+          <ul>
+            <li>The agent has a <strong>non-empty</strong> disclaimers list in backend storage (Redis field <code>disclaimers</code> as a JSON array of plain-text strings). An empty array <code>[]</code> means <strong>no</strong> disclaimer gate.</li>
+            <li>The session is <strong>not</strong> a resumed voice call (resume skips the gate).</li>
+          </ul>
+          <p>While the gate is open, the server:</p>
+          <ul>
+            <li>Does <strong>not</strong> open STT or play the greeting.</li>
+            <li>Rejects <code>start_continuous_mode</code> with <code>{"ok":false,"t":"error","code":"DISCLAIMER_PENDING",...}</code>.</li>
+            <li>Drops uplink <strong>binary</strong> audio (microphone data) until the gate clears.</li>
+            <li>Starts a server-side timer; if the user never acknowledges, the session is closed with <code>DISCLAIMER_TIMEOUT</code> (duration is configured on the server, typically on the order of minutes).</li>
+          </ul>
+
+          <h3 id="ios-uplink-audio">iOS Safari: microphone uplink</h3>
+          <p>Voice capture uses an <code>AudioWorklet</code>. On iPhone and iPad, WebKit often runs the capture <code>AudioContext</code> at the device hardware rate (commonly 44.1&nbsp;kHz or 48&nbsp;kHz) even when a lower rate was requested, while the server expects PCM at the input rate negotiated in <code>hello_ack</code> (typically 16&nbsp;kHz). The SDK <strong>resamples uplink PCM</strong> to that negotiated rate before sending binary frames. The recorder connects the worklet through a <strong>zero-gain node to the destination</strong> so WebKit reliably pulls the processor (graphs that dead-end at the worklet alone may not run on some builds). On mobile, after <code>getUserMedia</code> succeeds, the SDK may <strong>prime</strong> the shared recorder context while user activation is still fresh, before the WebSocket handshake and <code>hello_ack</code> finish. For embedded widgets, use <code>allow=&quot;microphone&quot;</code> on the iframe when the host page is cross-origin.</p>
+
+          <h3 id="host-csp-audioworklet">Embed sites: CSP and “Unable to load a worklet's module”</h3>
+          <p>Strict <strong>Content-Security-Policy</strong> on the parent page can block <code>audioWorklet.addModule()</code> when the processor URL points at another host (for example <code>cdn.talktopc.com</code>), which surfaces as <code>AbortError: Unable to load a worklet's module</code> and voice never reaches the server. The SDK tries that URL first, then automatically retries using the <strong>capture worklet source bundled inside the widget script</strong> and a <code>blob:</code> URL—this works on many shops without whitelisting our CDN. If both attempts fail, relax CSP (often <code>worker-src</code> / <code>script-src</code> must allow <code>blob:</code>, and/or your CDN origin for the processor), or host <code>audio-processor.js</code> on your own domain and set <code>voice.audioProcessorPath</code> to that same-origin URL.</p>
+
+          <h3><code>hello_ack</code> fields (gate active)</h3>
+          <p>When disclaimers apply, the server includes:</p>
+          <table class="properties-table">
+            <thead>
+              <tr>
+                <th>Field</th>
+                <th>Type</th>
+                <th>Description</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td><code>disclaimersRequired</code></td>
+                <td>boolean</td>
+                <td>Must be <code>true</code> when the gate is active</td>
+              </tr>
+              <tr>
+                <td><code>disclaimerTexts</code></td>
+                <td>string[]</td>
+                <td>Plain-text lines to show the user (no HTML; escape/sanitize in your UI)</td>
+              </tr>
+              <tr>
+                <td><code>disclaimersHash</code></td>
+                <td>string</td>
+                <td>SHA-256 (hex) over the canonical text list; echoed in <code>disclaimer_ack</code> for verification</td>
+              </tr>
+              <tr>
+                <td><code>disclaimerTimeoutMs</code></td>
+                <td>number</td>
+                <td>Hint for UI (countdown copy); server enforces the real timeout independently</td>
+              </tr>
+            </tbody>
+          </table>
+
+          <h3>Client message: <code>disclaimer_ack</code></h3>
+          <p>After the user accepts or declines, send:</p>
+          <pre><code class="language-json">{
+  "t": "disclaimer_ack",
+  "accepted": true,
+  "disclaimersHash": "sha256-from-hello_ack",
+  "conversationId": "optional-matches-hello_ack"
+}</code></pre>
+          <p>For decline, set <code>"accepted": false</code>. Duplicate acks for the same session are ignored. The SDK method <code>sendDisclaimerAck(accepted)</code> builds this frame using the hash and conversation id from <code>hello_ack</code>.</p>
+
+          <h3>Server error frames (<code>t: "error"</code>)</h3>
+          <table class="properties-table">
+            <thead>
+              <tr>
+                <th><code>code</code></th>
+                <th>Meaning</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td><code>DISCLAIMER_PENDING</code></td>
+                <td>Client tried to start continuous mode or stream audio before sending a successful ack; session stays open—send <code>disclaimer_ack</code> then retry</td>
+              </tr>
+              <tr>
+                <td><code>DISCLAIMER_DECLINED</code></td>
+                <td>User declined; server ends the conversation</td>
+              </tr>
+              <tr>
+                <td><code>DISCLAIMER_TIMEOUT</code></td>
+                <td>No acknowledgement in time; connection closed</td>
+              </tr>
+              <tr>
+                <td><code>DISCLAIMER_HASH_MISMATCH</code></td>
+                <td>Ack hash did not match server expectation; connection closed</td>
+              </tr>
+            </tbody>
+          </table>
+
+          <h3>Using VoiceSDK v2 (custom apps)</h3>
+          <ol>
+            <li>Use <strong>protocol v2</strong> (default in current SDK): <code>protocolVersion: 2</code>.</li>
+            <li>After <code>connect()</code>, wait for <code>hello_ack</code>. The SDK sets <code>voiceSDK.disclaimersPending === true</code> when the gate is active.</li>
+            <li>Listen for <code>disclaimersRequired</code>. The payload includes <code>texts</code>, <code>disclaimersHash</code>, <code>disclaimerTimeoutMs</code>, and <code>conversationId</code> for your UI.</li>
+            <li>Show your own modal or screen with the given texts. Do not call <code>startRecording()</code> until the user has accepted and you have called <code>sendDisclaimerAck(true)</code> (calling <code>startRecording()</code> while <code>disclaimersPending</code> is still true throws with <code>error.code === 'DISCLAIMER_PENDING'</code>).</li>
+            <li>On accept: <code>voiceSDK.sendDisclaimerAck(true)</code>. The server then opens STT, plays the greeting, and accepts <code>start_continuous_mode</code>.</li>
+            <li>On decline: <code>voiceSDK.sendDisclaimerAck(false)</code>. The server closes the session; the SDK emits <code>disclaimerRejected</code> and the raw <code>message</code> event for the error frame.</li>
+            <li>Handle <code>disclaimerRejected</code> for terminal server outcomes (<code>DISCLAIMER_DECLINED</code>, <code>DISCLAIMER_TIMEOUT</code>, <code>DISCLAIMER_HASH_MISMATCH</code>). Handle <code>error</code> for <code>DISCLAIMER_PENDING</code> (ordering bug or race—fix by ack first).</li>
+          </ol>
+          <pre><code class="language-javascript">const voiceSDK = new VoiceSDK({ agentId, appId, protocolVersion: 2 });
+
+voiceSDK.on('disclaimersRequired', (payload) => {
+  showMyModal({
+    texts: payload.texts,
+    onAccept: () => voiceSDK.sendDisclaimerAck(true),
+    onDecline: () => voiceSDK.sendDisclaimerAck(false)
+  });
+});
+
+voiceSDK.on('disclaimerRejected', ({ code, message }) => {
+  console.warn('Disclaimer flow ended:', code, message);
+});
+
+voiceSDK.on('error', (err) => {
+  if (err.code === 'DISCLAIMER_PENDING') {
+    console.warn('Start recording only after sendDisclaimerAck(true)');
+  }
+});
+
+await voiceSDK.connect();
+// Only after ack (or if disclaimersRequired never fired):
+await voiceSDK.startRecording();</code></pre>
+          <p><strong>SDK state you may read:</strong> <code>disclaimersPending</code>, <code>disclaimersHash</code>, <code>lastDisclaimerPayload</code> (set from <code>hello_ack</code>). After <code>sendDisclaimerAck</code> runs, the SDK clears <code>disclaimersPending</code> locally when the WebSocket send succeeds.</p>
+
+          <h3>Voice &amp; Chat Widget (built-in behavior)</h3>
+          <p>No extra widget options are required. When the server sends the disclaimer gate:</p>
+          <ul>
+            <li><code>VoiceInterface</code> waits after the WebSocket is up and <code>hello_ack</code> is processed.</li>
+            <li>It opens a built-in modal (<strong>Notice</strong> / <strong>Accept</strong> / <strong>Decline</strong>) with <code>disclaimerTexts</code> from the server.</li>
+            <li>Accept: on <strong>desktop</strong>, the widget sends <code>sendDisclaimerAck(true)</code> immediately, then requests the microphone and <code>startListening</code>. On <strong>mobile</strong>, it waits until the user has granted microphone access (and the post-grant audio delay) before sending <code>sendDisclaimerAck(true)</code>, so the server does not stream the greeting over the system permission sheet or get cut off when capture starts.</li>
+            <li>Decline (<strong>No thanks</strong>) calls <code>sendDisclaimerAck(false)</code>, waits briefly so the ack reaches the server (which ends the conversation and closes the socket), then disconnects the client, invokes <code>onConversationEnd</code> on the wrapper SDK since recording never started, resets UI, and returns to landing (or idle voice in <code>voice-only</code> mode).</li>
+          </ul>
+          <p>To match your site language, use the widget’s existing <code>language</code> / translation hooks for general UI; disclaimer <strong>body text</strong> always comes from the server (compliance copy).</p>
+
+          <h3>Resume &amp; text chat</h3>
+          <p><strong>Resume:</strong> Resumed voice sessions omit the disclaimer gate.</p>
+          <p><strong>Text chat:</strong> Server-driven disclaimer is implemented for <strong>voice</strong> in this release. The text WebSocket <code>hello</code> path does not yet mirror these fields; extend the backend and <code>TextChatSDK</code> if you need the same gate for text-only sessions.</p>
+
           <div class="info-box">
             <strong>🎯 Key Benefits:</strong>
             <ul style="margin-top: 10px;">
@@ -1017,6 +1188,17 @@ voiceSDK.on('formatNegotiated', (format) => {
           <h1>Voice & Chat Widget</h1>
           <p>Pre-built, customizable widget with voice and text chat - perfect for adding AI conversation to any website.</p>
 
+          <div class="info-box" id="widget-agent-display-name" style="margin-bottom: 20px;">
+            <p><strong>Agent display name</strong></p>
+            <ul style="margin: 8px 0 0 18px;">
+              <li>Set the name on the <strong>voice idle hero</strong> (and the letter inside the avatar when no image URL is set) with the <strong>root</strong> property <code>agentName</code> only.</li>
+              <li>Use <code>header.pillTitle</code> for a short CTA on the <strong>desktop floating pill</strong> and the <strong>mobile FAB</strong> (e.g. “Talk to me” / “דברו איתי”); when empty, both use <code>header.title</code>. Override the mobile FAB line only with <code>header.mobileLabel</code>. Separate from <code>agentName</code>.</li>
+              <li><code>voice.agentName</code> is <strong>not supported</strong> — it is removed from config when the widget merges settings.</li>
+              <li>Legacy root <code>headerTitle</code> is <strong>ignored</strong>. Use <code>agentName</code> for the hero name and <code>header.title</code> for the general assistant title line (pill / mobile landing fallback).</li>
+              <li>In <strong>unified</strong> mode, the text chat screen has a top bar with <strong>Voice or text</strong> (widget translation key <code>backToModeChoice</code>) to return to the voice/text choice inside the panel.</li>
+            </ul>
+          </div>
+
           <div class="feature-grid">
             <div class="feature-card">
               <div class="feature-icon">💬</div>
@@ -1057,6 +1239,9 @@ voiceSDK.on('formatNegotiated', (format) => {
   // Required
   agentId: 'agent_123',       // Your AI agent ID
   appId: 'your_app_id',       // Your application ID
+
+  // Optional — root only (voice idle hero name & avatar initial when no image)
+  agentName: 'Alex',
   
   // Optional - Agent Settings Override (available when domain whitelist is configured)
   agentSettingsOverride: {
@@ -1071,7 +1256,13 @@ voiceSDK.on('formatNegotiated', (format) => {
   
   // Optional - Appearance
   primaryColor: '#7C3AED',    // Widget theme color
-  position: 'bottom-right',   // 'bottom-right', 'bottom-left'
+  position: {                 // Or shorthand: 'bottom-right', 'bottom-left'
+    vertical: 'bottom',
+    horizontal: 'right',
+    offset: { x: 20, y: 20 },
+    draggable: false,         // true = user can drag launcher + panel
+    draggablePersist: true    // remember drag position in localStorage
+  },
   language: 'en',             // 'en', 'es', 'fr', 'de', 'he', etc.
   direction: 'ltr',           // 'ltr' or 'rtl' for right-to-left languages
   
@@ -1083,6 +1274,9 @@ voiceSDK.on('formatNegotiated', (format) => {
   }
 });</code></pre>
 
+          <h2>Server-driven disclaimer (voice)</h2>
+          <p>If your agent has non-empty <code>disclaimers</code> configured on the server, the widget shows a <strong>Notice</strong> modal with the server-provided text before microphone streaming and the greeting. The user must tap <strong>Accept</strong> or <strong>Decline</strong>; you do not need extra embed code. For protocol fields, SDK hooks, and custom implementations, see <a href="#server-driven-disclaimer">Server-driven disclaimer (voice)</a>.</p>
+
           <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.
@@ -1104,7 +1298,7 @@ voiceSDK.on('formatNegotiated', (format) => {
             <ul style="margin-top: 10px; margin-left: 20px;">
               <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>
+              <li>WebSocket URLs use the production TalkToPC endpoint by default (same as voice). Pass <code>websocketUrl</code> only if you need a non-default backend.</li>
             </ul>
           </div>
 
@@ -1116,8 +1310,9 @@ voiceSDK.on('formatNegotiated', (format) => {
   appId: 'your_app_id',
   
   icon: {
-    type: 'custom',                              // 'default', 'emoji', or 'custom'
-    customImage: 'https://your-site.com/logo.png', // Custom image URL
+    type: 'custom',                              // 'microphone', 'emoji', or 'custom'
+    // Omit customImage (or use '') for default animated waveform on the desktop pill
+    customImage: 'https://your-site.com/logo.png', // Optional: pill icon image URL
     size: 60,                                    // Icon size in pixels
     backgroundColor: '#FFFFFF',                  // Background color
     borderRadius: '50%'                         // Border radius (50% for circle)
@@ -1216,6 +1411,31 @@ document.getElementById('myButton').onclick = () => {
             <pre><code>widget.toggle();</code></pre>
           </div>
 
+          <div class="method-card">
+            <h3><code>widget.minimize()</code></h3>
+            <p>Collapse the chat panel back to the round launcher pill — same visual
+              state as if the user had clicked the launcher while the panel was open.
+              Idempotent (no-op when already minimized) and does <strong>not</strong>
+              end an active voice call: the WebSocket and conversation state are
+              preserved, the user just sees the bubble until they re-open. Also
+              triggered automatically by a backend-pushed
+              <code>{ t: 'minimize_widget' }</code> control message, so partner
+              integrations can choreograph the chat panel from the server side
+              (e.g. minimize the widget when opening a native trolley drawer).</p>
+            <pre><code>widget.minimize();</code></pre>
+          </div>
+
+          <div class="method-card">
+            <h3><code>widget.maximize()</code></h3>
+            <p>Expand the chat panel from the round launcher pill — same visual
+              state as if the user had clicked the launcher while the panel was
+              closed. Idempotent (no-op when already open) and runs the same
+              auto-connect side-effect a real click would when configured. Also
+              triggered automatically by a backend-pushed
+              <code>{ t: 'maximize_widget' }</code> control message.</p>
+            <pre><code>widget.maximize();</code></pre>
+          </div>
+
           <div class="method-card">
             <h3><code>widget.destroy()</code></h3>
             <p>Remove the widget from the page.</p>
@@ -1227,36 +1447,47 @@ document.getElementById('myButton').onclick = () => {
             <p>Update widget configuration dynamically.</p>
             <pre><code>widget.updateConfig({
   primaryColor: '#FF5733',
-  language: 'es'
+  language: 'es',
+  agentName: 'Jordan'  // root only; voice.agentName in this object is ignored
 });</code></pre>
           </div>
 
-          <h2>Widget Events</h2>
+          <h2>Widget Event Callbacks</h2>
+          <p>Pass these as top-level config properties when constructing <code>TTPChatWidget</code>:</p>
           <pre><code>const widget = new TTPAgentSDK.TTPChatWidget({
   agentId: 'agent_123',
   appId: 'your_app_id',
-  
-  // Event callbacks
-  onOpen: () => {
-    console.log('Chat opened');
+
+  onConversationStart: () => {
+    console.log('Voice conversation started');
   },
-  
-  onClose: () => {
-    console.log('Chat closed');
+
+  onConversationEnd: () => {
+    console.log('Voice conversation ended');
   },
-  
-  onMessage: (message) => {
-    console.log('New message:', message);
+
+  onBargeIn: () => {
+    console.log('User interrupted the agent');
   },
-  
-  onError: (error) => {
-    console.error('Widget error:', error);
+
+  onAudioStartPlaying: () => {
+    console.log('Agent audio started');
   },
-  
-  onReady: () => {
-    console.log('Widget initialized');
+
+  onAudioStoppedPlaying: () => {
+    console.log('Agent audio stopped');
+  },
+
+  onSubtitleDisplay: (subtitle) => {
+    console.log('Subtitle:', subtitle);
+  },
+
+  onVoiceCallButtonClick: () => {
+    // Return false to prevent starting the call
+    return true;
   }
 });</code></pre>
+          <p>For lower-level VoiceSDK events (<code>onConnected</code>, <code>onMessage</code>, etc.), use <code>widget.voiceInterface.sdk</code> or instantiate <code>VoiceSDK</code> directly. See <a href="#events">Events &amp; Callbacks</a>.</p>
 
           <h2>Complete Example</h2>
           <pre><code>&lt;!DOCTYPE html&gt;
@@ -1312,13 +1543,15 @@ document.getElementById('myButton').onclick = () => {
 &lt;/body&gt;
 &lt;/html&gt;</code></pre>
 
-          <h2>Configuration Reference</h2>
+          <h2 id="configuration-reference">Configuration Reference</h2>
           <div class="info-box">
             <p><strong>🎨 Extensive Customization</strong></p>
             <p>The Voice & Chat Widget can be customized in almost every aspect - colors, text, icons, sizes, behaviors, and more!</p>
           </div>
 
-          <p>See the <a href="../examples/test-text-chat.html" target="_blank">live demo</a> to experiment with all customization options interactively.</p>
+          <p><strong>Agent naming:</strong> use root <code>agentName</code> for the voice idle hero and avatar letter fallback. Do not use <code>voice.agentName</code> (removed on merge). Do not use legacy root <code>headerTitle</code> (ignored). See <a href="#widget-agent-display-name">Agent display name</a> above.</p>
+
+          <p>See the <a href="../examples/widget-customization.html" target="_blank">live customization demo</a> to experiment with all options interactively, including quick themes (Default, Light, Sunset, Hebrew, S-Law).</p>
 
           <details open>
             <summary><strong>Required Configuration</strong></summary>
@@ -1366,8 +1599,8 @@ document.getElementById('myButton').onclick = () => {
                 <tr>
                   <td><code>direction</code></td>
                   <td>string</td>
-                  <td>'ltr'</td>
-                  <td>'ltr' or 'rtl'</td>
+                  <td><code>'ltr'</code> (or <code>'rtl'</code> when <code>language</code> is <code>he</code> / <code>ar</code>)</td>
+                  <td><code>'ltr'</code> or <code>'rtl'</code>. If omitted, Hebrew and Arabic default to <code>'rtl'</code>. Sets the shadow host <code>dir</code> so the desktop pill launcher matches the panel (fixes extra padding beside the logo on RTL sites). In <code>'rtl'</code>, transcript, bubbles, and mobile bar use RTL punctuation order.</td>
                 </tr>
                 <tr>
                   <td><code>language</code></td>
@@ -1375,6 +1608,18 @@ document.getElementById('myButton').onclick = () => {
                   <td>'en'</td>
                   <td>Language code (en, es, fr, de, he, ar, etc.)</td>
                 </tr>
+                <tr>
+                  <td><code>agentName</code></td>
+                  <td>string</td>
+                  <td>—</td>
+                  <td><strong>Root only.</strong> Name on the voice idle hero and first-letter avatar fallback when no header image is set. If omitted or empty, the widget defaults to <code>Sasha</code>. Color: <code>voice.agentNameColor</code>. Not the desktop pill text — use <code>header.pillTitle</code> or <code>header.title</code> for that.</td>
+                </tr>
+                <tr>
+                  <td><code>headerTitle</code></td>
+                  <td>string</td>
+                  <td>—</td>
+                  <td><strong>Deprecated / ignored.</strong> Former optional root field; it is no longer read. Use <code>agentName</code> for the voice hero name and <code>header.title</code> for the shared assistant title line.</td>
+                </tr>
                 <tr>
                   <td><code>variables</code></td>
                   <td>object</td>
@@ -1384,8 +1629,8 @@ document.getElementById('myButton').onclick = () => {
                 <tr>
                   <td><code>websocketUrl</code></td>
                   <td>string</td>
-                  <td>null</td>
-                  <td>Optional custom WebSocket base URL (defaults to wss://speech.talktopc.com/ws/conv)</td>
+                  <td><code>wss://speech.talktopc.com/ws/conv</code> (built-in)</td>
+                  <td>Optional override for voice and text. Omit unless you point at a custom backend; text still uses <code>/chat/text</code> on the same host as this base.</td>
                 </tr>
                 <tr>
                   <td><code>agentSettingsOverride</code></td>
@@ -1405,6 +1650,30 @@ document.getElementById('myButton').onclick = () => {
                   <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>
+                <tr>
+                  <td><code>mobileVoiceUI</code></td>
+                  <td>boolean</td>
+                  <td>auto</td>
+                  <td><strong>Root-level override.</strong> Force mobile-style voice call UI (bottom bar + overlay) or desktop hero. Takes precedence over <code>behavior.mobileVoiceUI</code> when both are set. Omit for auto: native iOS/Android, or viewport ≤768px with touch/coarse pointer.</td>
+                </tr>
+                <tr>
+                  <td><code>inputFormat</code></td>
+                  <td>object</td>
+                  <td>—</td>
+                  <td>Optional v2 input audio format passed to the voice WebSocket hello message: <code>{ encoding, sampleRate, channels, bitDepth }</code>. Same fields as top-level VoiceSDK config (<code>sampleRate</code>, etc.). See <a href="#protocol-v2">Protocol v2</a>.</td>
+                </tr>
+                <tr>
+                  <td><code>visualAssistant</code></td>
+                  <td>object</td>
+                  <td>null</td>
+                  <td>Enable browser-side visual assistant tools (page read, highlight, scroll, navigate, form fill, click, screenshot). Also accepted under <code>agentSettingsOverride.visualAssistant</code>. See <a href="#visual-assistant-config">Visual Assistant</a> below.</td>
+                </tr>
+                <tr>
+                  <td><code>whatsapp</code></td>
+                  <td>object</td>
+                  <td>null</td>
+                  <td>Optional WhatsApp handoff on the voice idle hero: <code>{ number: '972501234567', text: 'optional pre-filled message' }</code>. Non-digits are stripped from <code>number</code>. Omit to hide the WhatsApp button.</td>
+                </tr>
               </tbody>
             </table>
           </details>
@@ -1487,6 +1756,9 @@ const widget = new TTPChatWidget({
             <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><strong>Unified mode:</strong> With <code>useShadowDOM: false</code>, the widget must show only one of voice or text at a time inside the panel. A previous reset rule forced <code>display:flex</code> on multiple roots (higher specificity than the hide rules), which made them stack vertically on Shopify; this is fixed in current builds.</li>
+              <li><strong>Voice call UI:</strong> Call duration updates and the red recording dot use DOM queries scoped to <code>#ttp-widget-container</code> (not <code>document</code>), and extra CSS guards the dot and pulse when themes override spans — fixes static timers and missing dots on Shopify.</li>
+              <li><strong>Orb waveform:</strong> Bars are injected under <code>#ttp-widget-container</code>. With <code>useShadowDOM: false</code>, the same CSS <code>ttp-wave</code> keyframes and per-bar delays are used as in Shadow DOM; high-specificity rules protect size and animation without fixing <code>opacity</code> (which would break the keyframe fade).</li>
               <li>The widget automatically handles CSS injection differently based on this setting - no additional configuration needed</li>
             </ul>
           </div>
@@ -1527,8 +1799,27 @@ const widget = new TTPChatWidget({
                   <td>{ x: 20, y: 20 }</td>
                   <td>Offset from edges (pixels)</td>
                 </tr>
+                <tr>
+                  <td><code>position.draggable</code></td>
+                  <td>boolean</td>
+                  <td>false</td>
+                  <td>When <code>true</code>, visitors can drag the launcher pill / mobile FAB and the open chat panel around the viewport. They move <strong>together as one unit</strong> (never split). Drag handles: the pill/FAB and panel header bars (voice idle header, active-call top bar, text chat top bar). Header buttons (close, etc.) still work normally.</td>
+                </tr>
+                <tr>
+                  <td><code>position.draggablePersist</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>When <code>true</code> (default), the dragged position is saved in <code>localStorage</code> per origin+path and restored on the next visit. Set <code>false</code> to reset to the configured corner on every load. The widget unit and the desktop minimized voice strip (<code>flavor.callView: 'minimized'</code>) remember positions independently.</td>
+                </tr>
+                <tr>
+                  <td><code>positionOffset</code></td>
+                  <td>object</td>
+                  <td>—</td>
+                  <td><strong>Legacy.</strong> Used only when <code>position</code> is a string (e.g. <code>'bottom-right'</code>) instead of an object. Prefer <code>position.offset</code>.</td>
+                </tr>
               </tbody>
             </table>
+            <p style="margin: 12px 0 0 0;">When <code>position.draggable</code> is enabled, the desktop <strong>minimized voice strip</strong> (<code>flavor.callView: 'minimized'</code>) is also draggable by its body (controls and text input still work). Positions are clamped to stay on-screen and re-clamped on window resize.</p>
           </details>
 
           <details>
@@ -1552,8 +1843,8 @@ const widget = new TTPChatWidget({
                 <tr>
                   <td><code>icon.customImage</code></td>
                   <td>string</td>
-                  <td>TTP logo</td>
-                  <td>URL to custom icon image</td>
+                  <td>—</td>
+                  <td>Optional HTTPS image URL for the <strong>desktop</strong> floating pill icon. When omitted or empty, the pill uses the same <strong>animated waveform</strong> as the mobile launcher and pre-chat landing (white bars on a frosted circle).</td>
                 </tr>
                 <tr>
                   <td><code>icon.size</code></td>
@@ -1641,7 +1932,13 @@ const widget = new TTPChatWidget({
                   <td><code>header.title</code></td>
                   <td>string</td>
                   <td>'Chat Assistant'</td>
-                  <td>Header title text</td>
+                  <td>Default title when more specific labels are omitted: fallback for the <strong>desktop and mobile</strong> launchers if <code>header.pillTitle</code> is not set (unless <code>header.mobileLabel</code> is set), and for the <strong>mobile pre-chat landing</strong> name when root <code>agentName</code> is not set. Does <strong>not</strong> set the voice idle hero name — use root <code>agentName</code> for that.</td>
+                </tr>
+                <tr>
+                  <td><code>header.pillTitle</code></td>
+                  <td>string</td>
+                  <td>''</td>
+                  <td>Optional main line on the <strong>desktop</strong> floating pill and the <strong>mobile</strong> pill launcher (same fallback chain as desktop: when empty, uses <code>header.title</code>). Set <code>header.mobileLabel</code> if the FAB needs different copy than the desktop pill. Does not change the voice idle hero name — use root <code>agentName</code> for that.</td>
                 </tr>
                 <tr>
                   <td><code>header.showTitle</code></td>
@@ -1661,12 +1958,73 @@ const widget = new TTPChatWidget({
                   <td>'#FFFFFF'</td>
                   <td>Header text color</td>
                 </tr>
+                <tr>
+                  <td><code>header.mobileLabel</code></td>
+                  <td>string</td>
+                  <td>—</td>
+                  <td>Optional: overrides the mobile pill launcher’s main line only. When omitted, the FAB uses the same text as the desktop pill (<code>header.pillTitle</code> or <code>header.title</code>).</td>
+                </tr>
+                <tr>
+                  <td><code>header.showCloseButton</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>Show or hide the panel close button in the header.</td>
+                </tr>
+                <tr>
+                  <td><code>header.onlineIndicatorText</code></td>
+                  <td>string</td>
+                  <td>Auto</td>
+                  <td>Online status label on the desktop pill, mobile FAB, and headers. When omitted, uses the translated “Online” string for the widget language.</td>
+                </tr>
+                <tr>
+                  <td><code>header.onlineIndicatorColor</code></td>
+                  <td>string</td>
+                  <td>header.textColor</td>
+                  <td>Text color for the online indicator label.</td>
+                </tr>
+                <tr>
+                  <td><code>header.onlineIndicatorDotColor</code></td>
+                  <td>string</td>
+                  <td>'#10b981'</td>
+                  <td>Color of the online status dot next to the indicator text.</td>
+                </tr>
+                <tr>
+                  <td><code>footer.show</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>Show or hide the &quot;Powered by&quot; footer.</td>
+                </tr>
+                <tr>
+                  <td><code>footer.brand</code></td>
+                  <td>string</td>
+                  <td>'talktopc'</td>
+                  <td>Brand shown in the &quot;Powered by&quot; footer. <code>'talktopc'</code> links to talktopc.com; <code>'speacart'</code> links to speacart.com. Any other value defaults to TalkToPC.</td>
+                </tr>
+                <tr>
+                  <td><code>footer.backgroundColor</code></td>
+                  <td>string</td>
+                  <td>'#f9fafb'</td>
+                  <td>Footer background color.</td>
+                </tr>
+                <tr>
+                  <td><code>footer.textColor</code></td>
+                  <td>string</td>
+                  <td>'#9ca3af'</td>
+                  <td>Footer text color.</td>
+                </tr>
+                <tr>
+                  <td><code>footer.hoverColor</code></td>
+                  <td>string</td>
+                  <td>'#7C3AED'</td>
+                  <td>Footer link hover color.</td>
+                </tr>
               </tbody>
             </table>
           </details>
 
           <details>
             <summary><strong>Messages & Chat</strong></summary>
+            <p style="margin: 10px 0 12px 0;">On <strong>desktop</strong>, when the text chat view is open, the panel uses a <strong>fixed height</strong> (up to <code>min(520px, 100vh − 100px)</code>) so new messages scroll inside the transcript instead of stretching the card. By default (<code>text.useVoiceTheme</code> not <code>false</code>), the text UI shares the <strong>voice theme</strong>: <code>voice.heroGradient1</code> / <code>heroGradient2</code> surface (same as the voice idle hero), <code>voice.primaryBtnGradient*</code> and <code>startCallButtonColor</code> for send/focus and user bubbles (<code>#primary40</code> tint), <code>avatarGradient1/2</code> on the assistant avatar, and transcript-style translucent inputs. The “Powered by” footer uses the same link accent as on the hero. Set <code>text.useVoiceTheme: false</code> for a light layout driven by solid <code>panel.backgroundColor</code> and <code>messages.*</code> colors.</p>
             <table class="properties-table">
               <thead>
                 <tr>
@@ -1705,12 +2063,36 @@ const widget = new TTPChatWidget({
                   <td><code>messages.textColor</code></td>
                   <td>string</td>
                   <td>'#1F2937'</td>
-                  <td>Message text color</td>
+                  <td>Message text color (fallback when role-specific colors are omitted)</td>
+                </tr>
+                <tr>
+                  <td><code>messages.userTextColor</code></td>
+                  <td>string</td>
+                  <td>messages.textColor</td>
+                  <td>User message text color</td>
+                </tr>
+                <tr>
+                  <td><code>messages.agentTextColor</code></td>
+                  <td>string</td>
+                  <td>messages.textColor</td>
+                  <td>Agent message text color</td>
+                </tr>
+                <tr>
+                  <td><code>messages.userAvatarIcon</code></td>
+                  <td>string</td>
+                  <td>'👤'</td>
+                  <td>Emoji/icon shown on user message avatars</td>
+                </tr>
+                <tr>
+                  <td><code>messages.agentAvatarIcon</code></td>
+                  <td>string</td>
+                  <td>'🤖'</td>
+                  <td>Emoji/icon shown on agent message avatars</td>
                 </tr>
                 <tr>
                   <td><code>messages.fontSize</code></td>
                   <td>string</td>
-                  <td>'14px'</td>
+                  <td>'16px'</td>
                   <td>Message font size</td>
                 </tr>
                 <tr>
@@ -1719,23 +2101,29 @@ const widget = new TTPChatWidget({
                   <td>8</td>
                   <td>Message bubble radius</td>
                 </tr>
+                <tr>
+                  <td><code>text.useVoiceTheme</code></td>
+                  <td>boolean</td>
+                  <td><code>true</code></td>
+                  <td>When <code>true</code>, text chat matches the voice idle hero gradient, primary gradients, avatar gradients, and dark translucent bubbles/inputs (see voice theme). When <code>false</code>, chrome follows solid <code>panel.backgroundColor</code> (hex) and <code>messages.userBackgroundColor</code> / <code>agentBackgroundColor</code>.</td>
+                </tr>
                 <tr>
                   <td><code>text.sendButtonColor</code></td>
                   <td>string</td>
-                  <td>'#7C3AED'</td>
-                  <td>Send button color</td>
+                  <td>voice accent</td>
+                  <td>Send button fill; defaults to the first resolvable hex from <code>voice.primaryBtnGradient1</code>, <code>voice.primaryBtnGradient2</code>, or <code>voice.startCallButtonColor</code> (including the default start-call indigo when those are unset), then <code>#7C3AED</code>.</td>
                 </tr>
                 <tr>
                   <td><code>text.sendButtonHoverColor</code></td>
                   <td>string</td>
-                  <td>'#6D28D9'</td>
-                  <td>Send button hover color</td>
+                  <td>voice accent 2 / shaded</td>
+                  <td>Hover state; uses <code>voice.primaryBtnGradient2</code> when it resolves to a different hex than the send color, otherwise a slightly darker shade of the accent.</td>
                 </tr>
                 <tr>
                   <td><code>text.sendButtonActiveColor</code></td>
                   <td>string</td>
-                  <td>'#6D28D9'</td>
-                  <td>Send button active color</td>
+                  <td>same as hover</td>
+                  <td>Active press state; same resolution as hover.</td>
                 </tr>
                 <tr>
                   <td><code>text.sendButtonText</code></td>
@@ -1752,7 +2140,7 @@ const widget = new TTPChatWidget({
                 <tr>
                   <td><code>text.sendButtonFontSize</code></td>
                   <td>string</td>
-                  <td>'18px'</td>
+                  <td>'20px'</td>
                   <td>Send button font size</td>
                 </tr>
                 <tr>
@@ -1776,8 +2164,8 @@ const widget = new TTPChatWidget({
                 <tr>
                   <td><code>text.inputFocusColor</code></td>
                   <td>string</td>
-                  <td>'#7C3AED'</td>
-                  <td>Input focus color</td>
+                  <td>voice accent</td>
+                  <td>Input focus border and ring; same default chain as <code>text.sendButtonColor</code>.</td>
                 </tr>
                 <tr>
                   <td><code>text.inputBackgroundColor</code></td>
@@ -1794,7 +2182,7 @@ const widget = new TTPChatWidget({
                 <tr>
                   <td><code>text.inputFontSize</code></td>
                   <td>string</td>
-                  <td>'14px'</td>
+                  <td>'16px'</td>
                   <td>Input font size</td>
                 </tr>
                 <tr>
@@ -1806,15 +2194,34 @@ const widget = new TTPChatWidget({
                 <tr>
                   <td><code>text.inputPadding</code></td>
                   <td>string</td>
-                  <td>'6px 14px'</td>
+                  <td>'8px 16px'</td>
                   <td>Input padding</td>
                 </tr>
+                <tr>
+                  <td><code>text.sendButtonHint.text</code></td>
+                  <td>string</td>
+                  <td>''</td>
+                  <td>Optional hint text below or near the send button</td>
+                </tr>
+                <tr>
+                  <td><code>text.sendButtonHint.color</code></td>
+                  <td>string</td>
+                  <td>'#6B7280'</td>
+                  <td>Send button hint text color</td>
+                </tr>
+                <tr>
+                  <td><code>text.sendButtonHint.fontSize</code></td>
+                  <td>string</td>
+                  <td>'14px'</td>
+                  <td>Send button hint font size</td>
+                </tr>
               </tbody>
             </table>
           </details>
 
           <details>
             <summary><strong>Voice Configuration</strong></summary>
+            <p style="margin: 10px 0 12px 0;">The agent’s spoken/idle <strong>display name</strong> is configured with <strong>root</strong> <code>agentName</code> only. Any <code>voice.agentName</code> value in your JSON is stripped during merge and has no effect (<code>widget.updateConfig({ voice: { agentName: '…' } })</code> is ignored for naming).</p>
             <table class="properties-table">
               <thead>
                 <tr>
@@ -1895,7 +2302,7 @@ const widget = new TTPChatWidget({
                   <td><code>voice.startCallButtonColor</code></td>
                   <td>string</td>
                   <td>'#667eea'</td>
-                  <td>Start call button color</td>
+                  <td>Fills the start-call button gradient when <code>primaryBtnGradient1</code>/<code>2</code> are omitted. The “TalkToPC” footer link uses the same solid accent as the start button (<code>primaryBtnGradient1</code>, then <code>startCallButtonColor</code>, then defaults).</td>
                 </tr>
                 <tr>
                   <td><code>voice.startCallButtonTextColor</code></td>
@@ -1927,6 +2334,12 @@ const widget = new TTPChatWidget({
                   <td>'#94a3b8'</td>
                   <td>Transcript label color</td>
                 </tr>
+                <tr>
+                  <td><code>voice.userTranscriptPrefix</code></td>
+                  <td>string | null</td>
+                  <td>null</td>
+                  <td>Prefix before live user speech (STT) in the collapsed transcript strip and mobile bar (e.g. <code>"You: "</code>). <code>null</code> uses the translation key <code>userTranscriptPrefix</code> for the widget language; empty string removes the prefix.</td>
+                </tr>
                 <tr>
                   <td><code>voice.controlButtonColor</code></td>
                   <td>string</td>
@@ -1945,8 +2358,170 @@ const widget = new TTPChatWidget({
                   <td>'en'</td>
                   <td>Voice language (overrides global)</td>
                 </tr>
+                <tr>
+                  <td><code>voice.statusDotColor</code></td>
+                  <td>string</td>
+                  <td>'#10b981'</td>
+                  <td>Status dot color on the voice idle screen</td>
+                </tr>
+                <tr>
+                  <td><code>voice.statusText</code></td>
+                  <td>string | null</td>
+                  <td>null</td>
+                  <td>Custom status line on the voice idle screen. <code>null</code> uses the translated default.</td>
+                </tr>
+                <tr>
+                  <td><code>voice.outputContainer</code></td>
+                  <td>string</td>
+                  <td>'raw'</td>
+                  <td>Output audio container for v2 format negotiation: <code>'raw'</code> or <code>'wav'</code></td>
+                </tr>
+                <tr>
+                  <td><code>voice.outputEncoding</code></td>
+                  <td>string</td>
+                  <td>'pcm'</td>
+                  <td>Output encoding: <code>'pcm'</code>, <code>'pcmu'</code>, or <code>'pcma'</code></td>
+                </tr>
+                <tr>
+                  <td><code>voice.outputSampleRate</code></td>
+                  <td>number</td>
+                  <td>24000</td>
+                  <td>Requested output sample rate (Hz): 8000, 16000, 22050, 24000, 44100, or 48000</td>
+                </tr>
+                <tr>
+                  <td><code>voice.outputChannels</code></td>
+                  <td>number</td>
+                  <td>1</td>
+                  <td>Output channels (mono only supported)</td>
+                </tr>
+                <tr>
+                  <td><code>voice.outputBitDepth</code></td>
+                  <td>number</td>
+                  <td>16</td>
+                  <td>Output bit depth: 8, 16, or 24</td>
+                </tr>
+              </tbody>
+            </table>
+          </details>
+
+          <details open>
+            <summary><strong>Voice Theming &amp; Pill Launcher</strong></summary>
+            <div class="info-box" style="margin: 10px 0;">
+              <p><strong>🎨 Full Voice UI Theming</strong></p>
+              <p>Customize every visual aspect of the voice interface — hero section, buttons, active call screen, pill launcher, and more. Use these properties to create branded themes or match your website's design.</p>
+              <p style="margin-top:8px;">The desktop pill has a fixed width (158px) on viewports ≥769px with a taller vertical layout (padding, 36px icon circle, 13px/11px title/status). Long titles ellipsize. RTL uses logical padding so the logo sits evenly on the start edge.</p>
+            </div>
+
+            <h4 style="margin-top: 16px;">Pill Launcher</h4>
+            <table class="properties-table">
+              <thead>
+                <tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr>
+              </thead>
+              <tbody>
+                <tr><td><code>voice.pillGradient</code></td><td>string</td><td>''</td><td>CSS gradient for the <strong>mobile</strong> floating pill, the <strong>mobile pre-chat landing sheet</strong> (<code>.ttp-mobile-landing</code>), and the <strong>mobile in-call bottom bar</strong> plus the <strong>expanded conversation header</strong>—same token everywhere. When unset, the widget uses the same default three-stop purple as the landing sheet (<code>linear-gradient(135deg, #581c87, #312e81, #1e1b4b)</code>). Example: <code>linear-gradient(135deg, #7c3aed, #6d28d9)</code>.</td></tr>
+                <tr><td><code>voice.pillTextColor</code></td><td>string</td><td>'#ffffff'</td><td>Text color on the pill launcher</td></tr>
+                <tr><td><code>voice.pillDotColor</code></td><td>string</td><td>'#4ade80'</td><td>Online-status dot color on the pill</td></tr>
+              </tbody>
+            </table>
+
+            <h4 style="margin-top: 16px;">Hero / Idle Screen</h4>
+            <table class="properties-table">
+              <thead>
+                <tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr>
+              </thead>
+              <tbody>
+                <tr><td><code>agentName</code></td><td>string</td><td>—</td><td><strong>Root only</strong> (duplicate of General Configuration). Idle hero name and avatar initial; default <code>Sasha</code> when unset/empty. Mobile pre-chat landing: <code>agentName</code> if set, else <code>header.title</code>.</td></tr>
+                <tr><td><code>voice.avatarGradient1</code></td><td>string</td><td>'#6d56f5'</td><td>Avatar gradient start color</td></tr>
+                <tr><td><code>voice.avatarGradient2</code></td><td>string</td><td>'#a78bfa'</td><td>Avatar gradient end color</td></tr>
+                <tr><td><code>voice.headerAvatarImageUrl</code></td><td>string</td><td>''</td><td>Optional <strong>https</strong> (or http) URL for the <strong>idle</strong> voice header circle (desktop and mobile pre-call). When missing or invalid, the UI shows the <strong>first letter</strong> of the agent name inside the circle (e.g. &quot;S&quot; for Sasha). Same key may be set at the <strong>top level</strong> as <code>headerAvatarImageUrl</code>. Legacy: <code>voice.avatarImageUrl</code> (and snake_case <code>header_avatar_image_url</code> / <code>avatar_image_url</code> on <code>voice</code> or root) are also accepted. Invalid or non-http(s) URLs are ignored.</td></tr>
+                <tr><td><code>voice.onlineDotColor</code></td><td>string</td><td>'#22c55e'</td><td>Online dot next to avatar</td></tr>
+                <tr><td><code>voice.heroGradient1</code></td><td>string</td><td>'#2a2550'</td><td>Hero gradient <strong>start</strong>: desktop voice panel (idle and in-call), widget footer, and <code>.voice-interface.active</code> use <code>linear-gradient(160deg, heroGradient1, heroGradient2)</code>. <strong>Mobile</strong> in-call chrome uses <code>voice.pillGradient</code> instead (see Pill Launcher).</td></tr>
+                <tr><td><code>voice.heroGradient2</code></td><td>string</td><td>'#1a1a2e'</td><td>Hero gradient <strong>end</strong>; pairs with <code>heroGradient1</code> for desktop/active surfaces above—not for the mobile minimized bar (use <code>pillGradient</code>).</td></tr>
+                <tr><td><code>voice.agentNameColor</code></td><td>string</td><td>'#f0eff8'</td><td>Agent name text color</td></tr>
+                <tr><td><code>voice.agentRoleColor</code></td><td>string</td><td>'rgba(255,255,255,0.35)'</td><td>Agent role text color</td></tr>
+                <tr><td><code>voice.agentRole</code></td><td>string</td><td>'AI Voice Assistant'</td><td>Agent role label</td></tr>
+                <tr><td><code>voice.headlineColor</code></td><td>string</td><td>'#ffffff'</td><td>Hero headline text color</td></tr>
+                <tr><td><code>voice.headline</code></td><td>string</td><td>'Hi there 👋'</td><td>Hero headline text</td></tr>
+                <tr><td><code>voice.sublineColor</code></td><td>string</td><td>'rgba(255,255,255,0.45)'</td><td>Hero subline text color</td></tr>
+                <tr><td><code>voice.subline</code></td><td>string</td><td>'Ask me anything...'</td><td>Hero subline text (supports HTML)</td></tr>
+              </tbody>
+            </table>
+
+            <h4 style="margin-top: 16px;">Primary &amp; Secondary Buttons</h4>
+            <table class="properties-table">
+              <thead>
+                <tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr>
+              </thead>
+              <tbody>
+                <tr><td><code>voice.primaryBtnGradient1</code></td><td>string</td><td>'#6d56f5'</td><td>"Start Voice Call" button gradient start; footer “TalkToPC” link uses the same resolved accent (after <code>startCallButtonColor</code> fallback when gradients are omitted). Mobile <strong>user bubbles</strong> and <strong>send</strong> accent use this palette with <code>primaryBtnGradient2</code> / <code>sendButtonColor</code>.</td></tr>
+                <tr><td><code>voice.primaryBtnGradient2</code></td><td>string</td><td>'#9d8df8'</td><td>"Start Voice Call" button gradient end; pairs with <code>sendButtonColor</code> for mobile message/send styling.</td></tr>
+                <tr><td><code>voice.startCallButtonTextColor</code></td><td>string</td><td>'#FFFFFF'</td><td>Primary button text color</td></tr>
+                <tr><td><code>voice.startCallButtonText</code></td><td>string</td><td>'Start Voice Call'</td><td>Primary button label</td></tr>
+                <tr><td><code>voice.sendMessageText</code></td><td>string</td><td>'Send a Message'</td><td>Secondary button label</td></tr>
+                <tr><td><code>voice.secondaryBtnBg</code></td><td>string</td><td>'rgba(255,255,255,0.05)'</td><td>Secondary button background</td></tr>
+                <tr><td><code>voice.secondaryBtnBorder</code></td><td>string</td><td>'rgba(255,255,255,0.09)'</td><td>Secondary button border color</td></tr>
+                <tr><td><code>voice.secondaryBtnTextColor</code></td><td>string</td><td>'rgba(255,255,255,0.6)'</td><td>Secondary button text color</td></tr>
+              </tbody>
+            </table>
+
+            <h4 style="margin-top: 16px;">Active Call View</h4>
+            <table class="properties-table">
+              <thead>
+                <tr><th>Property</th><th>Type</th><th>Default</th><th>Description</th></tr>
+              </thead>
+              <tbody>
+                <tr><td><code>voice.waveformBarColor</code></td><td>string</td><td>'#7C3AED'</td><td>Waveform bar color during call</td></tr>
+                <tr><td><code>voice.speakerButtonColor</code></td><td>string</td><td>'#FFFFFF'</td><td>Speaker button color</td></tr>
               </tbody>
             </table>
+
+            <h4 style="margin-top: 16px;">Quick Theme Example</h4>
+            <p>Apply a complete light theme:</p>
+            <pre><code class="language-javascript">const widget = new TTPAgentSDK.TTPChatWidget({
+  agentId: 'your-agent-id',
+  appId: 'your-app-id',
+  panel: {
+    backgroundColor: '#ffffff',
+    border: '1px solid rgba(0,0,0,0.06)'
+  },
+  voice: {
+    pillGradient: 'linear-gradient(135deg, #7c3aed, #6d28d9)',
+    pillTextColor: '#ffffff',
+    heroGradient1: '#ede9fe',
+    heroGradient2: '#f5f3ff',
+    agentNameColor: '#1e1b4b',
+    headlineColor: '#1e1b4b',
+    sublineColor: '#6b7280',
+    primaryBtnGradient1: '#7c3aed',
+    primaryBtnGradient2: '#a78bfa',
+    secondaryBtnBg: '#f5f3ff',
+    secondaryBtnBorder: 'rgba(124,58,237,0.15)',
+    secondaryBtnTextColor: '#6d28d9'
+  }
+});</code></pre>
+
+            <p style="margin-top: 12px;">RTL Hebrew theme example:</p>
+            <pre><code class="language-javascript">const widget = new TTPAgentSDK.TTPChatWidget({
+  agentId: 'your-agent-id',
+  appId: 'your-app-id',
+  direction: 'rtl',
+  header: { title: 'עוזרת חכמה', onlineIndicatorText: 'מחוברת' },
+  panel: { backgroundColor: '#0f172a' },
+  voice: {
+    pillGradient: 'linear-gradient(135deg, #1e3a5f, #1e40af, #0f172a)',
+    avatarGradient1: '#3b82f6',
+    avatarGradient2: '#1d4ed8',
+    heroGradient1: '#1a2744',
+    heroGradient2: '#0f172a',
+    primaryBtnGradient1: '#3b82f6',
+    primaryBtnGradient2: '#1d4ed8',
+    startCallButtonText: 'התחל שיחה קולית',
+    sendMessageText: 'שלח הודעה',
+    agentRole: 'עוזרת קולית חכמה',
+    headline: 'היי, מה שלומך? 👋',
+    subline: 'שאל/י אותי הכל — אני עונה מיידית בקול או בטקסט.'
+  }
+});</code></pre>
           </details>
 
           <details>
@@ -1985,6 +2560,12 @@ const widget = new TTPChatWidget({
                   <td>false</td>
                   <td>Hide the widget completely</td>
                 </tr>
+                <tr>
+                  <td><code>behavior.mobileVoiceUI</code></td>
+                  <td>boolean</td>
+                  <td>auto</td>
+                  <td>Force mobile-style voice call UI (bottom bar + overlay) or desktop hero. Omit for auto: native iOS/Android, or viewport ≤768px with touch/coarse pointer (helps in-app browsers with desktop User-Agent). Root-level <code>mobileVoiceUI</code> overrides this if both are set.</td>
+                </tr>
                 <tr>
                   <td><code>behavior.autoConnect</code></td>
                   <td>boolean</td>
@@ -2014,7 +2595,7 @@ const widget = new TTPChatWidget({
           </details>
 
           <details>
-            <summary><strong>Animation & Tooltips</strong></summary>
+            <summary><strong>Animation, Prompt Bubble &amp; Tooltips</strong></summary>
             <table class="properties-table">
               <thead>
                 <tr>
@@ -2049,6 +2630,66 @@ const widget = new TTPChatWidget({
                   <td>0.3</td>
                   <td>Animation duration (seconds)</td>
                 </tr>
+                <tr>
+                  <td><code>promptAnimation.enabled</code></td>
+                  <td>boolean</td>
+                  <td>false</td>
+                  <td>Show an animated “Try me!” prompt bubble next to the launcher pill. Must be explicitly set to <code>true</code>.</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.text</code></td>
+                  <td>string</td>
+                  <td>'Try me!'</td>
+                  <td>Prompt bubble label text</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.backgroundColor</code></td>
+                  <td>string</td>
+                  <td>purple gradient</td>
+                  <td>Prompt bubble background (CSS color or gradient)</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.textColor</code></td>
+                  <td>string</td>
+                  <td>'#ffffff'</td>
+                  <td>Prompt bubble text color</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.animationType</code></td>
+                  <td>string</td>
+                  <td>'bounce'</td>
+                  <td><code>'bounce'</code>, <code>'pulse'</code>, <code>'float'</code>, or <code>'none'</code></td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.showShimmer</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>Shimmer effect on the prompt bubble</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.showPulseRings</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>Pulse rings around the launcher while the prompt is visible</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.hideAfterClick</code></td>
+                  <td>boolean</td>
+                  <td>true</td>
+                  <td>Hide the prompt after the user opens the widget</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.hideAfterSeconds</code></td>
+                  <td>number | null</td>
+                  <td>null</td>
+                  <td>Auto-hide after N seconds. <code>null</code> = never auto-hide.</td>
+                </tr>
+                <tr>
+                  <td><code>promptAnimation.position</code></td>
+                  <td>string</td>
+                  <td>'top'</td>
+                  <td>Prompt placement relative to the launcher: <code>'top'</code>, <code>'left'</code>, or <code>'right'</code></td>
+                </tr>
                 <tr>
                   <td><code>tooltips.newChat</code></td>
                   <td>string</td>
@@ -2090,7 +2731,8 @@ const widget = new TTPChatWidget({
           </details>
 
           <details>
-            <summary><strong>Landing Screen (Unified Mode)</strong></summary>
+            <summary><strong>Mobile pre-chat overlay &amp; legacy <code>landing</code> keys (Unified Mode)</strong></summary>
+            <p style="margin: 0 0 12px 0;">On <strong>desktop</strong>, unified mode opens the <strong>voice idle hero</strong> inside the panel—there is <strong>no</strong> in-panel “Voice / Text” mode card screen. Back navigation and call end return to that hero. On <strong>mobile</strong>, the full-screen pre-chat sheet (<code>ttpMobileLanding</code>) still offers call vs text; the following options apply there. During an active call, the <strong>bottom minimized bar</strong> stays visible first; tapping the transcript row opens a <strong>conversation sheet</strong> (type while voice is active). Close the sheet to return to the bar—mute, speaker, and end call remain on the bar when the sheet is closed. On mobile, <strong>Back</strong> (header or text bar) closes the panel and opens the <strong>Call vs Chat</strong> landing overlay directly—the same sheet as tapping the FAB. If the user <strong>declines</strong> the server-driven disclaimer during voice setup, the widget also returns to that <strong>Call vs Chat</strong> overlay (and disconnects) instead of leaving the in-panel “Start call” card. After <strong>accepting</strong> the disclaimer, the minimized <strong>voice bar</strong> (waveform / mic / end call) stays the default view; the expandable conversation sheet with the text field does not open automatically. Other <code>landing.*</code> keys (e.g. mode card colors, in-panel title) remain in config merges for backward compatibility but are <strong>not</strong> rendered on desktop.</p>
             <table class="properties-table">
               <thead>
                 <tr>
@@ -2102,70 +2744,40 @@ const widget = new TTPChatWidget({
               </thead>
               <tbody>
                 <tr>
-                  <td><code>landing.backgroundColor</code></td>
-                  <td>string</td>
-                  <td>Gradient</td>
-                  <td>Landing screen background (color or gradient)</td>
-                </tr>
-                <tr>
-                  <td><code>landing.logo</code></td>
-                  <td>string</td>
-                  <td>'🤖'</td>
-                  <td>Landing screen logo (emoji or text)</td>
-                </tr>
-                <tr>
-                  <td><code>landing.title</code></td>
+                  <td><code>landing.voiceCardTitle</code></td>
                   <td>string</td>
                   <td>null</td>
-                  <td>Landing screen title (null uses translation)</td>
-                </tr>
-                <tr>
-                  <td><code>landing.titleColor</code></td>
-                  <td>string</td>
-                  <td>'#1e293b'</td>
-                  <td>Landing title text color</td>
-                </tr>
-                <tr>
-                  <td><code>landing.modeCardBackgroundColor</code></td>
-                  <td>string</td>
-                  <td>'#FFFFFF'</td>
-                  <td>Mode selection card background</td>
-                </tr>
-                <tr>
-                  <td><code>landing.modeCardBorderColor</code></td>
-                  <td>string</td>
-                  <td>'#E2E8F0'</td>
-                  <td>Mode card border color</td>
+                  <td>Fallback label for the mobile “call” action when <code>landing.callButtonText</code> is not set</td>
                 </tr>
                 <tr>
-                  <td><code>landing.modeCardHoverBorderColor</code></td>
+                  <td><code>landing.textCardTitle</code></td>
                   <td>string</td>
-                  <td>header.backgroundColor</td>
-                  <td>Mode card border color on hover</td>
+                  <td>null</td>
+                  <td>Fallback label for the mobile “chat” action when <code>landing.chatButtonText</code> is not set</td>
                 </tr>
                 <tr>
-                  <td><code>landing.modeCardIconBackgroundColor</code></td>
+                  <td><code>landing.callButtonText</code></td>
                   <td>string</td>
-                  <td>header.backgroundColor</td>
-                  <td>Mode card icon background</td>
+                  <td>null</td>
+                  <td>Mobile overlay primary button text (falls back to <code>voiceCardTitle</code> / translation)</td>
                 </tr>
                 <tr>
-                  <td><code>landing.modeCardTitleColor</code></td>
+                  <td><code>landing.chatButtonText</code></td>
                   <td>string</td>
-                  <td>'#111827'</td>
-                  <td>Mode card title text color</td>
+                  <td>null</td>
+                  <td>Mobile overlay secondary button text (falls back to <code>textCardTitle</code> / translation)</td>
                 </tr>
                 <tr>
-                  <td><code>landing.voiceCardIcon</code></td>
+                  <td><code>landing.statusText</code></td>
                   <td>string</td>
-                  <td>'🎤'</td>
-                  <td>Voice mode card icon</td>
+                  <td>null</td>
+                  <td>Mobile overlay status line; when unset, uses online translation plus <code>landing.subtitle</code> (e.g. “Ready to help”)</td>
                 </tr>
                 <tr>
-                  <td><code>landing.textCardIcon</code></td>
+                  <td><code>landing.subtitle</code></td>
                   <td>string</td>
-                  <td>'💬'</td>
-                  <td>Text mode card icon</td>
+                  <td>—</td>
+                  <td>Shown after the online dot in the mobile overlay status when <code>landing.statusText</code> is not set</td>
                 </tr>
               </tbody>
             </table>
@@ -2243,27 +2855,85 @@ const widget = new TTPChatWidget({
                   <td>true</td>
                   <td>Enable keyboard navigation</td>
                 </tr>
+                <tr>
+                  <td><code>onConversationStart</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when a voice conversation starts (after connect + recording begins).</td>
+                </tr>
+                <tr>
+                  <td><code>onConversationEnd</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when a voice conversation ends (including disclaimer decline before recording).</td>
+                </tr>
+                <tr>
+                  <td><code>onBargeIn</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when the user interrupts the agent (barge-in).</td>
+                </tr>
+                <tr>
+                  <td><code>onAudioStartPlaying</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when agent audio playback starts.</td>
+                </tr>
+                <tr>
+                  <td><code>onAudioStoppedPlaying</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when agent audio playback stops.</td>
+                </tr>
+                <tr>
+                  <td><code>onSubtitleDisplay</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when a subtitle/transcript line is displayed during a call.</td>
+                </tr>
+                <tr>
+                  <td><code>onVoiceCallButtonClick</code></td>
+                  <td>function</td>
+                  <td>—</td>
+                  <td>Called when the user taps “Start Voice Call”. Return <code>false</code> to cancel the call start.</td>
+                </tr>
               </tbody>
             </table>
           </details>
 
+          <div id="visual-assistant-config" class="info-box" style="margin: 20px 0; padding: 20px; background: #f8f9fa; border-left: 4px solid #7C3AED;">
+            <h3 style="margin-top: 0;">Visual Assistant (<code>visualAssistant</code>)</h3>
+            <p>When enabled, the SDK registers browser-side tools the agent can call to read the page, highlight elements, scroll, navigate, fill forms, click elements, and capture screenshots. Tools are always registered on the client; the backend agent config decides which are available.</p>
+            <pre><code class="language-javascript">visualAssistant: {
+  enabled: true,           // Required to activate visual assistant
+  allowHighlight: true,    // highlight_element
+  allowScroll: true,       // scroll_to_element
+  allowNavigate: true,     // navigate_to
+  allowFillForm: true,     // fill_form
+  allowClick: true         // click_element
+}</code></pre>
+            <p>May be set at the widget root or inside <code>agentSettingsOverride.visualAssistant</code>. See <code>examples/test-client-tools.html</code> for a live demo.</p>
+          </div>
+
           <div class="info-box" style="margin: 20px 0;">
             <p><strong>✅ Configuration Verified:</strong></p>
-            <p>All configuration options listed above have been verified against the source code and are fully supported. The widget has 80+ customization options across 13 categories:</p>
+            <p>All configuration options listed above have been verified against the source code and are fully supported. The widget has 100+ customization options across 15+ categories:</p>
             <ul style="margin: 10px 0 0 20px; columns: 2; column-gap: 20px;">
-              <li>General (5 options)</li>
-              <li>Positioning (4 options)</li>
-              <li>Icon & Button (9 options)</li>
-              <li>Panel & Header (8 options)</li>
-              <li>Messages (7 options)</li>
-              <li>Text Chat (13 options)</li>
-              <li>Voice Interface (17 options)</li>
-              <li>Landing Screen (11 options)</li>
-              <li>Tooltips (6 options)</li>
-              <li>Animations (4 options)</li>
-              <li>Behavior (8 options)</li>
-              <li>Accessibility (3 options)</li>
-              <li>Advanced (11 options)</li>
+              <li>General (incl. <code>visualAssistant</code>, <code>whatsapp</code>, <code>inputFormat</code>)</li>
+              <li>Positioning (incl. <code>draggable</code>, <code>draggablePersist</code>)</li>
+              <li>Icon &amp; Button</li>
+              <li>Panel &amp; Header (incl. online indicator, footer colors)</li>
+              <li>Messages &amp; Text Chat</li>
+              <li>Voice Interface &amp; output format</li>
+              <li>Voice Theming &amp; Pill Launcher</li>
+              <li>Mobile landing / legacy <code>landing</code></li>
+              <li>Prompt bubble (<code>promptAnimation</code>)</li>
+              <li>Tooltips &amp; Animations</li>
+              <li>Behavior (incl. <code>mobileVoiceUI</code>)</li>
+              <li>Accessibility</li>
+              <li>Event callbacks (voice lifecycle)</li>
+              <li>Advanced &amp; legacy keys</li>
+              <li>Visual Assistant</li>
             </ul>
             <p style="margin-top: 10px;">Experiment with all options interactively in the <a href="../examples/test-text-chat.html" target="_blank" style="color: inherit; text-decoration: underline;">live demo</a>.</p>
           </div>
@@ -2644,6 +3314,269 @@ function App() {
           </table>
         </section>
 
+        <!-- Fly-to-Cart Animation -->
+        <section id="fly-to-cart" class="doc-section">
+          <h1>Fly-to-Cart Animation</h1>
+          <p>When users tap "Add to Cart" in the e-commerce widget, the product card flies down into the cart icon with a tornado funnel effect. Uses <code>html2canvas</code> to capture the card as an image, avoiding stacking/overflow clipping in iframes or containers with <code>overflow:hidden</code>. Built-in for <code>TTPEcommerceWidget</code>. For custom React product widgets, use the <code>useFlyToCart</code> hook.</p>
+
+          <h2>React Hook (useFlyToCart)</h2>
+          <pre><code>import { useFlyToCart } from 'ttp-agent-sdk';
+
+const cartIconRef = useRef(null);
+const { triggerFly, isAnimating } = useFlyToCart(cartIconRef);
+
+const handleAddToCart = (product) => {
+  triggerFly(cardRef.current, product, () => {
+    addToCartAPI(product);
+  });
+};</code></pre>
+
+          <h2>Vanilla JS (FlyToCart)</h2>
+          <pre><code>import { FlyToCart } from 'ttp-agent-sdk';
+
+const flyToCart = new FlyToCart({
+  getCartTarget: () => document.querySelector('.cart-icon'),
+  onCartBump: () => { /* optional */ },
+});
+
+flyToCart.triggerFly(cardElement, product, () => {
+  addToCartAPI(product);
+});</code></pre>
+        </section>
+
+        <!-- E-commerce: partner API vs browser cart -->
+        <section id="ecommerce-cart-flow" class="doc-section">
+          <h1>E-commerce: Adding to cart (partner API &amp; front-end cart)</h1>
+          <p class="lead">Cart logic is owned by <strong>your integration</strong> (partner APIs, mock stores, or a Shopify storefront). The widget renders products, sends user intent over the WebSocket, and updates the cart summary when it receives the right messages. The SDK does not keep its own authoritative cart array: totals and counts should reflect what the backend (or the browser cart, then the backend) considers true.</p>
+
+          <h2>Who does the &quot;add&quot;?</h2>
+          <table class="properties-table">
+            <thead>
+              <tr>
+                <th>Model</th>
+                <th>Where the line item is added</th>
+                <th>How the widget learns the new totals</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td><strong>Server-side partner cart</strong> (mock store, custom API, headless stack)</td>
+                <td>Conversation backend calls the partner API after <code>product_selected</code> or after the model runs the internal tool <code>add_to_cart</code>.</td>
+                <td>Backend sends <code>t: &quot;cart_updated&quot;</code> with <code>cartTotal</code>, <code>cartItemCount</code>, and optional <code>currency</code>. For a visible &quot;added&quot; toast, include <code>action: &quot;added&quot;</code> and a <code>product</code> object (<code>id</code>, <code>name</code>, <code>price</code>).</td>
+              </tr>
+              <tr>
+                <td><strong>Shopify Online Store</strong> (widget embedded on the store theme)</td>
+                <td>The <strong>browser</strong> must call Shopify&apos;s Ajax Cart API (<code>POST /cart/add.js</code>) so the add uses the visitor&apos;s store <strong>session cookie</strong>. Server-only Storefront API carts are a different session and will not match the theme cart.</td>
+                <td>The conversation backend sends <code>t: &quot;add_to_store_cart&quot;</code> with <code>variantId</code> and <code>quantity</code>. The ecommerce flavor runs the Ajax calls, refreshes the cart bar from <code>GET /cart.js</code>, and sends <code>t: &quot;cart_add_result&quot;</code> back so the backend can continue the turn. The backend may still send <code>cart_updated</code> afterward if you want one canonical sync message.</td>
+              </tr>
+              <tr>
+                <td><strong>Custom client tool</strong></td>
+                <td>Your backend issues a <code>client_tool_call</code> with a tool name you defined (for example <code>addToCart</code>). Your page handles it via <code>registerToolHandler</code> on the widget or <code>AgentSDK</code>.</td>
+                <td>The SDK replies with <code>client_tool_result</code> (or <code>client_tool_error</code>). The cart bar still expects <code>cart_updated</code> unless your handler updates UI itself.</td>
+              </tr>
+            </tbody>
+          </table>
+
+          <h2>Flow 1 — User taps Add / Update on a product card</h2>
+          <ol>
+            <li>The widget stops playback (so the agent does not talk over the action) and sends <code>t: &quot;product_selected&quot;</code> on the voice WebSocket. Payload includes <code>productId</code>, <code>productName</code>, <code>price</code>, <code>quantity</code> (absolute units or weight), and <code>sellBy</code> (<code>quantity</code> or <code>weight</code>).</li>
+            <li><strong>Your backend</strong> decides what happens next:
+              <ul>
+                <li>Update the partner cart via API, then push <strong><code>cart_updated</code></strong> to the session, <em>or</em></li>
+                <li>For Shopify on-domain, send <strong><code>add_to_store_cart</code></strong> and let the widget perform <code>/cart/add.js</code>, then consume <strong><code>cart_add_result</code></strong> on the server, <em>or</em></li>
+                <li>Hybrid: tool or internal step on the server plus a follow-up <code>cart_updated</code>.</li>
+              </ul>
+            </li>
+            <li><code>EcommerceManager.handleCartUpdated</code> updates the bottom cart bar when <code>cartTotal</code> and <code>cartItemCount</code> are present. Optional <code>action: &quot;added&quot;</code> drives the short confirmation UX.</li>
+          </ol>
+
+          <h2>Flow 2 — User asks in voice (or the agent adds without a card click)</h2>
+          <p>For TTP&apos;s Java conversation backend, e-commerce uses <strong>internal</strong> tools such as <code>search_products</code>, <code>add_to_cart</code>, and <code>get_cart</code> (names match what the LLM sees; they are <strong>not</strong> the same as optional SDK <code>client_tool_call</code> names unless you wire them).</p>
+          <ol>
+            <li>The model calls <code>add_to_cart</code> with <code>productId</code> and <code>quantity</code>.</li>
+            <li>The server runs the partner integration:
+              <ul>
+                <li><strong>Partner API cart:</strong> The service calls the partner, receives success and line items, then typically sends <strong><code>cart_updated</code></strong> to the widget with totals and item count so the UI matches the server.</li>
+                <li><strong>Shopify theme cart:</strong> The service sends <strong><code>add_to_store_cart</code></strong> to the widget instead of mutating cart only on the server; the widget performs the Ajax add and returns <strong><code>cart_add_result</code></strong>. Reading the cart may use <code>get_store_cart</code> from the server, which the widget answers with <code>cart_state_result</code> after <code>GET /cart.js</code>.</li>
+              </ul>
+            </li>
+            <li>The model receives a text summary of the tool result and can speak to the user.</li>
+          </ol>
+
+          <h2>Message cheat sheet (widget &harr; backend)</h2>
+          <table class="properties-table">
+            <thead>
+              <tr>
+                <th>Direction</th>
+                <th><code>t</code> / type</th>
+                <th>Role</th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td>Widget &rarr; backend</td>
+                <td><code>product_selected</code></td>
+                <td>User confirmed quantity and tapped Add/Update on a card.</td>
+              </tr>
+              <tr>
+                <td>Backend &rarr; widget</td>
+                <td><code>show_products</code> / <code>show_items</code></td>
+                <td>Render product cards (search or browse results).</td>
+              </tr>
+              <tr>
+                <td>Backend &rarr; widget</td>
+                <td><code>cart_updated</code></td>
+                <td>Sync <code>cartTotal</code>, <code>cartItemCount</code>, optional <code>currency</code>, optional <code>action</code> + <code>product</code> for toast.</td>
+              </tr>
+              <tr>
+                <td>Backend &rarr; widget</td>
+                <td><code>add_to_store_cart</code></td>
+                <td>Shopify: widget runs Ajax add for <code>variantId</code> / <code>quantity</code>. Optional <code>verbalAck: true</code> when the add was triggered by the user tapping Add (not an agent tool); echoed on <code>cart_add_result</code> so the server can prompt a brief spoken acknowledgment.</td>
+              </tr>
+              <tr>
+                <td>Widget &rarr; backend</td>
+                <td><code>cart_add_result</code></td>
+                <td>Outcome of Ajax add (success, counts, totals, currency). Includes <code>verbalAck</code> when the originating <code>add_to_store_cart</code> or hook <code>add_to_site_cart</code> requested it (UI add).</td>
+              </tr>
+              <tr>
+                <td>Backend &rarr; widget</td>
+                <td><code>get_store_cart</code></td>
+                <td>Shopify: widget fetches <code>/cart.js</code> and replies with cart contents.</td>
+              </tr>
+              <tr>
+                <td>Widget &rarr; backend</td>
+                <td><code>cart_state_result</code></td>
+                <td>Async cart snapshot after <code>get_store_cart</code> (implementation-specific).</td>
+              </tr>
+              <tr>
+                <td>Backend &rarr; widget</td>
+                <td><code>client_tool_call</code></td>
+                <td>Optional: run custom logic in the page; reply with <code>client_tool_result</code>.</td>
+              </tr>
+            </tbody>
+          </table>
+
+          <p><strong>Custom client tools:</strong> Register handlers with <code>registerToolHandler</code> on the widget or <code>AgentSDK</code> so the <code>toolName</code> in each <code>client_tool_call</code> matches what your backend defines.</p>
+        </section>
+
+        <!-- Widget Flavors -->
+        <section id="widget-flavors" class="doc-section">
+          <h1>Widget Flavors</h1>
+          <p>The TTP SDK supports domain-specific "flavors" that customize the widget experience for different verticals. Each flavor provides specialized UI components, backend tools, and message handling.</p>
+
+          <h2>Available Flavors</h2>
+          <table>
+            <thead>
+              <tr><th>Flavor Type</th><th>Partner IDs</th><th>Backend Tools</th><th>Key Features</th></tr>
+            </thead>
+            <tbody>
+              <tr>
+                <td><code>ecommerce</code></td>
+                <td><code>mock-store</code>, <code>shopify</code></td>
+                <td><code>search_products</code>, <code>add_to_cart</code>, <code>get_cart</code></td>
+                <td>Product cards, cart bar, fly-to-cart animation</td>
+              </tr>
+              <tr>
+                <td><code>hotels</code></td>
+                <td><code>mock-hotel</code></td>
+                <td><code>search_rooms</code>, <code>select_room</code>, <code>add_extra</code>, <code>get_booking</code>, <code>show_media</code></td>
+                <td>Room cards, booking bar, gallery</td>
+              </tr>
+              <tr>
+                <td><code>pharma</code></td>
+                <td><code>mock-pharm</code></td>
+                <td><code>search_medications</code>, <code>add_to_prescription</code>, <code>get_prescription</code></td>
+                <td>Medication cards (with Rx/OTC badges), prescription summary bar</td>
+              </tr>
+              <tr>
+                <td><code>restaurants</code></td>
+                <td><code>mock-restaurant</code></td>
+                <td><code>search_menu</code>, <code>add_to_order</code>, <code>get_order</code>, <code>show_media</code></td>
+                <td>Menu item cards (with allergen/dietary tags), order summary bar, gallery</td>
+              </tr>
+              <tr>
+                <td><code>tours</code></td>
+                <td><code>mock-tour</code></td>
+                <td><code>search_tours</code>, <code>book_tour</code>, <code>get_tour_booking</code>, <code>show_media</code></td>
+                <td>Tour item cards, booking summary bar, gallery</td>
+              </tr>
+            </tbody>
+          </table>
+
+          <p><strong>E-commerce WebSocket messages:</strong> The widget listens for <code>t: &quot;show_items&quot;</code> and <code>t: &quot;show_products&quot;</code> (same handler; backend tools often send <code>show_products</code> with <code>products</code>, <code>title</code>, <code>layout</code>). Use <code>TTPEcommerceWidget</code> (or <code>TTPChatWidget</code> with <code>flavor.type: 'ecommerce'</code>) so these handlers are registered. For end-to-end add-to-cart flows (partner API vs Shopify Ajax vs client tools), see <a href="#ecommerce-cart-flow">E-commerce cart flows</a>.</p>
+
+          <p><strong>Desktop voice strip (<code>flavor.callView: 'minimized'</code>):</strong> When <code>flavor.callView</code> is <code>'minimized'</code>, a fixed bottom voice surface is used on viewports wider than 768px. This works <strong>with or without a flavor</strong>: it requires only a <code>flavor</code> object carrying <code>callView: 'minimized'</code> (e.g. <code>flavor: { callView: 'minimized' }</code>, no <code>type</code>/partner needed) — a flavor <code>type</code> is optional. It is a <strong>rounded floating dock</strong> with layered glass styling (rim light, ambient shadow, soft indigo outer glow), an inset transcript “well,” squircle control tiles, and a blurred LIVE capsule—same layout and controls as before. It is centered with a capped width (up to about 720px with horizontal inset) and bottom spacing plus <code>env(safe-area-inset-bottom)</code>. It uses the same tokens as the floating pill (<code>voice.pillGradient</code>, <code>pillTextColor</code>, <code>pillDotColor</code>, <code>endCallButtonColor</code>). Mute, pause, speaker, keyboard (text inject), and end-call align with the in-widget voice UI. The in-panel desktop “active call” UI stays hidden; the floating panel collapses if it was open, and the launcher pill is hidden for the duration of the call. The <strong>“Powered by”</strong> footer (<code>footer.show</code>, <code>footer.brand</code>) is rendered <strong>inside the strip</strong> (below the call controls) for the duration of the call—not as a separate floating pill at the widget corner. Viewports 768px and below skip the strip and use the mobile minimized bar flow instead. A <strong>single transcript line</strong> shows either the assistant (streaming) or the user (speech-to-text interim/final), never both at once; user text uses a warm highlight color and no <code>You:</code> prefix. When the widget <code>language</code> is Hebrew or Arabic (base <code>he</code> / <code>ar</code>) or <code>direction</code> is <code>'rtl'</code>, chrome uses RTL. Transcript lines use explicit <code>dir="rtl"</code> when the string contains Hebrew or Arabic letters (even if the widget Language is English), so neutral punctuation follows the sentence; Latin-only lines use <code>dir="ltr"</code>. Mic/pause/speaker/end layout is unchanged.</p>
+
+          <h2>Configuration</h2>
+          <p>Set the flavor when creating the widget:</p>
+          <pre><code>const widget = new TTPChatWidget({
+  agentId: 'agent_...',
+  appId: 'app_...',
+  flavor: {
+    type: 'pharma',        // 'ecommerce' | 'hotels' | 'pharma' | 'restaurants' | 'tours'
+    partnerId: 'mock-pharm' // partner-specific data source
+  }
+});</code></pre>
+
+          <h2>Pharma Flavor</h2>
+          <p>The pharmacy flavor provides a medication search and prescription management experience.</p>
+          <pre><code>// Pharma configuration
+flavor: {
+  type: 'pharma',
+  partnerId: 'mock-pharm'
+}
+
+// Backend tools injected automatically:
+// - search_medications: Search the medication catalog
+// - add_to_prescription: Add a medication to the prescription
+// - get_prescription: View current prescription contents
+
+// Frontend message types:
+// - show_items: Displays medication cards
+// - prescription_updated: Updates the prescription summary bar</code></pre>
+          <p>The pharma flavor does <strong>not</strong> include gallery support (<code>show_media</code>).</p>
+
+          <h2>Restaurants Flavor</h2>
+          <p>The restaurants flavor provides a menu browsing, ordering, and photo gallery experience.</p>
+          <pre><code>// Restaurant configuration
+flavor: {
+  type: 'restaurants',
+  partnerId: 'mock-restaurant'
+}
+
+// Backend tools injected automatically:
+// - search_menu: Search the restaurant menu
+// - add_to_order: Add a menu item to the order
+// - get_order: View current order contents
+// - show_media: Display restaurant photo gallery
+
+// Frontend message types:
+// - show_items: Displays menu item cards
+// - order_updated: Updates the order summary bar
+// - show_media / dismiss_media: Gallery with dish photos, ambiance, etc.</code></pre>
+          <p>Menu item cards display allergen warnings and dietary tags automatically.</p>
+
+          <h2>Tours Flavor</h2>
+          <p>The tours flavor provides a tour browsing, booking, and photo gallery experience.</p>
+          <pre><code>// Tour configuration
+flavor: {
+  type: 'tours',
+  partnerId: 'mock-tour'
+}
+
+// Backend tools injected automatically:
+// - search_tours: Search available tours and activities by query
+// - book_tour: Book a tour or activity
+// - get_tour_booking: View current booking contents
+// - show_media: Display tour photo gallery
+
+// Frontend message types:
+// - show_items: Displays tour item cards
+// - cart_updated: Updates the booking summary bar
+// - show_media / dismiss_media: Gallery with tour photos, highlights, etc.</code></pre>
+          <p>Tour cards display activity tags and pricing. Reuses the same UI infrastructure as the restaurants flavor.</p>
+        </section>
+
         <!-- Client-Script Tools -->
         <section id="client-script-tools" class="doc-section">
           <h1>Client-Script Tools</h1>
@@ -2717,7 +3650,7 @@ async (ctx) => {
             </thead>
             <tbody>
               <tr><td>Per-step code size</td><td>32 KB</td></tr>
-              <tr><td>Result size</td><td>50 KB serialized (oversize → <code>ok: false, error: "RESULT_TOO_LARGE"</code>)</td></tr>
+              <tr><td>Result size</td><td>512 KB serialized (oversize → <code>ok: false, error: "RESULT_TOO_LARGE"</code>)</td></tr>
               <tr><td>Sync timeout</td><td>1000–15000 ms (default 8000)</td></tr>
               <tr><td>Pending message</td><td>500 chars</td></tr>
             </tbody>
@@ -2795,7 +3728,7 @@ async (ctx) => {
         <!-- VoiceSDK API -->
         <section id="voicesdk" class="doc-section">
           <h1>VoiceSDK Class</h1>
-          <p>Core class for voice interaction functionality.</p>
+          <p>Core class for voice interaction functionality. Server-driven <strong>disclaimer</strong> gating (compliance copy before STT/greeting) is described in detail under <a href="#server-driven-disclaimer">Server-driven disclaimer (voice)</a> and applies when using protocol v2.</p>
 
           <h2>Constructor</h2>
           <pre><code>new VoiceSDK(config)</code></pre>
@@ -2881,7 +3814,7 @@ async (ctx) => {
                 <td><code>outputSampleRate</code></td>
                 <td>number</td>
                 <td>No</td>
-                <td>Output audio sample rate: 8000, 16000, 22050, 24000, 44100, or 48000 Hz (default: 16000)</td>
+                <td>Output audio sample rate: 8000, 16000, 22050, 24000, 44100, or 48000 Hz (default: 24000)</td>
               </tr>
               <tr>
                 <td><code>outputChannels</code></td>
@@ -2945,7 +3878,7 @@ async (ctx) => {
   // Output format (what we want from server)
   outputContainer: 'raw',        // 'raw' or 'wav'
   outputEncoding: 'pcm',          // 'pcm', 'pcmu', 'pcma'
-  outputSampleRate: 44100,       // Higher quality
+  outputSampleRate: 24000,       // Default; typical TTS/server output
   outputChannels: 1,
   outputBitDepth: 16,
   outputFrameDurationMs: 600,    // Frame duration for streaming
@@ -2982,10 +3915,19 @@ voiceSDK.on('formatNegotiated', (format) => {
           <div class="method-card">
             <h3><code>startRecording()</code></h3>
             <p>Start capturing and streaming audio.</p>
+            <p><strong>Disclaimer (v2):</strong> If the server required a disclaimer and <code>disclaimersPending</code> is still <code>true</code>, this throws an <code>Error</code> with <code>error.code === 'DISCLAIMER_PENDING'</code>. Call <code>sendDisclaimerAck(true)</code> first. See <a href="#server-driven-disclaimer">Server-driven disclaimer</a>.</p>
             <p><strong>Returns:</strong> <code>Promise&lt;boolean&gt;</code></p>
             <pre><code>await voiceSDK.startRecording();</code></pre>
           </div>
 
+          <div class="method-card">
+            <h3><code>sendDisclaimerAck(accepted)</code> <span style="font-weight: normal; font-size: 0.9em;">(v2, voice)</span></h3>
+            <p>Sends <code>disclaimer_ack</code> after the user accepts or declines server-shown disclaimer text. Uses <code>disclaimersHash</code> and <code>conversationId</code> from the last <code>hello_ack</code>.</p>
+            <p><strong>Parameters:</strong> <code>accepted</code> (boolean) — <code>true</code> to continue the call, <code>false</code> to decline.</p>
+            <p><strong>Returns:</strong> <code>void</code> (logs and clears <code>disclaimersPending</code> on successful send).</p>
+            <pre><code>voiceSDK.sendDisclaimerAck(true);</code></pre>
+          </div>
+
           <div class="method-card">
             <h3><code>stopRecording()</code></h3>
             <p>Stop capturing audio.</p>
@@ -3000,6 +3942,37 @@ voiceSDK.on('formatNegotiated', (format) => {
             <pre><code>await voiceSDK.toggleRecording();</code></pre>
           </div>
 
+          <div class="method-card">
+            <h3><code>pauseCall()</code></h3>
+            <p>Pause the active call. Stops sending audio, clears the playback queue, and notifies the server to close STT/TTS connections. The WebSocket stays open and conversation history is preserved. A configurable timeout (default 5 minutes) will automatically end the call if not resumed.</p>
+            <p><strong>Returns:</strong> <code>void</code></p>
+            <pre><code>voiceSDK.pauseCall();
+// or via AgentSDK:
+agentSDK.pauseCall();</code></pre>
+          </div>
+
+          <div class="method-card">
+            <h3><code>resumeCall()</code></h3>
+            <p>Resume a paused call. Restarts audio recording and notifies the server to re-create STT/TTS connections. The conversation continues from where it left off with full history.</p>
+            <p><strong>Returns:</strong> <code>void</code></p>
+            <pre><code>voiceSDK.resumeCall();
+// or via AgentSDK:
+agentSDK.resumeCall();</code></pre>
+          </div>
+
+          <div class="method-card">
+            <h3><code>isPaused</code> <span style="font-weight: normal; font-size: 0.9em;">(property)</span></h3>
+            <p>Boolean indicating whether the call is currently paused.</p>
+            <p><strong>Type:</strong> <code>boolean</code></p>
+            <pre><code>if (voiceSDK.isPaused) {
+  console.log('Call is paused');
+}
+// or via AgentSDK:
+if (agentSDK.isPaused) {
+  console.log('Call is paused');
+}</code></pre>
+          </div>
+
           <div class="method-card">
             <h3><code>getStatus()</code></h3>
             <p>Get current connection and recording status.</p>
@@ -3046,7 +4019,7 @@ if (error) {
             <pre><code>const error = voiceSDK.validateOutputFormat({
   container: 'raw',
   encoding: 'pcm',
-  sampleRate: 44100,
+  sampleRate: 24000,
   bitDepth: 16,
   channels: 1
 });
@@ -3187,6 +4160,16 @@ if (error) {
                 <td><code>error</code></td>
                 <td>Emitted when domain is not whitelisted</td>
               </tr>
+              <tr>
+                <td><code>disclaimersRequired</code></td>
+                <td><code>payload</code></td>
+                <td><strong>v2 voice:</strong> Server requires disclaimer acknowledgement. Payload: <code>texts</code>, <code>disclaimersHash</code>, <code>disclaimerTimeoutMs</code>, <code>conversationId</code>. Call <code>sendDisclaimerAck</code> after user decision.</td>
+              </tr>
+              <tr>
+                <td><code>disclaimerRejected</code></td>
+                <td><code>{ code, message }</code></td>
+                <td><strong>v2 voice:</strong> Terminal disclaimer failure from server (<code>DISCLAIMER_DECLINED</code>, <code>DISCLAIMER_TIMEOUT</code>, <code>DISCLAIMER_HASH_MISMATCH</code>). Not used for <code>DISCLAIMER_PENDING</code> (that uses <code>error</code>).</td>
+              </tr>
             </tbody>
           </table>
         </section>
@@ -3956,7 +4939,7 @@ sdk.textToSpeechStream(
     .voiceId("mamre")
     .outputContainer("raw")          // "raw" or "wav"
     .outputEncoding("pcm")           // "pcm", "pcmu", "pcma"
-    .outputSampleRate(16000)         // Hz (8000, 16000, 22050, 44100)
+    .outputSampleRate(24000)         // Hz (8000, 16000, 22050, 24000, 44100, 48000)
     .outputBitDepth(16)              // bits (8, 16, 24)
     .outputChannels(1)               // 1 (mono) or 2 (stereo)
     .outputFrameDurationMs(600)     // ms per frame (for streaming)
@@ -4180,7 +5163,7 @@ TTSRequest request = TTSRequest.builder()
     .speed(1.2)
     .outputContainer("wav")
     .outputEncoding("pcm")
-    .outputSampleRate(44100)
+    .outputSampleRate(24000)
     .outputBitDepth(16)
     .outputChannels(1)
     .build();