<Stream>

TL;DR

<Stream> the audio of the call to a remote web-socket endpoint.

Need Help? Let's Talk

Join our Discord community - we're here to help.

Description

The <Stream> noun creates a unidirectional audio stream that sends all the audio on the call to the WebSocket service that is specified.

Example

The following example shows the basic use of the <Stream> noun:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Start><Stream url="wss://stream-listener.example.com/my-app"/></Start>
    <Say>You are now being listened to</Say>
    <Pause length="30"/>
    <Say>Bye</say>
</Response>

Attributes

The following attributes are supported:

Attribute Name	Allowed Values	Default Value
name	Any short text	None
url	Absolute URL to a WebSocket service	None
track	inbound_track, outbound_track, or both_tracks	inbound_track
statusCallback	Relative or absolute HTTP URL	None
statusCallbackMethod	GET or POST	POST

Attribute: name

The name attribute specifies a name for this stream that should be unique for the current application. This name is used to allow the stream to be stopped by a <Stop> verb. If multiple <Stream> elements share the same name, only the first such stream will be created and any following stream with the same name will be assumed to refer to the initial identically named stream and will not be recreated.

To stop a stream, use a <Stream> noun with the same name, in the <Stop> verb. For example:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
	<Start><Stream name="my-stream" url="wss://example.com" track="both_tracks"/></Start>
	<Say>This will be sent to the stream</Say>
	<Stop><Stream name="my-stream"/></Stop>
</Response>

If the <Stop> verb is used to stop an unknown stream, the command will be ignored.

Attribute: url

The url attribute must be a valid URL to a websocket address. If the URL is not specified or is not a valid WebSocket URL, it is an error and the application will be stopped. If the connection to the WebSocket fails, it is an error and the application will be stopped.

Attribute: track

The track attribute specifies which side of the conversation should be sent to the WebSocket: setting inbound_track means to send the audio from the caller (the side of the call that started the application) while setting outbound_track means to send the audio that the application is sending to the caller, or if the application is running a <Dial> command - the audio that the other side of the dial is sending. Setting both_tracks means that audio from both sides is sent to the WebSocket.

Attribute: statusCallback

If the statusCallback property is set to a valid HTTP URL, the stream will send HTTP requests to the specified URL when stream events occur. The following parameters will be sent to the status callback URL:

• CallSid - the unique call ID associated with the connected call.
• Session - the session token for the connected call.
• StreamSid - the unique stream identifier for this stream.
• StreamName - the stream name, if the name attribute was defined.
• StreamEvent - the event that caused the call: one of stream-started, stream-stopped, or stream-error.
• StreamError - the error message, if an error has occured.
• Timestamp` - the time of the event in ISO 8601 format.

Attribute: statusCallbackMethod

The HTTP method to use when calling the statusCallback URL.

The Stream Protocol

This protocol is a compatible implementation with the Twilio Steram WebSocket protocol, and this linked document may be consulted for more details.

The Stream WebSocket protocol allows a WebSocket service to listen to audio on a call, by sending messages to the WebSocket service. Each message is a text messages containing a JSON encoded object (parameter list). For each such message, a parameter named event will specify the type of message.

The following messages are sent from the <Stream> noun:

Connected Message

Whenever the WebSocket connects, the first message that the <Stream> noun sends is the Connected Message, which describes the protocol that will be used on the connection.

It has the following parameters:

Parameter	Description
event	The value connected
protocol	A name describing the "protocol" - i.e. the type of messages to be expected on this connection. Supported values: "Call"
version	The semantic version of the protocol

Start Message

This message is sent immediately after the connected message and conveys metadata about the stream that has started.

It has the following parameters:

Parameter	Description
event	The value start
sequenceNumber	A sequence number for this message in the protocol. The first message after connected will have the sequence number "1" and any further message will have a number that is incremented by 1.
streamSid	The unique stream identifier for this stream
start	An object specifying the metadata for the stream contents, see below.

The start object contains the following parameters:

Parameter	Description
streamSid	The unique stream identifier for this stream.
session	The session token for the connected call.
callSid	The unique call ID associated with the connected call.
tracks	An array containing the list of tracks that were requested and for which audio will be sent. Can container either inbound, outbound or both values.
customParameters	An object containing the all the custom parameters for the stream.
mediaFormat	An object specifying the format media payload in Media Messages on this connection. See below.

The mediaFormat object contains the following parameters:

Parameter	Description
encoding	The audio encoding of media payloads. Supported values: audio/x-mulaw
sampleRate	The sample rate inHz of audio payloads. Supported values: 8000
channels	The number of channels in audio payloads. supported values: 1

Stop Message

This message is sent when the stream is either stopped by a <Stop> verb or by the call ending..

It has the following parameters:

Parameter	Description
event	The value stop
sequenceNumber	A sequence number for this message in the protocol. The first message after connected will have the sequence number "1" and any further message will have a number that is incremented by 1.
streamSid	The unique stream identifier for this stream.
stop	An object containing the stream metadata. See below.

The stop object contains the following parameters:

Parameter	Description
session	The session token for the connected call.
callSid	The unique call ID associated with the connected call.

Media Message

This message is sent when audio is received in the call.

It has the following parameters:

Parameter	Description
event	The value media
sequenceNumber	A sequence number for this message in the protocol. The first message after connected will have the sequence number "1" and any further message will have a number that is incremented by 1.
streamSid	The unique stream identifier for this stream.
media	An object containing media metadata and payload. See below.

The media object contains the following parameters:

Parameter	Description
track	The track this media is for, either inbound or outbound.
chunk	The chunk seequence number for this track. Starts with "1" and incremends for each media message for this track.
timestamp	The presentation timestamp in milliseconds from the start of the stream.
payload	The audio payload for this message as raw audio data encoded in base64.

DTMF Message

This message is sent when the someone presses a touch-tone keypad key in the inbound stream.

It has the following parameters:

Parameter	Description
event	The value dtmf
sequenceNumber	A sequence number for this message in the protocol. The first message after connected will have the sequence number "1" and any further message will have a number that is incremented by 1.
streamSid	The unique stream identifier for this stream.
dtmf	An object containing the DTMF data. See below.

The dtmf object contains the following parameters:

Parameter	Description
track	The track this DTMF event is for, either inbound or outbound.
digit	The key that was pressed, either 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, #, or *.