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

# Build a browser voice client

> For phone calls managed by Voiceflow, use Make your first phone call. This sample is for an application that owns microphone capture and playback.

For phone calls managed by Voiceflow, use [Make your first phone call](/docs/guides/studio/voice/first-phone-call). This sample is for an application that owns microphone capture and playback.

## Before you begin

- Node.js 20.19+ and a browser supporting AudioWorklet, microphone access and a 16 kHz AudioContext.
- A Voiceflow project with **public API access**, a standard text model with TTS, and its project ID and Environment alias.
- HTTPS or localhost for microphone access. Never place a private Voiceflow API key in browser code.

The sample buffers each complete MP3 message before decoding; it does not implement a low-latency streaming MP3 decoder or realtime-model PCM output. Private projects need an authenticated server-side audio relay; the [connection reference](/docs/api-reference/conversations-api/interact-socket#client-start) defines its authentication.

## Run and test the client

### 1. Download and run the example

[Download the browser voice example](/docs/examples/voice-client.zip) and unzip it, then run:

```bash title="Run locally"
cd voice-client
npm install
npm run dev
```

Open the localhost address printed by Vite. The [source](/docs/examples/voice-client/main.js) and [audio helpers](/docs/examples/voice-client/audio.mjs) are included in the download.

### 2. Connect your project

Enter the project ID and Environment alias, then click **Start conversation** and allow microphone access. The app registers its listeners before connecting, creates the session, starts recognition in server-managed turns and sends one launch action.

### 3. Speak and interrupt

Ask for a task your agent can complete. Microphone samples are converted to signed 16-bit little-endian mono PCM at 16 kHz and sent only after `asr.started` acknowledges that format. Replies are decoded and played in order; `playback.idle` waits for action completion and finished audio. Speak during a reply to verify `asr.barge-in` clears active and queued output.

### 4. Stop and restart

Click **End conversation**. The app stops recognition, microphone tracks and playback, closes the audio contexts and disconnects the socket. This stops the local client; disconnect is not a remote session-termination guarantee. Starting again uses a new user identity and creates a new conversation. Follow the [resumption sequence](/docs/api-reference/conversations-api/interact-socket#reconnect-after-an-interruption) to implement durable sessions.

## Verify the result

You should see committed recognition text, hear ordered agent replies, hear old audio stop when interrupted, and see the microphone indicator turn off when you end the conversation. Local automated checks exercise synthetic audio, queue cancellation and socket sequences; they do not replace a real microphone-to-agent test.

## Handle errors

Check browser permission and the selected Environment first. The example reports recognition, runtime, playback and connection errors and releases resources. It does not silently reconnect or replay an uncertain action. Use [Voice troubleshooting](/docs/api-reference/agent-runtime/voice/troubleshooting) and [Errors and recovery](/docs/api-reference/agent-runtime/voice/recovery) when adding production recovery.
