Skip to main content

​
Overview

FastAPIWebsocketTransport provides WebSocket support for FastAPI web applications, enabling real-time audio communication over WebSocket connections. It’s primarily designed for telephony integrations with providers like Twilio, Telnyx, and Plivo, supporting bidirectional audio streams with configurable serializers and voice activity detection.
FastAPIWebsocketTransport is best suited for telephony applications and server-side WebSocket integrations.For general client/server applications, we recommend using WebRTC-based transports for more robust network and media handling.

FastAPI WebSocket API Reference

Pipecat’s API methods for FastAPI WebSocket integration

Example Implementation

Complete Twilio telephony integration example

FastAPI Documentation

Official FastAPI WebSocket documentation

Telephony Serializers

Learn about supported FrameSerializers for telephony providers

​
Installation

To use FastAPIWebsocketTransport, install the required dependencies: 
pip install "pipecat-ai[websocket]"

​
Prerequisites

​
FastAPI Application Setup

Before using FastAPIWebsocketTransport, you need:
  1. FastAPI Application: Set up a FastAPI web application
  2. WebSocket Endpoint: Configure WebSocket routes for real-time communication
  3. Telephony Provider: Set up integration with Twilio, Telnyx, or Plivo
  4. Frame Serializers: Configure appropriate serializers for your telephony provider

​
Configuration Options

  • Serializer Selection: Choose frame serializer based on telephony provider
  • Audio Parameters: Configure sample rates and audio formats
  • VAD Integration: Set up voice activity detection for optimal performance
  • Connection Management: Handle WebSocket lifecycle and reconnections

​
Key Features

  • Telephony Integration: Optimized for Twilio, Telnyx, and Plivo WebSocket streams
  • Frame Serialization: Built-in support for telephony provider audio formats
  • FastAPI Integration: Seamless WebSocket handling within FastAPI applications
  • Bidirectional Audio: Real-time audio streaming in both directions

​
Configuration

​
FastAPIWebsocketTransport

​
websocket
WebSocket
required
The FastAPI WebSocket connection instance.
​
params
FastAPIWebsocketParams
required
Transport configuration parameters.
​
input_name
str
default:"None"
Optional name for the input transport processor.
​
output_name
str
default:"None"
Optional name for the output transport processor.

​
FastAPIWebsocketParams

Inherits from TransportParams with additional WebSocket-specific parameters.
​
add_wav_header
bool
default:"False"
Whether to add WAV headers to outgoing audio frames.
​
serializer
FrameSerializer
default:"None"
Frame serializer for encoding/decoding WebSocket messages. Use a telephony serializer (e.g., TwilioFrameSerializer, TelnyxFrameSerializer) for provider-specific audio formats.
​
session_timeout
int
default:"None"
Session timeout in seconds. When set, triggers on_session_timeout if the session exceeds this duration. None disables the timeout.
​
fixed_audio_packet_size
int
default:"None"
Optional fixed-size packetization for raw PCM audio payloads. Useful when the remote WebSocket media endpoint requires strict audio framing (e.g., 640 bytes for 20ms at 16kHz PCM16 mono).

​
Usage

FastAPIWebsocketTransport integrates with your FastAPI application to handle telephony WebSocket connections. It works with telephony frame serializers to process audio streams from phone calls. See the complete example for a full implementation including:
  • FastAPI WebSocket endpoint configuration
  • Telephony provider integration setup
  • Frame serializer configuration
  • Audio processing pipeline integration

​
Event Handlers

FastAPIWebsocketTransport provides event handlers for client connection lifecycle and session management. Register handlers using the @event_handler decorator on the transport instance.

​
Events Summary

EventDescription
on_client_connectedClient WebSocket connected
on_client_disconnectedClient WebSocket disconnected
on_session_timeoutSession timed out

​
Connection Lifecycle

​
on_client_connected

Fired when a client successfully connects to the WebSocket. 
@transport.event_handler("on_client_connected")
async def on_client_connected(transport, websocket):
    print("Client connected")
Parameters:
ParameterTypeDescription
transportFastAPIWebsocketTransportThe transport instance
websocketWebSocketThe FastAPI WebSocket connection object

​
on_client_disconnected

Fired when a client disconnects from the WebSocket. 
@transport.event_handler("on_client_disconnected")
async def on_client_disconnected(transport, websocket):
    print("Client disconnected")
Parameters:
ParameterTypeDescription
transportFastAPIWebsocketTransportThe transport instance
websocketWebSocketThe FastAPI WebSocket connection object

​
on_session_timeout

Fired when a session exceeds the configured session_timeout duration. Only fires if session_timeout is set in the params. 
@transport.event_handler("on_session_timeout")
async def on_session_timeout(transport, websocket):
    print("Session timed out")
Parameters:
ParameterTypeDescription
transportFastAPIWebsocketTransportThe transport instance
websocketWebSocketThe FastAPI WebSocket connection object

​
Additional Resources