Skip to main content
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.
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. 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.

​
Pipecat Cloud Configuration

​
1. Get Your Organization Name

Retrieve your Pipecat Cloud organization name using the Pipecat CLI: 
$ pipecat cloud organizations list
This command will output a list of organizations associated with your account. For example: 
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: 
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)
Using Regional EndpointsIf 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_NAMEFor example, for Europe: wss://eu-central.api.pipecat.daily.co/ws/plivo?serviceHost=my-agent.my-orgLearn more about regional endpoints.

​
3. Deploy Your XML Server

Install dependencies and run your server: 
pip install fastapi uvicorn
python server.py
For local testing, use ngrok to make your server publicly accessible: 
ngrok http 7860
This will give you a public URL like https://abc123.ngrok.io.
Use the --subdomain flag with ngrok to keep your URL consistent across restarts.
For production, deploy your XML server to a reliable hosting platform.

​
4. Configure Plivo

Purchase a phone number from Plivo 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.