> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# jambonz Frame Serializer

> JambonzFrameSerializer connects Pipecat pipelines to phone calls on jambonz through the listen verb's raw PCM WebSocket protocol.

## Overview

`JambonzFrameSerializer` connects a Pipecat pipeline to calls on [jambonz](https://jambonz.org) through the `listen` verb's WebSocket protocol. Audio is raw 16-bit signed little-endian mono PCM, and the call's sample rate is read from the preamble jambonz sends when the socket opens, so it needs no configuration.

> [card] [jambonz Serializer API Reference](https://reference-server.pipecat.ai/en/latest/api/pipecat.serializers.jambonz.html)
>
> Pipecat's API methods for jambonz WebSocket integration

> [card] [jambonz listen Verb](https://docs.jambonz.org/verbs/verbs/listen)
>
> Official jambonz documentation for the `listen` verb

## Installation

The `JambonzFrameSerializer` does not require any additional dependencies beyond the core Pipecat library:

```bash theme={null}
uv add "pipecat-ai"
```

## Prerequisites

1. **A jambonz account or server** with an application that runs the `listen` verb.
2. **A public WebSocket URL** for your bot, which the verb's `url` points to.

### listen Verb

The verb needs three settings stated explicitly:

```json theme={null}
{
  "verb": "listen",
  "url": "wss://your-bot.example.com/ws",
  "sampleRate": 16000,
  "mixType": "mono",
  "bidirectionalAudio": {
    "enabled": true,
    "streaming": true,
    "sampleRate": 16000
  }
}
```

* `bidirectionalAudio.streaming` defaults to `false`. While it is, audio sent back is ignored and the caller hears nothing.
* `sampleRate` defaults to `8000`. Other allowed values are 16000, 24000, 48000 and 64000.
* `bidirectionalAudio.sampleRate` has no default. Set it to the same value as `sampleRate`, or set the serializer's `audio_out_sample_rate` to it: the serializer sends audio at the `sampleRate` from the preamble unless `audio_out_sample_rate` is set, so a mismatch plays back too fast or too slow.
* `mixType` must be `mono`. Audio is dropped with a warning for `stereo` or `mixed`.
* Set `passDtmf` to receive keypad digits as `InputDTMFFrame`.

## Configuration

**params** `JambonzFrameSerializer.InputParams | None` (default: None)

Configuration parameters. See [InputParams](#inputparams) below.

### InputParams

| Parameter | Type | Default | Description |
| - | - | - | - |
| `audio_in_sample_rate` | `int \| None` | `None` | Overrides the rate jambonz forks audio at. When `None`, the rate comes from the connection's preamble. |
| `audio_out_sample_rate` | `int \| None` | `None` | The rate jambonz reads the audio sent back at, the verb's `bidirectionalAudio.sampleRate`. When `None`, audio is sent at the preamble's rate. |
| `disconnect_on_end` | `bool` | `True` | Sends `disconnect` when the pipeline ends, which ends the `listen` verb so jambonz runs the verb's `actionHook` or hangs up. Needs no API credentials. |
| `ignore_rtvi_messages` | `bool` | `True` | Whether to ignore RTVI protocol messages during serialization. |
| `resampler_clear_after_secs` | `float \| None` | `0.2` | *Deprecated since 1.16.0.* Has no effect. No replacement. Removed in 2.0.0. |

### Properties

Populated from the preamble once it arrives.

| Property | Type | Description |
| - | - | - |
| `audio_in_sample_rate` | `int \| None` | The rate jambonz is forking the call at. |
| `audio_out_sample_rate` | `int \| None` | The rate the serializer sends audio at. |
| `mix_type` | `str \| None` | The channel layout stated in the preamble. |
| `call_sid` | `str \| None` | The jambonz call identifier. |
| `trace_id` | `str \| None` | The jambonz trace identifier. |
| `call_meta` | `dict[str, Any]` | A copy of the full preamble. |

## Usage

### Basic Setup

```python theme={null}
from pipecat.serializers.jambonz import JambonzFrameSerializer
from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketParams,
    FastAPIWebsocketTransport,
)

serializer = JambonzFrameSerializer()

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

## Notes

* **Interruptions**: An `InterruptionFrame` sends `killAudio`, which flushes audio jambonz is playing or has buffered.
* **DTMF support**: With `passDtmf` set on the verb, digits are converted to `InputDTMFFrame` objects. `mark` and `playDone` events are ignored.
* **Preamble first**: Audio that arrives before the preamble is dropped.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.