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

# Plivo Websocket Transport

> Using Plivo's WebSocket Transport for your Pipecat Cloud agents

<Note>
  This guide covers Pipecat Cloud-specific configuration for Plivo WebSocket
  integration. For a complete guide including dial-in, dial-out, and advanced
  features, see the [Plivo WebSocket Integration
  guide](/pipecat/telephony/plivo-websockets).
</Note>

Native support for Plivo's WebSocket Transport with Pipecat Cloud allows you to connect your AI agents with Plivo's voice infrastructure. This integration enables your Pipecat bots to handle real phone calls using Plivo's WebSocket streaming.

## How It Works

Pipecat Cloud implements Plivo's bidirectional [Media Streaming protocol](https://www.plivo.com/docs/voice/guides/stream-audio/). While audio streams flow through WebSockets, the call session is controlled by XML responses that tell Plivo how to handle each call.

When Pipecat Cloud receives an incoming WebSocket connection from Plivo, it processes the `start` message to initialize a new bot instance. All WebSocket messages are forwarded to your bot, including call information such as the caller's number and call UUID. This allows your bot to leverage Plivo's Voice API for advanced call control - such as recording conversations, transferring to human agents, or implementing complex call flows.

## Prerequisites

Before setting up this integration, ensure you have:

* A Plivo account with voice capabilities
* A Pipecat Cloud account with a Plivo WebSocket-compatible bot
* A web server to host XML responses (we'll show you how to set this up)

A ready-to-build example of a Plivo websockets bot with complete source code is available in the [pipecat-examples repo](https://github.com/pipecat-ai/pipecat-examples/tree/main/plivo-chatbot).

## Pipecat Cloud Configuration

### 1. Get Your Organization Name

Retrieve your Pipecat Cloud organization name using the Pipecat CLI:

```bash theme={null}
$ pipecat cloud organizations list
```

This command will output a list of organizations associated with your account. For example:

```bash theme={null}
Organization        Name
──────────────────────────────────────
Default Workspace   three-random-words-randomnumber (active)
```

### 2. Set Up an XML Server

Unlike Twilio's TwiML Bins, Plivo requires a web server to host your XML responses. Create a file called `server.py`:

```python theme={null}
from fastapi import FastAPI, Query, HTTPException
from starlette.responses import Response
import uvicorn

app = FastAPI(title="Plivo XML Server")

@app.get("/plivo-xml")
async def plivo_xml(
    agent: str = Query(..., description="Agent name"),
    org: str = Query(..., description="Organization name"),
):
    """
    Returns XML for Plivo to start WebSocket streaming to Pipecat Cloud
    Example: /plivo-xml?agent=my-bot&org=my-org-123
    """
    if not agent or not org:
        raise HTTPException(status_code=400, detail="Both 'agent' and 'org' parameters are required")

    xml = f"""<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Stream bidirectional="true" keepCallAlive="true" contentType="audio/x-mulaw;rate=8000">
    wss://api.pipecat.daily.co/ws/plivo?serviceHost={agent}.{org}
  </Stream>
</Response>"""

    return Response(content=xml, media_type="application/xml")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=7860)
```

<Note>
  **Using Regional Endpoints**

  If you deployed your agent to a specific region, use the regional WebSocket endpoint:

  `wss://{region}.api.pipecat.daily.co/ws/plivo?serviceHost=AGENT_NAME.ORGANIZATION_NAME`

  For example, for Europe: `wss://eu-central.api.pipecat.daily.co/ws/plivo?serviceHost=my-agent.my-org`

  Learn more about [regional endpoints](/pipecat-cloud/guides/regions#regional-websocket-endpoints).
</Note>

### 3. Deploy Your XML Server

Install dependencies and run your server:

```bash theme={null}
uv add fastapi uvicorn
python server.py
```

For local testing, use ngrok to make your server publicly accessible:

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

This will give you a public URL like `https://abc123.ngrok.io`.

<Tip>
  Use the `--subdomain` flag with ngrok to keep your URL consistent across
  restarts.
</Tip>

For production, deploy your XML server to a reliable hosting platform.

### 4. Configure Plivo

[Purchase a phone number from Plivo](https://www.plivo.com/docs/numbers/quickstart/) if you haven't already, then:

1. Navigate to Voice → XML in your Plivo dashboard

2. Select Add New Application

3. Enter a name for your application (e.g., "Pipecat WebSocket")

4. Set the **Answer URL** to your server URL with agent and organization parameters:

   ```
   https://your-server.com/plivo-xml?agent=AGENT_NAME&org=ORGANIZATION_NAME
   ```

   * Replace `AGENT_NAME` with your deployed bot's name (e.g., `my-first-agent`)
   * Replace `ORGANIZATION_NAME` with your organization name from step 1 (e.g., `three-random-words-randomnumber`)

5. Set **HTTP Method** to `GET`

6. Click Create Application

### 5. Assign to Your Phone Number

1. Navigate to Phone Numbers and select your phone number
2. Select XML Application as the Application Type
3. Select your XML Application from the Plivo Application dropdown
4. Click Update to apply your changes

## Testing Your Integration

To test your integration, simply dial your Plivo phone number from any phone. The call will connect to your Pipecat Cloud bot, which will respond according to your bot's configuration.

## Next Steps

For complete implementation details including dial-out and advanced call control features, see the [Plivo WebSocket Integration guide](/pipecat/telephony/plivo-websockets).