Skip to main content

pipecat-vobiz

Connect a Pipecat voice agent to phone calls on Vobiz, a global telephony provider for voice AI.

VobizFrameSerializer translates between Pipecat frames and the WebSocket protocol opened by the Vobiz <Stream> XML verb. It follows the same structure as Pipecat's built-in telephony serializers.

This integration is maintained by Vobiz.

Installation

uv add pipecat-vobiz

Or use pip install pipecat-vobiz.

How it works

Phone call <-> Vobiz <-> WebSocket <-> FastAPIWebsocketTransport + VobizFrameSerializer <-> your pipeline
Pipecat Vobiz
media event InputAudioRawFrame
OutputAudioRawFrame playAudio event
InterruptionFrame clearAudio event
EndFrame or CancelFrame REST DELETE on the call, when auto_hang_up is on

Usage

Answer the call with XML that opens a bidirectional stream:

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

Then read the start event and give the serializer to the transport:

from pipecat.transports.websocket.fastapi import FastAPIWebsocketParams, FastAPIWebsocketTransport
from pipecat_vobiz import VobizFrameSerializer, parse_vobiz_start

await websocket.accept()
start = await parse_vobiz_start(websocket)

serializer = VobizFrameSerializer(
    stream_id=start["stream_id"],
    call_id=start["call_id"],
    auth_id=os.environ["VOBIZ_AUTH_ID"],
    auth_token=os.environ["VOBIZ_AUTH_TOKEN"],
    params=VobizFrameSerializer.InputParams(
        encoding=start["encoding"],
        vobiz_sample_rate=start["sample_rate"],
    ),
)
transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        serializer=serializer,
    ),
)

Run the transport in a pipeline at the sample rate from the start event:

pipeline = Pipeline(
    [
        transport.input(),
        stt,
        user_aggregator,
        llm,
        tts,
        transport.output(),
        assistant_aggregator,
    ]
)
worker = PipelineWorker(
    pipeline,
    params=PipelineParams(
        audio_in_sample_rate=start["sample_rate"],
        audio_out_sample_rate=start["sample_rate"],
    ),
)

examples/bot.py is the complete agent in one file, including stt, llm, tts and the aggregators.

Configuration

VobizFrameSerializer takes stream_id, call_id, auth_id, auth_token and params. auto_hang_up uses the call ID and the two credentials.

InputParams field Default Description
encoding audio/x-mulaw Inbound encoding: audio/x-mulaw or audio/x-l16. Must match the <Stream> contentType.
vobiz_sample_rate 8000 Inbound rate. μ-law supports 8000 Hz. L16 supports 8000 and 16000 Hz.
output_encoding inbound encoding Outbound encoding, set independently of inbound.
output_sample_rate inbound rate Outbound rate. L16 also supports 24000 Hz outbound.
sample_rate None Overrides the pipeline input sample rate.
auto_hang_up True End the call on EndFrame or CancelFrame.

L16 audio is little-endian on the wire.

auto_hang_up deletes the whole call. If your XML has a verb after <Stream>, such as <Dial> for a transfer, set auto_hang_up=False so that the verb can run.

Run the example

The example uses Gemini for speech-to-text, the LLM and text-to-speech, on a Vobiz phone number.

  1. Install the dependencies and add your keys:

    uv pip install "pipecat-vobiz[example]"
    cp examples/env.example .env
    
  2. Start the bot, and expose port 8765 at a public HTTPS URL:

    python examples/bot.py
    ngrok http 8765
    
  3. In the Vobiz console, create an application with https://<your-url>/answer as its answer URL, and attach your number to it.

  4. Call the number.

For recording, transfers and a dashboard, see Vobiz-X-Pipecat. The full setup guide is at vobiz.ai/docs/integrations/pipecat.

Pipecat compatibility

Tested with Pipecat v1.15.0. This package ran on real phone calls in every inbound and outbound format above, with Gemini STT, LLM and TTS and with Gemini Live, including interruptions and auto_hang_up. examples/bot.py ran on a real μ-law call. Unit tests run against Pipecat 1.12.0 and 1.15.0, on Python 3.11 to 3.13.

DTMF digits sent through the Vobiz REST API and the <DTMF> XML element did not reach the stream in testing, so treat InputDTMFFrame as unverified.

Development

uv pip install -e ".[dev]"
pytest
ruff check .

License

BSD 2-Clause. See LICENSE.

Metadata

Release files for pipecat-vobiz 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pipecat-vobiz 0.1.1
File Size Uploaded Provenance Actions
pipecat_vobiz-0.1.1.tar.gz 14.3 kB Without provenance Details for pipecat_vobiz-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pipecat-vobiz 0.1.1
File Interpreter ABI Platform Actions
pipecat_vobiz-0.1.1-py3-none-any.whl Python 3 none any Details for pipecat_vobiz-0.1.1-py3-none-any.whl

Total release size: 23.3 kB

Release files / pipecat_vobiz-0.1.1.tar.gz

Download URL pipecat_vobiz-0.1.1.tar.gz
Size 14.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e531ae23c7e05c666aa80278fbc96b709687e5aeb9410d5a6ef9e769f5b6bf2c
BLAKE2b-256 checksum
How to use checksums
e171ecefb744bfaa8fa03f39a1338596238f84a6a1bbaa5ed148c45ac1bb46d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.1 {"installer":{"name":"uv","version":"0.11.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / pipecat_vobiz-0.1.1-py3-none-any.whl

Download URL pipecat_vobiz-0.1.1-py3-none-any.whl
Size 9.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9acb28a3f221cfda2f6720b6fa1528207692ac6949b64c90b669a12293b226ec
BLAKE2b-256 checksum
How to use checksums
22c07773210435cd8c65d7fbac9c0837dec3af6d9c88927e5fd65f3e806a7508
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.1 {"installer":{"name":"uv","version":"0.11.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for pipecat-vobiz 0.1.1

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page