Pipecat Acefone Telephony Serializer

Host your Pipecat voice agents on the Acefone bi-directional audio streaming stack.

AcefoneFrameSerializer converts between Pipecat frames and the Acefone Media Streams WebSocket protocol, enabling real-time, two-way audio over a single WebSocket connection so you can serve an agent on an Indian phone number.

Maintainer: Himanshu Gunwant

Installation

pip install pipecat-acefone

Or via uv, add it to your pyproject.toml:

[project]
name = "your-project"
version = "0.1.0"
dependencies = [
    "pipecat-acefone",
    "another-package"
]

uv sync

Prerequisites

• An Acefone account with a phone number.
• Bi-directional audio streaming enabled on that number, pointed at your WebSocket endpoint (see the protocol docs under Protocol).
• Python 3.11+.

Usage

Construct the serializer with AcefoneFrameSerializer.InputParams and pass it to your Pipecat WebSocket transport:

from pipecat_acefone.serializer import AcefoneFrameSerializer, AcefoneMediaFormat
from pipecat.audio.vad.silero import SileroVADAnalyzer
from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketTransport,
    FastAPIWebsocketParams,
)

serializer = AcefoneFrameSerializer(
    AcefoneFrameSerializer.InputParams(
        # Required: the Media Stream SID for the call.
        stream_sid=stream_id,
        # Required only when auto_hang_up is enabled.
        call_sid=call_id,
        # Terminate the call via a WebSocket "end" event on EndFrame/CancelFrame.
        auto_hang_up=True,
        # Wire format: ULAW (default, 8kHz G.711 μ-law) or PCM (16-bit slin16).
        media_format=AcefoneMediaFormat.ULAW,
        acefone_sample_rate=8000,
    )
)

transport = FastAPIWebsocketTransport(
    websocket=websocket_client,
    params=FastAPIWebsocketParams(
        audio_out_enabled=True,
        add_wav_header=True,
        vad_audio_passthrough=True,
        serializer=serializer,
        audio_out_sample_rate=8000,
    ),
)

See bot.py for a complete working example including STT/LLM/TTS services, event handlers, and transport setup.

Configuration

All configuration is passed through AcefoneFrameSerializer.InputParams:

Regardless of the wire media_format, inbound audio is normalized to PCM InputAudioRawFrame for the pipeline, and outbound audio is converted back to the configured wire format.

Features

• Audio streaming — media events in both directions, with automatic μ-law ⇄ PCM conversion and resampling between the pipeline and acefone_sample_rate.
• Configurable wire format — 8kHz μ-law (default) or 16-bit linear PCM.
• DTMF input — inbound dtmf events become InputDTMFFrame keypad entries.
• Interruptions — InterruptionFrame emits a clear event to flush queued audio on the provider side.
• Auto hang-up — when enabled, terminates the call over the same WebSocket via an end event instead of a separate REST call.

Running the Example

1. Start ngrok to tunnel the local server:

   ngrok http 7860
   

2. Point your Acefone number's bi-directional audio streaming at your ngrok WebSocket endpoint (e.g. wss://foo.bar.ngrok-free.dev/ws). See the Protocol docs for the dashboard/API configuration.

3. Install dependencies:

   uv sync
   

4. Set up your environment:

   cp .env.example .env
   

5. Run the bot:

   uv run bot.py --transport acefone --proxy your_ngrok_url
   

The bot creates a WebSocket that accepts connections from your Acefone number. Once it's running, call the number to interact with the agent.

Protocol

Reference docs for the wire protocol and events:

• Acefone: https://docs.acefone.in/docs/bi-directional-audio-streaming-integration-document

Compatibility

• Tested with Pipecat v1.5.0
• Python 3.11+

License

BSD-2-Clause — see LICENSE.

Support

• Protocol docs: see Protocol above for message formats.
• Pipecat Discord: https://discord.gg/pipecat (#community-integrations)
• Issues: https://github.com/monster-anshu/pipecat-acefone/issues