Pipecat Client Quickstart

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 quickstart guide will help you build your first Pipecat voice AI bot with a React front-end and run it locally. You’ll create a simple conversational agent that you connect and talk to in real-time via your browser.

The CLI generates React and vanilla JavaScript projects. For React Native, iOS, Android, or C++, see Building a Voice UI to get started without the CLI.

Prerequisites

Python 3.11+ and uv
Node.js 18+

Step 1: Scaffold your project

# Install the Pipecat CLI
uv tool install "pipecat-ai[cli]"

# Start your project
pipecat init

When init asks how you want to build, choose Scaffold a runnable bot now. The wizard will guide you through the setup. Choose the following options:

This quickstart uses the interactive pipecat init wizard so you end up with the same project this guide walks through below. When you’re ready to build your own bot, we recommend driving development with a coding agent — see Build Your Next Bot.

Project name: my-voice-app
Bot type: Web/Mobile
Client framework: React
React dev server: Vite
Transport: SmallWebRTC

The rest is up to you! The CLI generates a complete project with two main directories:

bot/ — a Python Pipecat bot
client/ — a React front-end with voice UI components

The CLI’s React template currently uses the legacy Voice UI Kit npm package. Pipecat UI replaces it with components installed as source through the shadcn CLI. The walkthrough below describes the existing template; see Pipecat UI for new UI development.

Step 2: Start the bot

cd my-voice-app/bot
cp .env.example .env       # add your API keys
uv sync
uv run bot.py

The bot starts at http://localhost:7860.

Step 3: Start the client

cd ../client
npm install
npm run dev

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

First run note: The initial startup may take ~20 seconds as Pipecat downloads required models and imports. Subsequent runs will be much faster.

🎉 Success! Your bot is running locally. Now let’s deploy it to production so others can use it.

Understanding the Quickstart Client

The generated React app uses the legacy Voice UI Kit API. These components differ from the new Pipecat UI registry. Here’s what each file does:src/config.ts — transport configuration. By default it uses SmallWebRTC for local development. To switch to Daily for production, add your Daily credentials and update AVAILABLE_TRANSPORTS.

const botStartUrl =
  import.meta.env.VITE_BOT_START_URL || "http://localhost:7860/start";

export const DEFAULT_TRANSPORT: TransportType = "smallwebrtc";

src/main.tsx — entry point. PipecatAppBase handles transport creation, connection lifecycle, loading states, and errors, passing a ready client down to your app via a render prop.

<PipecatAppBase connectParams={connectParams} transportType={transportType}>
  {({ client, handleConnect, handleDisconnect, error }) =>
    !client ? <SpinLoader /> :
    error ? <ErrorCard>{error}</ErrorCard> :
    <App client={client} handleConnect={handleConnect} ... />
  }
</PipecatAppBase>

src/components/App.tsx — the UI. Built from legacy Voice UI Kit components:

Component	What it does
`ConnectButton`	Connect/disconnect button with built-in loading and error states
`UserAudioControl`	Mic mute/unmute toggle
`ConversationPanel`	Live transcript of the conversation
`EventsPanel`	Real-time stream of RTVI events — useful during development

Deploying to production

The .env.example file shows the production configuration. Point VITE_BOT_START_URL at your deployed bot’s start endpoint:

# Pipecat Cloud
VITE_BOT_START_URL="https://api.pipecat.daily.co/v1/public/{agentName}/start"
VITE_BOT_START_PUBLIC_API_KEY="your-public-api-key"

The client app is a static site — build it with npm run build and deploy to any static hosting provider (Vercel, Netlify, S3, etc.).

Next steps

Pipecat UI

Build your UI with customizable React components from the shadcn registry

Building a Voice UI

Build a React voice app from scratch — understand the SDK without abstractions

Core Concepts

Understand transports, sessions, events, and media

Deploy your bot

Deploy to Pipecat Cloud for production

Get Started

Core Concepts

Guides

Pipecat UI

Pipecat Client Quickstart

Prerequisites

Step 1: Scaffold your project

Step 2: Start the bot

Step 3: Start the client

Understanding the Quickstart Client

Deploying to production

Next steps

Pipecat UI

Building a Voice UI

Core Concepts

Deploy your bot

​Prerequisites

​Step 1: Scaffold your project

​Step 2: Start the bot

​Step 3: Start the client

​Understanding the Quickstart Client

​Deploying to production

​Next steps

Pipecat UI

Building a Voice UI

Core Concepts

Deploy your bot

Prerequisites

Step 1: Scaffold your project

Step 2: Start the bot

Step 3: Start the client

Understanding the Quickstart Client

Deploying to production

Next steps