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

# Pipecat Overview

> Build AI voice agents with Pipecat and Plivo Audio Streaming

[Pipecat](https://www.pipecat.ai/) is an open-source framework for building conversational AI agents. It orchestrates speech-to-text (STT), language models (LLM), and text-to-speech (TTS) services into a unified pipeline.

Connect Plivo Audio Streaming to Pipecat to build AI voice agents that handle inbound and outbound phone calls.

***

## How It Works

Pipeline

Pipecat

<ol>
  <li>
    Phone Call
  </li>

  <li>
    Plivo

    WebSocket
  </li>

  <li>
    WebSocket
    Stream
  </li>

  <li>
    Pipecat
    Orchestrator
  </li>

  <li>
    AI Services

    STT
    LLM
    TTS
  </li>
</ol>

The pipeline branches at **AI Services** into speech-to-text (Deepgram), an LLM (OpenAI/Gemini), and text-to-speech (Cartesia/ElevenLabs).

1. **Plivo** handles phone call routing and streams real-time audio over WebSocket
2. **Pipecat** receives audio and orchestrates the AI pipeline
3. **STT service** converts speech to text
4. **LLM** processes the text and generates a response
5. **TTS service** converts the response back to speech
6. **Plivo** plays the audio to the caller

***

## Choose Your Stack

Pipecat supports multiple AI service combinations. Choose based on your requirements:

### Standard Pipelines (STT → LLM → TTS)

| Guide | STT | LLM | TTS | Best For |
| - | - | - | - | - |
| [OpenAI + Cartesia](https://plivo.com/docs/voice-agents/audio-streaming/integration-guides/pipecat/openai-cartesia.md) | Deepgram | OpenAI GPT-4o | Cartesia | Low latency, expressive voices |
| [OpenAI + ElevenLabs](https://plivo.com/docs/voice-agents/audio-streaming/integration-guides/pipecat/openai-elevenlabs.md) | Deepgram | OpenAI GPT-4o | ElevenLabs | Natural voices, voice cloning |
| [Gemini + Cartesia](https://plivo.com/docs/voice-agents/audio-streaming/integration-guides/pipecat/gemini-cartesia.md) | Deepgram | Google Gemini | Cartesia | Cost-effective, fast responses |
| [Gemini + ElevenLabs](https://plivo.com/docs/voice-agents/audio-streaming/integration-guides/pipecat/gemini-elevenlabs.md) | Deepgram | Google Gemini | ElevenLabs | Balance of cost and voice quality |

### Speech-to-Speech (Direct Audio Processing)

| Guide | Model | Best For |
| - | - | - |
| [OpenAI Realtime](https://plivo.com/docs/voice-agents/audio-streaming/integration-guides/pipecat/openai-realtime.md) | GPT-4o Realtime | Lowest latency, native multimodal |
| [Gemini Live](https://plivo.com/docs/voice-agents/audio-streaming/integration-guides/pipecat/gemini-live.md) | Gemini Live | Multimodal with video support |

Speech-to-speech models process audio directly without intermediate text conversion, resulting in lower latency and more natural conversations.

***

## Prerequisites

| Requirement | Description |
| - | - |
| **Plivo Account** | [Sign up](https://cx.plivo.com/signup) and get Auth ID and Auth Token |
| **Phone Number** | [Purchase a voice-enabled number](https://cx.plivo.com/phone-numbers) |
| **Pipecat** | Install via `pip install pipecat-ai` |
| **AI Service Accounts** | Credentials for your chosen STT, LLM, and TTS providers |

***

## Quick Start

### 1. Clone the Examples

```bash theme={null}
git clone https://github.com/pipecat-ai/pipecat-examples.git
cd pipecat-examples/plivo-chatbot
```

### 2. Choose Inbound or Outbound

* **Inbound calls**: `cd inbound` - Receive calls on your Plivo number
* **Outbound calls**: `cd outbound` - Initiate calls programmatically

### 3. Configure Environment

```bash theme={null}
cp env.example .env
```

Edit `.env` with your credentials (varies by provider stack).

### 4. Start the Server

```bash theme={null}
uv sync && uv run server.py
```

### 5. Expose for Development (Inbound Only)

```bash theme={null}
ngrok http 7860
```

Configure your Plivo number's Answer URL to `https://your-ngrok-url.ngrok.io/`

***

## Inbound vs Outbound Calls

### Inbound Calls

Your Plivo number receives calls and connects them to your Pipecat bot.

**Setup:**

1. Configure Answer URL on your Plivo number
2. Plivo sends call to your server
3. Server returns XML with `<Stream>` element
4. WebSocket connection established with Pipecat

### Outbound Calls

Your application initiates calls to phone numbers.

**Setup:**

1. Start your Pipecat server
2. Call the `/start` endpoint with target phone number
3. Plivo places the call and connects to your bot

```bash theme={null}
curl -X POST http://localhost:7860/start \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+1234567890"}'
```

Pass custom data to your bot:

```bash theme={null}
curl -X POST http://localhost:7860/start \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890",
    "user_name": "John",
    "context": "appointment reminder"
  }'
```

Access this data in your bot via `runner_args.body`.

***

## Troubleshooting

| Issue | Solution |
| - | - |
| Call doesn't connect | Verify ngrok URL matches Plivo Answer URL |
| No audio | Check WebSocket connection in Pipecat logs |
| Bot not responding | Verify AI service API keys in `.env` |
| Authentication errors | Check Plivo Auth ID and Token |

**Debug logs:**

* Server logs: Terminal running `server.py`
* Bot logs: `bot_<room_name>.log` files
* Plivo logs: [Console > Logs > Calls](https://cx.plivo.com/sip-trunking)

***

## Related

> [card] [Pipecat Documentation](https://docs.pipecat.ai/)
>
> Complete Pipecat setup

> [card] [Pipecat Plivo Examples](https://github.com/pipecat-ai/pipecat-examples/tree/main/plivo-chatbot)
>
> Source code

> [card] [Audio Streaming Overview](https://plivo.com/docs/voice-agents/audio-streaming/overview.md)
>
> Plivo Audio Streaming docs