pipecat-bandwidth
A Pipecat community integration that lets you use Bandwidth Programmable Voice as the telephony layer for your Pipecat voice bots.
This package provides BandwidthFrameSerializer, a FrameSerializer you plug
into a FastAPIWebsocketTransport to handle Bandwidth's bidirectional
WebSocket media stream protocol.
Maintained by Bandwidth.
What it does
- Decodes Bandwidth's inbound μ-law audio (8 kHz) into Pipecat audio frames.
- Encodes outbound audio as either μ-law or linear PCM at 8/16/24 kHz. PCM at 24 kHz noticeably improves TTS quality compared to μ-law.
- Handles interruptions by emitting Bandwidth's
clearevent, so the bot stops talking immediately when the caller speaks. - Auto hangs up the call via the Bandwidth Voice API on
EndFrameorCancelFrame, using OAuth 2.0 client_credentials.
Installation
pip install pipecat-bandwidth
Or with uv:
uv add pipecat-bandwidth
Usage
from pipecat.transports.websocket.fastapi import (
FastAPIWebsocketParams,
FastAPIWebsocketTransport,
)
from pipecat_bandwidth import BandwidthFrameSerializer
# IMPORTANT: 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's metadata, which is unauthenticated
# and attacker-controllable. See the chatbot example for one safe pattern
# (token-in-URL correlating the webhook to the WS connect).
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,
),
)
Example
A complete end-to-end example lives in
examples/bandwidth-chatbot. It shows a
single-file FastAPI server that:
- Returns a
<StartStream>BXML response on Bandwidth's voice webhook. - Accepts the bidirectional WebSocket and reads Bandwidth's
startevent for the stream/call/account IDs. - Runs a Deepgram (STT) → OpenAI (LLM) → Cartesia (TTS) Pipecat pipeline.
See the example's README for setup and run instructions.
DTMF
Bandwidth does not deliver DTMF over the media-stream WebSocket. DTMF is
captured by the BXML <Gather> verb and posted to a separate webhook. Wire
DTMF handling in your application's webhook handler — not in the serializer.
Compatibility
- Tested with Pipecat v1.1.0.
- Python 3.11, 3.12.
Links
License
BSD 2-Clause. See LICENSE.
Contributing
Issues and PRs are welcome. For larger changes, please open an issue first to discuss what you'd like to change.
Metadata
Release files for pipecat-bandwidth 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pipecat_bandwidth-0.1.0.tar.gz | 18.5 kB | Without provenance | Details for pipecat_bandwidth-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pipecat_bandwidth-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for pipecat_bandwidth-0.1.0-py3-none-any.whl |
Total release size: 28.0 kB
Release files / pipecat_bandwidth-0.1.0.tar.gz
| Download URL | pipecat_bandwidth-0.1.0.tar.gz |
|---|---|
| Size | 18.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
be3571a7b01c56945421a6b55ce4bd4277702ee7083ccf871d94740800af74bf
|
|
BLAKE2b-256 checksum How to use checksums |
669a8a5900ffd3c60ca2b0c40348394367f0931f8d2244fc424b6113c7eab408
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / pipecat_bandwidth-0.1.0-py3-none-any.whl
| Download URL | pipecat_bandwidth-0.1.0-py3-none-any.whl |
|---|---|
| Size | 9.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a09629953a87076163345d79ddba673de687fe364e07368a579d29db672e1bfe
|
|
BLAKE2b-256 checksum How to use checksums |
bd06779fd7e7fc36d8b1e76316b2a3e4f6ab9e1f329a367e83032e639505c250
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for pipecat-bandwidth 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.