Bandwidth

Overview

BandwidthFrameSerializer is a FrameSerializer that converts between Pipecat frames and Bandwidth Programmable Voice’s bidirectional WebSocket media stream protocol. Plug it into a FastAPIWebsocketTransport to use Bandwidth as the telephony layer for your Pipecat voice bots.

Source Repository

Source code, examples, and issues for the Bandwidth integration

PyPI Package

The pipecat-bandwidth package on PyPI

Bandwidth StartStream BXML

Bandwidth’s media-stream protocol reference

Bandwidth Voice API

Manage credentials and calls via the Bandwidth Voice API

Installation

This is a community-maintained package distributed separately from pipecat-ai:

uv add pipecat-bandwidth

Prerequisites

Bandwidth Account Setup

Before using BandwidthFrameSerializer, you need:

Bandwidth Account: Sign up at Bandwidth
Programmable Voice: A phone number and application configured for Programmable Voice with a <StartStream mode="bidirectional"> BXML response
OAuth 2.0 Credentials: A Client ID and Client Secret for the Bandwidth Voice API (required for auto hang-up)

Required Environment Variables

BANDWIDTH_CLIENT_ID: OAuth 2.0 Client ID for Bandwidth API authentication
BANDWIDTH_CLIENT_SECRET: OAuth 2.0 Client Secret for Bandwidth API authentication

call_id and account_id flow into an authenticated POST to the Bandwidth Voice API on auto hang-up. They must come from a server-trusted source — typically the authenticated inbound voice webhook body — and not from the WebSocket start event metadata, which is unauthenticated and attacker-controllable.

Configuration

stream_id

str

required

The Bandwidth Stream ID, available in the start event metadata.

call_id

str

default:"None"

The Bandwidth Call ID. Required when auto_hang_up is enabled. Must come from a server-trusted source (e.g. the signed inbound voice webhook).

account_id

str

default:"None"

The Bandwidth account ID. Required when auto_hang_up is enabled. Same trust requirement as call_id.

client_id

str

default:"None"

OAuth 2.0 Client ID for Bandwidth API authentication. Required when auto_hang_up is enabled.

client_secret

str

default:"None"

OAuth 2.0 Client Secret for Bandwidth API authentication. Required when auto_hang_up is enabled.

params

InputParams

default:"None"

Configuration parameters for audio encoding and hang-up behavior. See InputParams below.

InputParams

Configuration passed via the params constructor argument using BandwidthFrameSerializer.InputParams(...).

Parameter	Type	Default	Description
`bandwidth_sample_rate`	`int`	`8000`	Sample rate Bandwidth uses on the wire for PCMU audio. Always 8000 Hz; exposed for symmetry with other serializers.
`sample_rate`	`int`	`None`	Optional override for the pipeline input sample rate.
`outbound_encoding`	`str`	`"PCMU"`	Audio encoding for media sent back to the call: `"PCMU"` (μ-law 8 kHz) or `"PCM"` (16-bit signed little-endian PCM).
`outbound_pcm_sample_rate`	`int`	`24000`	Sample rate used when `outbound_encoding == "PCM"`. One of `8000`, `16000`, or `24000`. Higher improves TTS quality.
`auto_hang_up`	`bool`	`True`	Whether to automatically terminate the call via the Voice API on `EndFrame` or `CancelFrame`.
`ignore_rtvi_messages`	`bool`	`False`	Inherited from the base `FrameSerializer`.

Usage

Wire the serializer into a FastAPIWebsocketTransport:

import os

from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketParams,
    FastAPIWebsocketTransport,
)
from pipecat_bandwidth import BandwidthFrameSerializer

# call_id and account_id MUST come from a server-trusted source — typically
# the authenticated inbound voice webhook body — not the WebSocket "start"
# event metadata.
serializer = BandwidthFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,
    account_id=account_id,
    client_id=os.getenv("BANDWIDTH_CLIENT_ID"),
    client_secret=os.getenv("BANDWIDTH_CLIENT_SECRET"),
)

transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        add_wav_header=False,
        serializer=serializer,
    ),
)

For higher-fidelity outbound audio, configure linear PCM:

from pipecat_bandwidth import BandwidthFrameSerializer

serializer = BandwidthFrameSerializer(
    stream_id=stream_id,
    call_id=call_id,
    account_id=account_id,
    client_id=os.getenv("BANDWIDTH_CLIENT_ID"),
    client_secret=os.getenv("BANDWIDTH_CLIENT_SECRET"),
    params=BandwidthFrameSerializer.InputParams(
        outbound_encoding="PCM",
        outbound_pcm_sample_rate=24000,
    ),
)

DTMF is not delivered over the media-stream WebSocket on Bandwidth. It is captured by the BXML <Gather> verb and posted to a separate webhook, so DTMF handling belongs in your application’s webhook handler, not the serializer.

Compatibility

Tested with Pipecat v1.4.0. Check the source repository for the latest tested version and changelog.

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Overview

Source Repository

PyPI Package

Bandwidth StartStream BXML

Bandwidth Voice API

Installation

Prerequisites

Bandwidth Account Setup

Required Environment Variables

Configuration

InputParams

Usage

Compatibility

​Overview

Source Repository

PyPI Package

Bandwidth StartStream BXML

Bandwidth Voice API

​Installation

​Prerequisites

​Bandwidth Account Setup

​Required Environment Variables

​Configuration

​InputParams

​Usage

​Compatibility

Overview

Installation

Prerequisites

Bandwidth Account Setup

Required Environment Variables

Configuration

InputParams

Usage

Compatibility