Acefone Frame Serializer

AcefoneFrameSerializer converts between Pipecat frames and Acefone’s telephony WebSocket protocol for hosted voice agents.

Overview

AcefoneFrameSerializer converts between Pipecat frames and the Acefone bi-directional audio streaming protocol, enabling real-time voice agents over a websocket. It is designed to be wired into a FastAPIWebsocketTransport so you can host a Pipecat agent on the Acefone telephony stack and reach it over an Indian phone number.

It supports both ULAW (8kHz G.711 μ-law, the default) and PCM (16-bit linear PCM) wire formats, DTMF keypad input, interruptions, and optional automatic call termination over the same websocket.

Source Repository

Source code, examples, and issues for the Acefone integration

PyPI Package

The pipecat-acefone package on PyPI

Acefone

Learn about Acefone telephony and get a phone number

Protocol Docs

Acefone bi-directional audio streaming message formats

Installation

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

uv add pipecat-acefone

Prerequisites

To host an agent on the Acefone telephony stack you need:

1. An Acefone phone number: with bi-directional audio streaming enabled and pointed at your bot’s websocket endpoint.
2. A public websocket endpoint: expose your bot’s websocket so Acefone can connect to it (for example, by tunneling with ngrok during development).

The serializer itself does not require any API keys — automatic hang-up is performed over the same websocket via an end event. The message formats are documented in the Acefone bi-directional audio streaming docs.

Configuration

AcefoneFrameSerializer takes a single, optional params argument:

params · AcefoneFrameSerializer.InputParams · default: "InputParams()"

Serializer input parameters, including the stream/call identifiers. See InputParams below.

InputParams

Passed via the params constructor argument using AcefoneFrameSerializer.InputParams(...).

Parameter	Type	Default	Description
media_format	AcefoneMediaFormat	ULAW	Wire audio format. ULAW = 8kHz G.711 μ-law; PCM = 16-bit linear PCM (slin16).
acefone_sample_rate	int	8000	Sample rate of the Acefone media stream (Hz).
sample_rate	int	0	Pipeline input sample rate override. When 0, the rate comes from the pipeline configuration during setup.
stream_sid	str	None	The Media Stream SID for the call. Typically parsed from the initial start message; captured automatically from it if unset.
call_sid	str	None	The associated Call SID. Required when auto_hang_up is enabled.
auto_hang_up	bool	False	Terminate the call via a websocket end event on the first EndFrame/CancelFrame.

See the source repository for the authoritative, up-to-date list of parameters and message formats.

Usage

Wire the serializer into a FastAPIWebsocketTransport. The stream_sid (and call_sid, if you enable auto hang-up) is read from the initial websocket start message Acefone sends when a call connects.

from pipecat_acefone import AcefoneFrameSerializer, AcefoneMediaFormat
from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketTransport,
    FastAPIWebsocketParams,
)

serializer = AcefoneFrameSerializer(
    AcefoneFrameSerializer.InputParams(
        stream_sid=stream_id,
        call_sid=call_id,
        auto_hang_up=True,
        media_format=AcefoneMediaFormat.ULAW,
    )
)

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

See the source repository for a complete bot.py example, including parsing stream_sid from the initial websocket messages and running the bot behind an ngrok tunnel.

Compatibility

Tested with Pipecat v1.5.0 and Python 3.11+. Check the source repository for the latest tested version and changelog.