> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinnest.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Widget

> Add a browser-based voice call button to your website so visitors can speak with your AI agent directly.

# Voice Widget

Let website visitors talk to your voice agent directly from the browser — no phone number needed. The voice widget adds a call button to your site that connects users via WebRTC for real-time voice conversations.

## Quick Setup

Add the voice widget to any webpage by setting the `data-widget-type` to `"voice"`:

```html theme={null}
<script
  src="https://api.thinnest.ai/embed/widget.js"
  data-publishable-key="pk_live_abc123xyz"
  data-agent-id="YOUR_AGENT_PUBLIC_ID"
  data-widget-type="voice"
  async
></script>
```

A floating call button appears. When clicked, the browser connects to your voice agent via WebRTC.

## How It Works

```
User clicks voice button on your website
        ↓
Browser requests microphone permission
        ↓
WebRTC connection established with thinnestAI
        ↓
User speaks → STT → Agent processes → TTS → User hears response
        ↓
Call ends when user clicks "Hang up"
```

No phone network is involved — audio travels directly over the internet. Works on all modern browsers (Chrome, Firefox, Safari, Edge).

## Combined Chat + Voice Widget

Deploy both chat and voice on the same page — the embed widget supports a combined mode:

```html theme={null}
<!-- Widget with both chat and voice enabled -->
<script
  src="https://api.thinnest.ai/embed/widget.js"
  data-publishable-key="pk_live_abc123xyz"
  data-agent-id="YOUR_AGENT_PUBLIC_ID"
  data-widget-type="combined"
  async
></script>
```

Users can choose to type or speak. The widget shows both a text input and a microphone button.

## Custom Integrations (JavaScript SDK)

If you'd like to build a completely custom voice UI rather than use the drop-in widget, you can use our dedicated **Voice SDK**.

### Installation

```bash theme={null}
npm install @thinnest-ai/voice-sdk
```

### Basic Usage

```javascript theme={null}
import ThinnestVoice from "@thinnest-ai/voice-sdk";

const voice = new ThinnestVoice("YOUR_API_KEY");

// Start talking to your agent
await voice.start("YOUR_AGENT_PUBLIC_ID");

// Listen for transcripts
voice.on("transcript", (msg) => {
  console.log(`${msg.role}: ${msg.text}`);
});

// End the call
voice.stop();
```

## React Example

For React applications building custom voice interfaces:

```tsx theme={null}
import { useState, useEffect, useRef } from "react";
import ThinnestVoice from "@thinnest-ai/voice-sdk";

function VoiceAgent({ agentId }: { agentId: string }) {
  const voiceRef = useRef<ThinnestVoice>();
  const [status, setStatus] = useState("idle");

  useEffect(() => {
    // Initialize with your API key
    voiceRef.current = new ThinnestVoice("YOUR_API_KEY");

    voiceRef.current.on("status-change", ({ status }) => setStatus(status));
    
    return () => voiceRef.current?.stop();
  }, []);

  const toggle = async () => {
    if (status === "active") {
      await voiceRef.current?.stop();
    } else {
      await voiceRef.current?.start(agentId);
    }
  };

  return (
    <div>
      <button onClick={toggle}>
        {status === "active" ? "End Call" : "Start Call"}
      </button>
      <p>Status: {status}</p>
    </div>
  );
}
```

## Browser Requirements

| Browser       | Supported | Notes                          |
| ------------- | --------- | ------------------------------ |
| Chrome 74+    | Yes       | Full support                   |
| Firefox 66+   | Yes       | Full support                   |
| Safari 14.1+  | Yes       | Requires user gesture to start |
| Edge 79+      | Yes       | Full support                   |
| Mobile Chrome | Yes       | Works on Android               |
| Mobile Safari | Yes       | iOS 14.5+                      |

### Permissions

The browser will ask for microphone permission on the first call. Users must grant access for the voice SDK to work.

## Audio Quality

The voice engine uses:

* **Opus codec** for efficient audio compression
* **Echo cancellation** built into WebRTC
* **Noise suppression** for cleaner input
* **Adaptive bitrate** based on network conditions

For best quality, recommend users use headphones or a quiet environment.

## vs Phone Calls

| Feature      | Voice Widget             | Phone Calls              |
| ------------ | ------------------------ | ------------------------ |
| Setup        | Script tag on website    | Twilio/Vobiz number      |
| Cost         | No telephony charges     | Per-minute carrier rates |
| Reach        | Website visitors only    | Anyone with a phone      |
| Quality      | High (WebRTC)            | Standard (PSTN)          |
| Lead capture | Session-based            | Phone number captured    |
| Mobile       | Works in mobile browsers | Native phone experience  |

Use the voice widget for website visitors. Use phone calls when you need to reach users on their phones.