docs: add websocket authentication and generic handler documentation

api-reference/pipecat-cloud/rest-reference/openapi-start.json

@@ -104,7 +104,7 @@
           "transport": {
             "type": "string",
             "description": "Explicitly specify which transport the bot should use.",
-            "enum": ["daily", "webrtc"],
+            "enum": ["daily", "webrtc", "websocket"],
             "example": "webrtc"
           },
           "body": {
@@ -117,6 +117,16 @@
       "StartResponse": {
         "type": "object",
         "properties": {
+          "token": {
+            "type": "string",
+            "description": "HMAC session token for WebSocket authentication (only when transport is \"websocket\")",
+            "example": "eyJzaCI6Im15LWFnZW50Lm15LW9yZyIsImV4cCI6MTcxMjgwMDAwMCwibm9uY2UiOiJhYmMxMjMifQ.dGVzdC1zaWduYXR1cmU"
+          },
+          "wsUrl": {
+            "type": "string",
+            "description": "WebSocket URL to connect to (only when transport is \"websocket\")",
+            "example": "wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org"
+          },
           "dailyRoom": {
             "type": "string",
             "description": "URL of the created Daily room (if createDailyRoom was set to true)",

docs.json

@@ -342,10 +342,18 @@
               "pipecat-cloud/guides/regions",
               "pipecat-cloud/guides/session-api",
               "pipecat-cloud/guides/smart-turn",
+              {
+                "group": "WebSockets",
+                "pages": [
+                  "pipecat-cloud/guides/generic-websocket",
+                  "pipecat-cloud/guides/websocket-authentication"
+                ]
+              },
               "pipecat-cloud/guides/whatsapp",
               {
                 "group": "Telephony",
                 "pages": [
+                  "pipecat-cloud/guides/telephony/overview",
                   "pipecat-cloud/guides/telephony/twilio-websocket",
                   "pipecat-cloud/guides/telephony/telnyx-websocket",
                   "pipecat-cloud/guides/telephony/plivo-websocket",

pipecat-cloud/fundamentals/deploy.mdx

@@ -69,6 +69,8 @@ region = "us-west"
     min_agents = 1
 ```
 
+You can optionally enable WebSocket authentication by adding `websocket_auth = "token"` to require HMAC token authentication on the [generic WebSocket endpoint](/pipecat-cloud/guides/generic-websocket). Defaults to `"none"` (no authentication required). See the [WebSocket Authentication guide](/pipecat-cloud/guides/websocket-authentication) for details.
+
 If you're deploying with a custom image, add the `image` field (and `image_credentials` for private registries):
 
 ```toml

pipecat-cloud/guides/generic-websocket.mdx

@@ -0,0 +1,55 @@
+---
+title: Generic WebSocket
+description: "Connect any WebSocket client — telephony, server-to-server, or custom integrations — to your Pipecat Cloud agents"
+---
+
+The generic WebSocket endpoint is a protocol-agnostic way to connect a WebSocket client to your Pipecat Cloud agent. Unlike the provider-specific endpoints (`/ws/twilio`, `/ws/plivo`, etc.), it imposes no protocol requirements. Messages are relayed directly between the client and your bot without validation or transformation.
+
+## When to Use
+
+- **Custom telephony providers**: Connect telephony providers that Pipecat Cloud doesn't ship a dedicated endpoint for. Dedicated endpoints exist for [Twilio](/pipecat-cloud/guides/telephony/twilio-websocket), [Plivo](/pipecat-cloud/guides/telephony/plivo-websocket), [Telnyx](/pipecat-cloud/guides/telephony/telnyx-websocket), and [Exotel](/pipecat-cloud/guides/telephony/exotel-websocket).
+- **Server-to-server integrations**: Connect your own backend or a third-party platform that speaks WebSocket.
+- **Custom WebSocket clients**: Any client that can establish a WebSocket connection and whose message protocol you control.
+
+<Note>
+  **Web and mobile clients**: Browsers and mobile apps can connect via
+  WebSocket, but we recommend WebRTC instead. WebRTC handles varying network
+  conditions, media quality, and reconnect behavior better than raw WebSocket.
+  See the [Daily WebRTC guide](/pipecat-cloud/guides/daily-webrtc) or the
+  SmallWebRTC [client SDKs](/client/js/introduction) for recommended web and
+  mobile options.
+</Note>
+
+<Note>
+  If you're using Twilio, Plivo, Telnyx, or Exotel, you can use either the
+  generic endpoint or the dedicated provider endpoint (`/ws/twilio`, etc.). The
+  dedicated endpoints provide protocol validation for added reliability.
+</Note>
+
+## Endpoint
+
+```
+wss://{region}.api.pipecat.daily.co/ws/generic/{agentName}.{organizationName}
+```
+
+The service host (`{agentName}.{organizationName}`) can also be provided as a query parameter:
+
+```
+wss://{region}.api.pipecat.daily.co/ws/generic?serviceHost={agentName}.{organizationName}
+```
+
+## Authentication
+
+The generic endpoint supports optional HMAC token authentication, controlled by the `websocket_auth` setting on your agent. See the [WebSocket Authentication guide](/pipecat-cloud/guides/websocket-authentication) for details on how to configure and use token authentication.
+
+When `websocket_auth` is set to `none`, clients can connect directly without a token:
+
+```bash
+wscat -c "wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org"
+```
+
+## Message Format
+
+The generic endpoint supports both text and binary WebSocket frames. Your bot receives messages exactly as sent by the client — no protocol-specific parsing or transformation is applied.
+
+Your bot code is responsible for handling the client's message format. Use the appropriate [serializer](/api-reference/server/services/serializers/introduction) for your client's protocol, or implement custom message handling for non-standard clients.

pipecat-cloud/guides/telephony/overview.mdx

@@ -0,0 +1,87 @@
+---
+title: Telephony Overview
+sidebarTitle: Overview
+description: "Connect telephony providers to your Pipecat Cloud agents"
+---
+
+Pipecat Cloud supports telephony through two broad approaches: **WebSocket streaming** from a telephony provider, or **Daily PSTN**. Pick the approach that matches how your phone numbers are provisioned and what call-control features you need.
+
+## WebSocket Providers
+
+Telephony providers stream real-time audio to and from your Pipecat Cloud agent over a WebSocket connection. Pipecat Cloud ships dedicated endpoints for the major providers, each with protocol validation for added reliability.
+
+All provider integrations follow a common setup pattern:
+
+1. Get your organization name with `pipecat cloud organizations list`.
+2. Configure the provider's call flow to connect to `wss://{region}.api.pipecat.daily.co/ws/{provider}?serviceHost={agentName}.{organizationName}`.
+3. Assign the configuration to your phone number.
+
+<CardGroup cols={2}>
+  <Card
+    title="Twilio"
+    icon="phone"
+    href="/pipecat-cloud/guides/telephony/twilio-websocket"
+  >
+    Connect Twilio numbers via Media Streams and a TwiML Bin.
+  </Card>
+  <Card
+    title="Telnyx"
+    icon="phone"
+    href="/pipecat-cloud/guides/telephony/telnyx-websocket"
+  >
+    Connect Telnyx numbers via a TeXML Application.
+  </Card>
+  <Card
+    title="Plivo"
+    icon="phone"
+    href="/pipecat-cloud/guides/telephony/plivo-websocket"
+  >
+    Connect Plivo numbers via XML responses from your own server.
+  </Card>
+  <Card
+    title="Exotel"
+    icon="phone"
+    href="/pipecat-cloud/guides/telephony/exotel-websocket"
+  >
+    Connect Exotel numbers via an App Bazaar Voicebot flow.
+  </Card>
+</CardGroup>
+
+## Custom Telephony Providers
+
+If your provider isn't listed above, use the **generic WebSocket endpoint**. It relays messages directly without protocol validation, so your bot is responsible for parsing the provider's format.
+
+<Card
+  title="Generic WebSocket"
+  icon="plug"
+  href="/pipecat-cloud/guides/generic-websocket"
+>
+  Protocol-agnostic WebSocket endpoint for custom telephony providers and other
+  integrations.
+</Card>
+
+## Daily PSTN
+
+Daily provisions phone numbers and delivers calls to your Pipecat Cloud agent through a Daily room — no WebSocket integration required. This approach uses WebRTC under the hood and supports advanced call-control features like transfers.
+
+<CardGroup cols={2}>
+  <Card
+    title="Daily Dial-In"
+    icon="phone"
+    href="/pipecat-cloud/guides/telephony/daily-dial-in"
+  >
+    Receive incoming PSTN calls on a Daily-provisioned number.
+  </Card>
+  <Card
+    title="Daily Dial-Out"
+    icon="phone"
+    href="/pipecat-cloud/guides/telephony/daily-dial-out"
+  >
+    Have your agent place outbound PSTN calls.
+  </Card>
+</CardGroup>
+
+## Common Topics
+
+- **[Regional endpoints](/pipecat-cloud/guides/regions#regional-websocket-endpoints)**: Reduce latency by connecting to the region closest to your agent.
+- **[WebSocket authentication](/pipecat-cloud/guides/websocket-authentication)**: Require HMAC tokens to prevent unauthorized connections to your agent.

pipecat-cloud/guides/websocket-authentication.mdx

@@ -0,0 +1,158 @@
+---
+title: WebSocket Authentication
+description: "Secure your WebSocket connections with HMAC token authentication"
+---
+
+Pipecat Cloud supports optional HMAC token authentication for WebSocket connections. When enabled, clients must obtain a short-lived session token via the `/start` endpoint before connecting, preventing unauthorized session starts.
+
+## How It Works
+
+<Steps>
+  <Step title="Client calls /start">
+    Your client calls the `/start` endpoint with `transport: "websocket"` and
+    your public API key. Pipecat Cloud generates a signed HMAC token and returns
+    it along with the WebSocket URL.
+  </Step>
+  <Step title="Client connects with token">
+    The client connects to the returned WebSocket URL with the token included as
+    a header, query parameter, or URL path segment. No bot is started until the
+    client connects.
+  </Step>
+  <Step title="Pipecat Cloud validates">
+    The token is validated before the WebSocket connection is accepted. Invalid,
+    expired, or replayed tokens are rejected with an HTTP 403 — no bot resources
+    are allocated.
+  </Step>
+</Steps>
+
+## Configuration
+
+WebSocket authentication is controlled by the `websocket_auth` setting in your deployment config. Valid values are:
+
+| Value   | Behavior                                             |
+| ------- | ---------------------------------------------------- |
+| `none`  | No authentication required (default)                 |
+| `token` | Requires an HMAC session token obtained via `/start` |
+
+Set it in your `pcc-deploy.toml`:
+
+```toml pcc-deploy.toml
+agent_name = "my-agent"
+websocket_auth = "token"
+
+[scaling]
+min_agents = 1
+```
+
+## Getting a Token
+
+Call the `/start` endpoint with `transport` set to `"websocket"`:
+
+```bash
+curl -X POST "https://api.pipecat.daily.co/v1/public/my-agent/start" \
+  -H "Authorization: Bearer pk_your_public_key" \
+  -H "Content-Type: application/json" \
+  -d '{"transport": "websocket"}'
+```
+
+Response:
+
+```json
+{
+  "token": "eyJzaCI6Im15LWFnZW50Lm15LW9yZy...",
+  "wsUrl": "wss://us-west.api.pipecat.daily.co/ws/generic/my-agent.my-org",
+  "sessionId": "639f91d8-d511-4677-a83b-bd7564d5d92f"
+}
+```
+
+<Info>
+  Unlike other transport types, `transport: "websocket"` does not start a bot
+  immediately. The bot starts when the client connects to the WebSocket URL.
+</Info>
+
+## Connecting with a Token
+
+Use the `wsUrl` from the `/start` response as your WebSocket endpoint. Always use this URL rather than constructing one manually — the format may change in the future.
+
+The token can be attached to the `wsUrl` in three ways, checked in this order:
+
+### Authorization Header
+
+```
+Authorization: Bearer <token>
+```
+
+<Warning>
+  Browser WebSocket connections cannot set custom headers. Use a query parameter
+  or URL path instead for browser-based clients.
+</Warning>
+
+### Query Parameter
+
+Append `?token=<token>` to the `wsUrl`:
+
+```
+{wsUrl}?token=<token>
+```
+
+### URL Path
+
+Append `/<token>` to the `wsUrl`:
+
+```
+{wsUrl}/<token>
+```
+
+This is the recommended method for telephony providers that don't support query
+parameters (such as Twilio).
+
+## Token Details
+
+- **Lifetime**: 5 minutes from generation. Connect promptly after calling `/start`.
+- **One-time use**: Each token can only be used once. Replayed tokens are rejected.
+- **Scoped**: Tokens are bound to a specific agent and organization. They cannot be used with a different agent.
+
+## Using with Telephony Providers
+
+Telephony providers like Twilio, Plivo, and Telnyx initiate WebSocket connections
+directly — they can't call `/start` themselves. To use token authentication with
+these providers, call `/start` from your existing webhook handler and embed the
+token in the WebSocket URL that you return to the provider.
+
+### Example: Twilio Function
+
+This Twilio Function calls `/start` to get a token, then returns TwiML with the
+authenticated WebSocket URL:
+
+```javascript
+exports.handler = async function (context, event, callback) {
+  // Call PCC /start to get a websocket auth token
+  const startResponse = await fetch(
+    "https://api.pipecat.daily.co/v1/public/my-agent/start",
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${context.PCC_PUBLIC_KEY}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ transport: "websocket" }),
+    },
+  );
+  const { token, wsUrl } = await startResponse.json();
+
+  // Return TwiML with the authenticated WebSocket URL
+  const twiml = new Twilio.twiml.VoiceResponse();
+  const connect = twiml.connect();
+  connect.stream({ url: `${wsUrl}/${token}` });
+  callback(null, twiml);
+};
+```
+
+<Tip>
+  Store your Pipecat Cloud public API key as an environment variable in your
+  Twilio Function settings (e.g., `PCC_PUBLIC_KEY`) rather than hardcoding it.
+</Tip>
+
+The same pattern works for any provider — call `/start` from your webhook handler,
+get the token, and include it in the provider-specific XML response. The token
+goes in the URL path, which is supported by all providers.

pipecat-cloud/security/security-and-compliance.mdx

@@ -124,6 +124,16 @@ Your deployed code remains private and protected through multiple layers:
 - Each organization has separate namespaces
 - Access controls prevent unauthorized access to running containers
 
+## WebSocket Security
+
+### How do I prevent unauthorized access to my WebSocket endpoints?
+
+Pipecat Cloud supports HMAC token authentication for WebSocket connections. When enabled, clients must obtain a short-lived, one-time-use token via the `/start` endpoint before connecting. Tokens are validated before the WebSocket connection is accepted — unauthorized requests never allocate bot resources.
+
+New agents default to requiring token authentication. For telephony providers that connect directly (Twilio, Plivo, etc.), you can set `websocket_auth = "none"` in your deployment config.
+
+See the [WebSocket Authentication guide](/pipecat-cloud/guides/websocket-authentication) for setup instructions and details.
+
 ## Runtime Security
 
 ### Can other customers access my agents or data?