Building a Voice UI

Build a voice application from scratch using the Pipecat client SDK.

You are currently viewing the React version of this page. Use the dropdown to the right to customize this page for your client framework.

This guide walks through building a React voice app without any UI abstractions — just the Pipecat React SDK directly. You’ll see exactly how the client, provider, hooks, and audio output fit together, which is useful whether you’re building a fully custom UI or want to understand what the CLI-generated app is doing under the hood.

Prerequisites

• Node.js 18+
• A running Pipecat bot

Don't have a bot yet?

Follow the Pipecat server quickstart to get a bot running locally at http://localhost:7860.

Installation

Create a new React project and install the SDK, React bindings, and SmallWebRTC transport:

npm create vite@latest my-voice-app -- --template react-ts
cd my-voice-app
npm install @pipecat-ai/client-js @pipecat-ai/client-react @pipecat-ai/small-webrtc-transport

SmallWebRTC is ideal for development — no third-party account needed. For production, swap in the Daily transport, which provides global infrastructure, echo cancellation, and more.

Step 1: Create the client

Create the PipecatClient once at the module level with SmallWebRTC as the transport. Pass it to PipecatClientProvider so every component in your app can access it. PipecatClientAudio mounts a hidden <audio> element for the bot’s voice output.

Replace src/main.tsx with:

import React from "react";
import ReactDOM from "react-dom/client";
import { PipecatClient } from "@pipecat-ai/client-js";
import { SmallWebRTCTransport } from "@pipecat-ai/small-webrtc-transport";
import { PipecatClientAudio, PipecatClientProvider } from "@pipecat-ai/client-react";
import App from "./App";

const client = new PipecatClient({
  transport: new SmallWebRTCTransport(),
  enableMic: true,
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <PipecatClientProvider client={client}>
    <App />
    <PipecatClientAudio />
  </PipecatClientProvider>
);

Two things to note here:

• PipecatClientProvider makes the client available to all child components via hooks.
• PipecatClientAudio is a headless component that mounts the bot’s audio output. It needs to live inside the provider, but has no visible UI.

Step 2: Build the app

Replace src/App.tsx with:

import { useCallback } from "react";
import { RTVIEvent } from "@pipecat-ai/client-js";
import {
  usePipecatClient,
  usePipecatClientTransportState,
  usePipecatConversation,
  useRTVIClientEvent,
} from "@pipecat-ai/client-react";

export default function App() {
  const client = usePipecatClient();
  const transportState = usePipecatClientTransportState();
  const { messages } = usePipecatConversation();

  const isConnected = transportState === "ready";
  const isConnecting = ["authenticating", "connecting", "connected"].includes(transportState);

  useRTVIClientEvent(
    RTVIEvent.Error,
    useCallback((error) => console.error("Bot error:", error), [])
  );

  const handleConnect = async () => {
    await client.connect({ webrtcRequestParams: { endpoint: "http://localhost:7860/api/offer" } });
  };

  return (
    <div style={{ maxWidth: 600, margin: "40px auto", fontFamily: "sans-serif" }}>
      <h1>Pipecat Voice App</h1>

      <div style={{ marginBottom: 16 }}>
        <button
          onClick={isConnected ? () => client.disconnect() : handleConnect}
          disabled={isConnecting}
        >
          {isConnected ? "Disconnect" : isConnecting ? "Connecting…" : "Connect"}
        </button>
        <span style={{ marginLeft: 12, color: "#666" }}>
          {transportState}
        </span>
      </div>

      <ul style={{ listStyle: "none", padding: 0 }}>
        {messages.map((msg, i) => (
          <li key={i} style={{ marginBottom: 8 }}>
            <strong>{msg.role === "user" ? "You" : "Bot"}:</strong>{" "}
            {msg.parts?.map((part, j) => (
              <span key={j}>
                {typeof part.text === "string"
                  ? part.text
                  : part.text.spoken + part.text.unspoken}
              </span>
            ))}
          </li>
        ))}
      </ul>
    </div>
  );
}

Step 3: Run it

Start your Pipecat bot (if it isn’t already running), then start the app:

npm run dev

Open http://localhost:5173, click Connect, allow microphone access, and start talking.

What each piece does

Piece	Role
PipecatClient	Manages the connection and session lifecycle
SmallWebRTCTransport	Handles the WebRTC peer connection to your bot
PipecatClientProvider	Shares the client instance via React context
PipecatClientAudio	Mounts a hidden <audio> element for bot voice output
usePipecatClientTransportState	Tracks connection state for button and status display
usePipecatConversation	Streams the live transcript of the conversation
useRTVIClientEvent	Subscribes to a specific event — here, errors

Next steps

Session Lifecycle

Understand connection states, reconnection, and teardown

Events & Callbacks

The full event system — what fires, when, and how to handle it

Custom Messaging

Send and receive custom messages between client and bot

React SDK Reference

All hooks, components, and types