Skip to content

Add new stream attributes #546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 25, 2025
Merged

Add new stream attributes #546

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
055ecdc
Add new stream attributes
Devon-White Sep 25, 2025
670bc40
fix link
Devon-White Sep 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 40 additions & 19 deletions website/docs/main/compatibility-api/cxml/voice/stream.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand All @@ -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. |
Expand All @@ -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:

Expand All @@ -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.
Expand All @@ -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
{
Expand All @@ -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.
Expand All @@ -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
{
Expand All @@ -235,7 +256,7 @@ Example Start Message
}
```

### Media Message
### Media message

This message type encapsulates the raw audio data.

Expand All @@ -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

Expand Down Expand Up @@ -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
{
Expand All @@ -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.

Expand All @@ -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
{
Expand All @@ -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.

Expand All @@ -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",
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion ...ibility-api/guides/voice/python/utilizing-websockets-and-call-streams/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down