> ## 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.

# WebSocketTransport

> A lightweight transport for WebSocket based connections with Pipecat

`WebSocketTransport` enables a purely WebSocket based connection between clients and your Pipecat application. It implements bidirectional audio and video streaming using a WebSocket for real-time communication.

This transport is intended for lightweight implementations, particularly for local development and testing. It expects your Pipecat server to include the corresponding [`WebSocketTransport` server-side](/api-reference/server/services/transport/websocket-server) implementation.

<Warning>
  The `WebSocketTransport` is best suited for server-server applications and prototyping client/server apps.

  For client/server production applications, we strongly recommend using a WebRTC-based transport for robust network and media handling. For more on WebRTC vs. Websocket communication, check out [this article](https://voiceaiandvoiceagents.com/#websockets-webrtc).
</Warning>

## Usage

### Basic Setup

```javascript theme={null}
import { PipecatClient } from "@pipecat-ai/client-js";
import {
  WebSocketTransport,
  ProtobufFrameSerializer,
} from "@pipecat-ai/websocket-transport";

const pcClient = new PipecatClient({
  transport: new WebSocketTransport({
    serializer: new ProtobufFrameSerializer(),
    recorderSampleRate: 8000,
    playerSampleRate: 8000,
  }),
  enableCam: false, // Default camera off
  enableMic: true, // Default microphone on
  callbacks: {
    // Event handlers
  },
});

await pcClient.connect({
  wsUrl: "ws://localhost:7860/ws", // Your WebSocket server URL
});
```

## API Reference

### Constructor Options

```typescript theme={null}
type WebSocketTransportOptions = {
  wsUrl?: string;
  serializer?: WebSocketSerializer;
  recorderSampleRate?: number;
  playerSampleRate?: number;
};

export interface WebSocketTransportConstructorOptions extends WebSocketTransportOptions {
  mediaManager?: MediaManager;
}
```

#### Properties

<ParamField name="wsUrl" type="string">
  URL of the WebSocket server. This is the endpoint your client will connect to
  for WebSocket communication.
</ParamField>

<ParamField name="serializer" type="WebSocketSerializer" default="ProtobufFrameSerializer">
  The serializer to use for encoding/decoding messages sent over the WebSocket
  connection. The websocket-transport package provides two serializer options: -
  `ProtobufFrameSerializer`: Uses Protocol Buffers for serialization. -
  `TwilioSerializer`: Uses Twilio's serialization format. The main purpose of
  the TwilioSerializer is to allow testing the bots built to work with Twilio
  without having to make phone calls.
</ParamField>

<ParamField name="recorderSampleRate" type="number">
  Sample rate for which to encode the audio input. Default is `16000`.
</ParamField>

<ParamField name="playerSampleRate" type="number">
  Sample rate for which to decode the incoming audio for output. Default is
  `24000`.
</ParamField>

<ParamField name="mediaManager" type="MediaManager" default="DailyMediaManager">
  The media manager to use for handling local audio and video streams. This
  should not be overridden unless you have a specific reason to use a different
  media manager. The default is `DailyMediaManager`, which is suitable for most
  use cases. Note that the `DailyMediaManager` does not use any of Daily's
  services, it simply takes advantage of vast media support provided by the
  Daily library.
</ParamField>

### TransportConnectionParams

The `WebSocketTransport` takes the same options as the constructor; `WebSocketTransportOptions`. Anything provided here will override the defaults set in the constructor. The `wsUrl` is required to establish a connection.

<CodeGroup>
  ```typescript client theme={null}
  pcClient.connect({
    wsUrl: 'http://localhost:7860/ws'
  });
  // OR...
  pcClient.startBotAndConnect({
    endpoint: '/api/start', // returns { wsUrl }
  });
  ```

  ```python server theme={null}
  # See
  # https://github.com/pipecat-ai/pipecat-examples/blob/main/websocket/server/server.py
  # for a complete example of how to implement the server-side endpoint.
  @app.websocket("/ws")
  async def websocket_endpoint(websocket: WebSocket):
      await websocket.accept()
      print("WebSocket connection accepted")
      try:
          await run_bot(websocket)
      except Exception as e:
          print(f"Exception in run_bot: {e}")


  @app.post("/api/start")
  async def start(request: Request) -> Dict[Any, Any]:
      ws_url = "ws://localhost:7860/ws"
      return {"wsUrl": ws_url}
  ```

  ```python bot theme={null}
  # See
  # https://github.com/pipecat-ai/pipecat-examples/blob/main/websocket/server/bot_websocket_server.py
  # for a complete example of a bot script using the WebSocketTransport.
  from pipecat.serializers.protobuf import ProtobufFrameSerializer
  from pipecat.transports.websocket.fastapi import (
      FastAPIWebsocketParams,
      FastAPIWebsocketTransport,
  )

  async def run_bot(websocket_client):
      ws_transport = FastAPIWebsocketTransport(
          websocket=websocket_client,
          params=FastAPIWebsocketParams(
              audio_in_enabled=True,
              audio_out_enabled=True,
              add_wav_header=False,
              serializer=ProtobufFrameSerializer(),
          ),
      )

      llm = ... # Initialize your LLM here, e.g., OpenAI, HuggingFace, etc.

      messages = [{ role: "system", content: "You are a helpful assistant." }]
      context = LLMContext(messages)
      user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
          context,
          user_params=LLMUserAggregatorParams(
              vad_analyzer=SileroVADAnalyzer(),
          ),
      )

      pipeline = Pipeline(
          [
              ws_transport.input(),
              user_aggregator,
              llm,  # LLM
              ws_transport.output(),
              assistant_aggregator,
          ]
      )

      task = PipelineTask(
          pipeline,
          params,
      )
      ...
  ```
</CodeGroup>

### Methods

For most operations, you will not interact with the transport directly. Most methods have an equivalent in the `PipecatClient` and should be called from the `PipecatClient`. However, there is one transport-specific methods that you may need to call directly. When doing so, be sure to access your transport via the `transport` property of the `PipecatClient` instance.

<ResponseField name="handleUserAudioStream" type="method">
  If implementing your own serializer, you will need to pass the user audio
  stream to the transport via this method, which takes an `ArrayBuffer` of audio
  data.

  ```javascript theme={null}
  transport.handleUserAudioStream(chunk.data);
  ```
</ResponseField>

## Events

The transport implements the various [`PipecatClient` event handlers](/api-reference/client/js/callbacks).

## Reconnection Handling

The WebSocketTransport does provide reconnection handling. If the WebSocket connection is lost, it will attempt to reconnect twice. If all reconnection attempts fail, the transport will gracefully disconnect.

## More Information

<CardGroup cols={2}>
  <Card horizontal title="WebSocket Demo" icon="video" href="https://github.com/pipecat-ai/pipecat-examples/tree/main/websocket">
    Basic Agent example using a WebSocket transport
  </Card>

  <Card horizontal title="Twilio Demo" icon="video" href="https://github.com/pipecat-ai/pipecat-examples/tree/main/twilio-chatbot">
    Example using a WebSocket transport to simulate a Twilio connection to a bot
  </Card>

  <Card horizontal title="Source" icon="github" href="https://github.com/pipecat-ai/pipecat-client-web-transports/tree/main/transports/websocket-transport">
    `WebSocketTransport`
  </Card>

  <Card horizontal title="Package" icon="browser" href="https://www.npmjs.com/package/@pipecat-ai/websocket-transport">
    `@pipecat-ai/websocket-transport`
  </Card>
</CardGroup>