Merge pull request #894 from pipecat-ai/docs/pr-4704

docs: update for pipecat PR #4704

Author: markbackman

api-reference/server/services/transport/fastapi-websocket.mdx

@@ -131,10 +131,23 @@ Inherits from `TransportParams` with additional WebSocket-specific parameters.
   that need longer to complete a graceful close.
 </ParamField>
 
+<ParamField path="allowed_origins" type="list[str]" default="[]">
+  List of allowed origins for WebSocket connections. Empty list allows all
+  origins. When set, connections with a missing or disallowed `Origin` header
+  are rejected before the WebSocket handshake completes. Defaults to
+  `PIPECAT_ALLOWED_ORIGINS` environment variable (comma-separated).
+</ParamField>
+
 ## 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.
 
+<Note>
+  The transport constructor raises `ValueError` if `params.allowed_origins` is
+  set and the connection's `Origin` header is missing or not in the allowed
+  list. The caller is responsible for closing the WebSocket in that case.
+</Note>
+
 See the [complete example](https://github.com/pipecat-ai/pipecat-examples/tree/main/twilio-chatbot) for a full implementation including:
 
 - FastAPI WebSocket endpoint configuration

api-reference/server/services/transport/websocket-server.mdx

@@ -120,6 +120,13 @@ Inherits from `TransportParams` with additional WebSocket-specific parameters.
   timeout.
 </ParamField>
 
+<ParamField path="allowed_origins" type="list[str]" default="[]">
+  List of allowed origins for WebSocket connections. Empty list allows all origins.
+  When set, connections with a missing or disallowed `Origin` header are rejected
+  before the WebSocket handshake completes. Defaults to `PIPECAT_ALLOWED_ORIGINS`
+  environment variable (comma-separated).
+</ParamField>
+
 ### WebsocketClientTransport
 
 <ParamField path="uri" type="str" required>

api-reference/server/utilities/runner/guide.mdx

@@ -339,17 +339,20 @@ The development runner accepts several command-line arguments to customize its b
 python bot.py [OPTIONS]
 
 Options:
-  --host TEXT          Server host address (default: localhost)
-  --port INTEGER       Server port (default: 7860)
-  -t, --transport      Restrict to a single transport and set it as the default
-                       for /start: daily, webrtc, twilio, telnyx, plivo, exotel.
-                       Omit to support all transports simultaneously (default).
-  -x, --proxy TEXT     Public proxy hostname for telephony webhooks (required for telephony)
-  --esp32              Enable SDP munging for ESP32 WebRTC compatibility
-  -d, --direct         Connect directly to Daily room for testing (automatically sets transport to daily)
-  --dialin             Enable Daily PSTN dial-in webhook handling
-  --whatsapp           Verify required WhatsApp environment variables are present
-  -v, --verbose        Increase logging verbosity
+  --host TEXT                Server host address (default: localhost)
+  --port INTEGER             Server port (default: 7860)
+  -t, --transport            Restrict to a single transport and set it as the default
+                             for /start: daily, webrtc, twilio, telnyx, plivo, exotel.
+                             Omit to support all transports simultaneously (default).
+  -x, --proxy TEXT           Public proxy hostname for telephony webhooks (required for telephony)
+  --allowed-origins [ORIGIN] Allowed origins for HTTP and WebSocket connections.
+                             Can be specified multiple times. Omit or leave empty to allow
+                             all origins. Defaults to PIPECAT_ALLOWED_ORIGINS env var.
+  --esp32                    Enable SDP munging for ESP32 WebRTC compatibility
+  -d, --direct               Connect directly to Daily room for testing (automatically sets transport to daily)
+  --dialin                   Enable Daily PSTN dial-in webhook handling
+  --whatsapp                 Verify required WhatsApp environment variables are present
+  -v, --verbose              Increase logging verbosity
 ```
 
 ### Key Arguments
@@ -366,6 +369,8 @@ Options:
 
 **`--dialin`**: Enables the `/daily-dialin-webhook` endpoint for handling Daily PSTN dial-in calls. This endpoint receives webhook data from Daily when a phone call dials into your configured phone number, creates a SIP-enabled room, and spawns your bot. (It no longer requires `-t daily`, though dial-in is a Daily feature.)
 
+**`--allowed-origins`**: Restricts which origins can connect to HTTP and WebSocket endpoints. Useful for preventing Cross-Site WebSocket Hijacking (CSWSH) attacks. When set, connections with a missing or disallowed `Origin` header are rejected. Can be specified multiple times for multiple origins. Defaults to the `PIPECAT_ALLOWED_ORIGINS` environment variable (comma-separated). Leave unset to allow all origins.
+
 **`--esp32`**: Enables SDP (Session Description Protocol) modifications needed for ESP32 WebRTC compatibility. Must be used with a specific IP address via `--host`.
 
 ### Environment Variables
@@ -384,6 +389,10 @@ Different transports require different environment variables:
 - `PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN`: Plivo credentials
 - `TELNYX_API_KEY`: Telnyx API key
 
+**Security**:
+
+- `PIPECAT_ALLOWED_ORIGINS`: Comma-separated list of allowed origins for HTTP and WebSocket connections. When set, the runner and WebSocket transports reject any connection whose `Origin` header is missing or not in this list. Leave unset or empty to allow all origins. Example: `https://example.com,https://app.example.com`
+
 The runner automatically uses these environment variables when creating transport sessions and authentication tokens.
 
 ## Simplifying with the Transport Utility