In this quickstart, we’ll create a simple conversational bot that greets users when they join and exits when they leave. This example demonstrates the core components of a Pipecat application with a streamlined setup.

​
Set up your project

​
Create a project directory

mkdir pipecat-quickstart && cd pipecat-quickstart

​
Set up a virtual environment

python3 -m venv env
source env/bin/activate

​
Download the example files

curl -O https://raw.githubusercontent.com/pipecat-ai/pipecat/main/examples/foundational/01-say-one-thing.py
curl -O https://raw.githubusercontent.com/pipecat-ai/pipecat/main/examples/foundational/run.py
curl -O https://raw.githubusercontent.com/pipecat-ai/pipecat/main/examples/foundational/requirements.txt

​
Install dependencies

pip install -r requirements.txt

​
Configure the environment

Create a .env file with your Cartesia API key:

echo "CARTESIA_API_KEY=your_cartesia_api_key" > .env

Replace your_cartesia_api_key with the actual API key you created during the installation step.

​
Run the example

Start the bot with this command:

python 01-say-one-thing.py

You’ll see a URL (typically http://localhost:7860) in the console output. Open this URL in your browser to join the session. The bot will automatically join, greet you, and then disconnect.

​
Understanding the code

Let’s examine the key components of 01-say-one-thing.py:

# Configure the SmallWebRTCTransport for WebRTC communication
# - WebRTC connection object provided by run.py
# - Enable audio output for text-to-speech playback via the Transport Parameters
transport = SmallWebRTCTransport(
    webrtc_connection=webrtc_connection,
    params=TransportParams(
        audio_out_enabled=True,
    ),
)

# Initialize Cartesia's text-to-speech service
# Using a pre-selected British female voice
# You can find other voices at https://play.cartesia.ai/voices
tts = CartesiaTTSService(
    api_key=os.getenv("CARTESIA_API_KEY"),
    voice_id="79a125e8-cd45-4c13-8a67-188112f4dd22",  # British Reading Lady
)

# Create PipelineTask containing the Pipeline
# The Pipeline processes text into speech and play it
# 1. tts: Converts text messages into audio
# 2. transport.output(): Sends audio into the WebRTC session
task = PipelineTask(Pipeline([tts, transport.output()]))

# When the client connects:
# - Generate a greeting message
# - Queue it for text-to-speech conversion
# - Queue an EndFrame to shut down the pipeline when done
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, client):
    await task.queue_frames([TTSSpeakFrame(f"Hello there!"), EndFrame()])

# Create a pipeline runner and run the pipeline task
runner = PipelineRunner(handle_sigint=False)
await runner.run(task)

​
Customize the example

Try these simple modifications to enhance your bot:

​
Next steps

Try more examples

Explore our GitHub repository with more sophisticated examples

Core concepts

Deepen your understanding of Pipecat’s architecture and components

Supported services

Integrate additional AI services like OpenAI, Anthropic, or Deepgram

Join our community

Get help, share projects, and connect with other Pipecat developers