​
Overview

PlivoFrameSerializer enables integration with Plivo’s Audio Streaming WebSocket protocol, allowing your Pipecat application to handle phone calls via Plivo’s voice services.

​
Features

  • Bidirectional audio conversion between Pipecat and Plivo
  • DTMF (touch-tone) event handling
  • Automatic call termination via Plivo’s REST API
  • μ-law audio encoding/decoding

​
Installation

The PlivoFrameSerializer does not require any additional dependencies beyond the core Pipecat library.

​
Configuration

​
Constructor Parameters

​
stream_id
str
required

The Plivo Stream ID

​
call_id
Optional[str]
default:"None"

The associated Plivo Call ID (required for auto hang-up)

​
auth_id
Optional[str]
default:"None"

Plivo auth ID (required for auto hang-up)

​
auth_token
Optional[str]
default:"None"

Plivo auth token (required for auto hang-up)

​
params
InputParams
default:"InputParams()"

Configuration parameters

​
InputParams Configuration

​
plivo_sample_rate
int
default:"8000"

Sample rate used by Plivo (typically 8kHz)

​
sample_rate
int | None
default:"None"

Optional override for pipeline input sample rate

​
auto_hang_up
bool
default:"True"

Whether to automatically terminate call on EndFrame

​
Basic Usage

from pipecat.serializers.plivo import PlivoFrameSerializer
from pipecat.transports.network.fastapi_websocket import (
    FastAPIWebsocketTransport,
    FastAPIWebsocketParams
)

# Extract required values from Plivo WebSocket connection
stream_id = start_message["start"]["streamId"]
call_id = start_message["start"]["callId"]

# Create serializer
serializer = PlivoFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,
    auth_id="your_plivo_auth_id",
    auth_token="your_plivo_auth_token"
)

# Use with FastAPIWebsocketTransport
transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        vad_analyzer=SileroVADAnalyzer(),
        serializer=serializer,
    )
)

​
Hang-up Functionality

When auto_hang_up is enabled, the serializer will automatically hang up the Plivo call when an EndFrame or CancelFrame is processed, using Plivo’s REST API:

# Properly configured with hang-up support
serializer = PlivoFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,                             # Required for auto hang-up
    auth_id=os.getenv("PLIVO_AUTH_ID"),          # Required for auto hang-up
    auth_token=os.getenv("PLIVO_AUTH_TOKEN"),    # Required for auto hang-up
)

​
Server Code Example

Here’s a complete example of handling a Plivo WebSocket connection:

from fastapi import FastAPI, WebSocket
from pipecat.serializers.plivo import PlivoFrameSerializer
import json
import os

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()

    # Read the start message from Plivo
    start_data = websocket.iter_text()
    start_message = json.loads(await start_data.__anext__())

    # Extract Plivo-specific IDs from the start event
    start_info = start_message.get("start", {})
    stream_id = start_info.get("streamId")
    call_id = start_info.get("callId")

    # Create serializer with authentication for auto hang-up
    serializer = PlivoFrameSerializer(
        stream_id=stream_id,
        call_id=call_id,
        auth_id=os.getenv("PLIVO_AUTH_ID"),
        auth_token=os.getenv("PLIVO_AUTH_TOKEN"),
    )

    # Continue with transport and pipeline setup...

​
Plivo XML Configuration

To enable audio streaming with Plivo, you’ll need to configure your Plivo application to return appropriate XML:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Stream
    keepCallAlive="true"
    bidirectional="true"
    contentType="audio/x-mulaw;rate=8000"
  >
    wss://your-websocket-url/ws
  </Stream>
</Response>

The bidirectional="true" attribute is required for two-way audio communication, and keepCallAlive="true" prevents the call from being disconnected after XML execution.

​
Key Differences from Twilio

  • Stream Identifier: Plivo uses streamId instead of streamSid
  • Call Identifier: Plivo uses callId instead of callSid
  • XML Structure: Plivo uses <Stream> element directly instead of <Connect><Stream>
  • Authentication: Plivo uses Auth ID and Auth Token instead of Account SID and Auth Token

See the Plivo Chatbot example for a complete implementation.