diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-start.json b/api-reference/pipecat-cloud/rest-reference/openapi-start.json index 5352eae5..916d3b3a 100644 --- a/api-reference/pipecat-cloud/rest-reference/openapi-start.json +++ b/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)", diff --git a/docs.json b/docs.json index a9dc979b..8b37ea6c 100644 --- a/docs.json +++ b/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", diff --git a/pipecat-cloud/fundamentals/deploy.mdx b/pipecat-cloud/fundamentals/deploy.mdx index 8ce46b63..507bba9c 100644 --- a/pipecat-cloud/fundamentals/deploy.mdx +++ b/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 diff --git a/pipecat-cloud/guides/generic-websocket.mdx b/pipecat-cloud/guides/generic-websocket.mdx new file mode 100644 index 00000000..4491bc50 --- /dev/null +++ b/pipecat-cloud/guides/generic-websocket.mdx @@ -0,0 +1,49 @@ +--- +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 + +- **Telephony providers**: Connect any telephony provider that supports WebSocket audio streaming. +- **Server-to-server integrations**: Connect your own backend or a third-party platform over WebSocket. +- **Custom WebSocket clients**: Any client that can establish a WebSocket connection. + + + **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. + + +## 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. diff --git a/pipecat-cloud/guides/telephony/overview.mdx b/pipecat-cloud/guides/telephony/overview.mdx new file mode 100644 index 00000000..2b01bc23 --- /dev/null +++ b/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. + + + + Connect Twilio numbers via Media Streams and a TwiML Bin. + + + Connect Telnyx numbers via a TeXML Application. + + + Connect Plivo numbers via XML responses from your own server. + + + Connect Exotel numbers via an App Bazaar Voicebot flow. + + + +## 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. + + + Protocol-agnostic WebSocket endpoint for custom telephony providers and other + integrations. + + +## 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. + + + + Receive incoming PSTN calls on a Daily-provisioned number. + + + Have your agent place outbound PSTN calls. + + + +## 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. diff --git a/pipecat-cloud/guides/websocket-authentication.mdx b/pipecat-cloud/guides/websocket-authentication.mdx new file mode 100644 index 00000000..4a30d63b --- /dev/null +++ b/pipecat-cloud/guides/websocket-authentication.mdx @@ -0,0 +1,153 @@ +--- +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 + + + + 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. + + + 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. + + + 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. + + + +## 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" +} +``` + + + Unlike other transport types, `transport: "websocket"` does not start a bot + immediately. The bot starts when the client connects to the WebSocket URL. + + +## 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 +``` + +### Query Parameter + +Append `?token=` to the `wsUrl`: + +``` +{wsUrl}?token= +``` + +### URL Path + +Append `/` to the `wsUrl`: + +``` +{wsUrl}/ +``` + +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); +}; +``` + + + 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. + + +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. diff --git a/pipecat-cloud/security/security-and-compliance.mdx b/pipecat-cloud/security/security-and-compliance.mdx index 97717dcd..d71ab165 100644 --- a/pipecat-cloud/security/security-and-compliance.mdx +++ b/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?