Add new stream attributes (#546)

Devon-White · web-flow · commit db5c00d7b9b2 · 2025-09-25T14:14:41.000-04:00
* Add new stream attributes

* fix link
diff --git a/website/docs/main/compatibility-api/cxml/voice/stream.mdx b/website/docs/main/compatibility-api/cxml/voice/stream.mdx
@@ -112,8 +112,10 @@ puts response
 |                                                             Attribute |                                                                                                                                                                                                                              |
 | --------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 |                 `url` <span className="required-arg">required</span>  | Absolute or relative URL. A WebSocket connection to the url will be established and audio will start flowing towards the Websocket server. The only supported protocol is `wss`. For security reasons `ws` is NOT supported. |
+|                 `authBearerToken` <span className="optional-arg">optional</span> | A authentication Bearer token that can be supplied when starting a stream. The remote server can then authenticate the websocket connection request from the supplied token. More information can be found in the [WebSocket connection](#websocket-connection) section. |
 |                 `codec` <span className="optional-arg">optional</span> | The codecs attribute allows you to control the set codec to be used on the stream. **Possible Values**: `L16@24000h` & `L16@16000h` |
 |                 `name` <span className="optional-arg">optional</span> | Unique name for the Stream, per Call. It is used to stop a Stream by name.                                                                                                                                                   |
+|                 `realtime` <span className="optional-arg">optional</span> | If `true`, and the stream is [`bidirectional`](/compatibility-api/cxml/voice/connect#bidirectional-media-stream), the stream offers a realtime experience to the call parties by managing packet delays and bursts. If `false`, the use benefits from buffered audio, which can be played out with delay. Default: `false` |
 |                `track` <span className="optional-arg">optional</span> | This attribute can be one of: `inbound_track`, `outbound_track`, `both_tracks` . Defaults to `inbound_track`. For `both_tracks` there will be both `inbound_track` and `outbound_track` events.                              |
 |       `statusCallback` <span className="optional-arg">optional</span> | Absolute or relative URL. SignalWire will make a HTTP GET or POST request to this URL when a Stream is started, stopped or there is an error.                                                                                |
 | `statusCallbackMethod` <span className="optional-arg">optional</span> | GET or POST. The type of HTTP request to use when requesting a statusCallback. Default is POST.                                                                                                                              |
@@ -133,6 +135,7 @@ You can utilize our REST API to both [start][stream_start] and [stop][stream_sto
 |                 `url` <span className="required-arg">required</span>  | Absolute or relative URL. A WebSocket connection to the url will be established and audio will start flowing towards the Websocket server. The only supported protocol is `wss`. For security reasons `ws` is NOT supported. |
 |                 `codec` <span className="optional-arg">optional</span> | The codecs attribute allows you to control the set codec to be used on the stream. **Possible Values**: `L16@24000h` & `L16@16000h` |
 |                 `name` <span className="required-arg">required</span> | Unique name for the Stream, per Call. It is used to stop a Stream by name.                                                                                                                                                   |
+|                 `realtime` <span className="optional-arg">optional</span> | If `true`, and the stream is [`bidirectional`](/compatibility-api/cxml/voice/connect#bidirectional-media-stream), the stream offers a realtime experience to the call parties by managing packet delays and bursts. If `false`, the use benefits from buffered audio, which can be played out with delay. Default: `false` |
 |                `track` <span className="optional-arg">optional</span> | This attribute can be one of: `inbound_track`, `outbound_track`, `both_tracks` . Defaults to `inbound_track`. For `both_tracks` there will be both `inbound_track` and `outbound_track` events.                              |
 |       `statusCallback` <span className="optional-arg">optional</span> | Absolute or relative URL. SignalWire will make a HTTP GET or POST request to this URL when a Stream is started, stopped or there is an error.                                                                                |
 | `statusCallbackMethod` <span className="optional-arg">optional</span> | GET or POST. The type of HTTP request to use when requesting a statusCallback. Default is POST.                                                                                                                              |
@@ -148,7 +151,7 @@ You can utilize our REST API to [create][conference_create] and [update][confere
 </TabItem>
 </Tabs>
 
-## `StatusCallback` Parameters
+## `StatusCallback` parameters
 
 For a `statusCallback`, SignalWire will send a request with the following parameters:
 
@@ -162,14 +165,32 @@ For a `statusCallback`, SignalWire will send a request with the following parame
 | `StreamError` <span className="optional-arg">string</span> | If an error has occurred, this will contain a detailed error message.                           |
 |   `Timestamp` <span className="optional-arg">string</span> | The time of the event in ISO 8601 format.                                                       |
 
-## WebSocket Messages
 
-There are 5 separate types of events that occur during the Stream's life cycle.
-These events are represented via WebSocket Messages: `Connected`, `Start`, `Media`, `DTMF` and `Stop`.
-Each message sent is a JSON string.
-The type of event which is occurring can be identified by using the `event` property of every JSON object.
 
-### Connected Message
+## WebSocket connection
+
+When establishing a stream, SignalWire initiates a WebSocket connection to your specified URL endpoint. The connection begins with an HTTP upgrade request containing the following headers:
+
+| Header | Description |
+| :----| :----- |
+| Host | The destination server hosting the WebSocket endpoint (e.g., "example.com") |
+| Upgrade | Protocol upgrade request indicating a switch to WebSocket (value: "websocket") |
+| Connection | Connection type for the upgrade (value: "Upgrade") |
+| Sec-WebSocket-Key | Base64-encoded random value used for the WebSocket handshake |
+| Sec-WebSocket-Version | WebSocket protocol version (value: "13") |
+| Authorization | Bearer token for authentication if `authBearerToken` attribute is provided (format: "Bearer token_here") |
+
+Once the WebSocket connection is established, SignalWire will send various events throughout the stream's lifecycle.
+These events are delivered as JSON-formatted WebSocket messages, each containing an `event` property that identifies the message type.
+
+The stream supports five distinct event types:
+- **Connected** - Initial handshake message confirming the connection
+- **Start** - Stream metadata and configuration details
+- **Media** - Audio data packets
+- **DTMF** - Touch-tone digit events
+- **Stop** - Stream termination notification
+
+### Connected message
 
 The first message sent once a WebSocket connection is established is the Connected event.
 This message describes the protocol to expect in the following messages.
@@ -180,7 +201,7 @@ This message describes the protocol to expect in the following messages.
 | protocol | Defines the protocol for the WebSocket connections lifetime. eg: "Call" |
 |  version | Semantic version of the protocol.                                       |
 
-Example Connected Message
+Example Connected message
 
 ```json
 {
@@ -190,7 +211,7 @@ Example Connected Message
 }
 ```
 
-### Start Message
+### Start message
 
 This message contains important information about the Stream and is sent immediately after the `Connected` message.
 It is only sent once at the start of the Stream.
@@ -210,7 +231,7 @@ It is only sent once at the start of the Stream.
 | start.mediaFormat.sampleRate | The Sample Rate in Hertz of the upcoming audio data. Default value is 8000, which is the rate of PCMU.                                  |
 |   start.mediaFormat.channels | The number of channels in the input audio data. Default value is 1. For `both_tracks` it will be 2.                                     |
 
-Example Start Message
+Example Start message
 
 ```json
 {
@@ -235,7 +256,7 @@ Example Start Message
 }
 ```
 
-### Media Message
+### Media message
 
 This message type encapsulates the raw audio data.
 
@@ -249,7 +270,7 @@ This message type encapsulates the raw audio data.
 | media.timestamp | Presentation Timestamp in Milliseconds from the start of the stream.                                                               |
 |   media.payload | Raw audio encoded in base64.                                                                                                       |
 
-Example Media Messages
+Example media messages
 
 Outbound
 
@@ -280,11 +301,11 @@ Inbound
 }
 ```
 
-### Stop Message
+### Stop message
 
 A stop message will be sent when the Stream is either stopped or the Call has ended.
 
-Example Stop Message
+Example stop message
 
 ```json
 {
@@ -298,7 +319,7 @@ Example Stop Message
 |          event | The string value of `stop`.                                                                                                        |
 | sequenceNumber | Number used to keep track of message sending order. First message starts with number "1" and then is incremented for each message. |
 
-### DTMF Message
+### DTMF message
 
 A DTMF message will be sent when the Stream receives a DTMF tone.
 
@@ -311,7 +332,7 @@ A DTMF message will be sent when the Stream receives a DTMF tone.
 |   dtmf.duration | The duration of the DTMF in milliseconds.                                                                                                     |
 |      dtmf.digit | The digit, as a string, that corresponds to the DTMF.                                                                                         |
 
-Example DTMF Message
+Example DTMF message
 
 ```json
 {
@@ -325,7 +346,7 @@ Example DTMF Message
 }
 ```
 
-### Clear Message
+### Clear message
 
 Send the clear event message if you would like to interrupt the audio that has been sent various media event messages. This will empty all buffered audio.
 
@@ -334,7 +355,7 @@ Send the clear event message if you would like to interrupt the audio that has b
 |           event | The string value of `clear`.                                                                                                                  |
 |       streamSid | The unique identifier of the stream as a string.                                                                                              |
 
-Example Clear Message
+Example Clear message
 ```json
 { 
  "event": "clear",
@@ -410,7 +431,7 @@ This can be done by using the nested `<Parameter>` cXML noun. These parameters w
 </Response>
 ```
 
-## Notes on Usage
+## Notes on usage
 
 - The url does not support query string parameters. To pass custom key value pairs to the WebSocket, make use of Custom Parameters instead.
 - There is a one to one mapping of a stream to a websocket connection, therefore there will be at most one call being streamed over a single websocket connection. Information will be provided so that you can handle handle multiple inbound connections and manage the association between the unique stream identifier (StreamSid) and the connection.
diff --git a/website/docs/main/compatibility-api/guides/voice/python/utilizing-websockets-and-call-streams/index.mdx b/website/docs/main/compatibility-api/guides/voice/python/utilizing-websockets-and-call-streams/index.mdx
@@ -55,7 +55,7 @@ Then we can use asyncio to create a non-blocking for loop that iterates over the
 Finally, we will parse our messages based on their `event` designation. 
 
 The `start` event provides details such as the callSid, streamSid, the tracks we can expect, and more. We will only use the `callSid` to name and organize our recordings.  
-A full example of what a `start` even returns can be found in our `<stream>` documentation [here](/compatibility-api/cxml/voice/stream#websocket-messages).
+A full example of what a `start` even returns can be found in our `<stream>` documentation [here](/compatibility-api/cxml/voice/stream#websocket-connection).
 
 The `media` events hold the base64-encoded audio that we will use to compile our wave files. We can do this by decoding the base64 and appending the decoded payload to the appropriate list.
 
