Skip to main content

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":
<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:
<!-- 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

npm install @thinnest-ai/voice-sdk

Basic Usage

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:
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

BrowserSupportedNotes
Chrome 74+YesFull support
Firefox 66+YesFull support
Safari 14.1+YesRequires user gesture to start
Edge 79+YesFull support
Mobile ChromeYesWorks on Android
Mobile SafariYesiOS 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

FeatureVoice WidgetPhone Calls
SetupScript tag on websiteTwilio/Vobiz number
CostNo telephony chargesPer-minute carrier rates
ReachWebsite visitors onlyAnyone with a phone
QualityHigh (WebRTC)Standard (PSTN)
Lead captureSession-basedPhone number captured
MobileWorks in mobile browsersNative phone experience
Use the voice widget for website visitors. Use phone calls when you need to reach users on their phones.