Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Stream Resource


(information)

Support for Twilio Regions

Media Streams is now available in the Ireland (IE1) and Australia (AU1) Regions.

The Stream resource represents a live audio stream during a live call.

Creating a Stream resource creates a unidirectional Media Stream. You can stop a unidirectional Media Stream by updating the status of a Stream resource, regardless of whether the Stream was created via TwiML (with <Start><Stream>) or via REST API (with the Stream resource).


Stream Properties

stream-properties page anchor
sidSID<MZ>
Not PII

The SID of the Stream resource.

Pattern: ^MZ[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

call_sidSID<CA>

The SID of the Call(link takes you to an external page) the Stream resource is associated with.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

namestring

The user-specified name of this Stream, if one was given when the Stream was created. This can be used to stop the Stream.


statusenum<string>

The status of the Stream. Possible values are stopped and in-progress.

Possible values:
in-progressstopped

date_updatedstring<date-time-rfc-2822>

The date and time in GMT that this resource was last updated, specified in RFC 2822(link takes you to an external page) format.


uristring

The URI of the resource, relative to https://api.twilio.com.


Create a Stream resource

create-a-stream-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Streams.json

Path parameters

path-parameters page anchor
AccountSidSID<AC>required

The SID of the Account(link takes you to an external page) that created this Stream resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

CallSidSID<CA>required

The SID of the Call(link takes you to an external page) the Stream resource is associated with.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34
Urlstring<uri>required

Relative or absolute URL where WebSocket connection will be established.


Namestring

The user-specified name of this Stream, if one was given when the Stream was created. This can be used to stop the Stream.


Trackenum<string>

The tracks to be included in the Stream. Possible values are inbound_track, outbound_track, both_tracks. Default value is inbound_track.

Possible values:
inbound_trackoutbound_trackboth_tracks

StatusCallbackstring<uri>

Absolute URL to which Twilio sends status callback HTTP requests.


StatusCallbackMethodenum<http-method>

The HTTP method Twilio uses when sending status_callback requests. Possible values are GET and POST. Default is POST.

Possible values:
GETPOST

Parameter1.Namestring

Parameter name


Parameter1.Valuestring

Parameter value


Parameter2.Namestring

Parameter name


Parameter2.Valuestring

Parameter value


Parameter3.Namestring

Parameter name


Parameter3.Valuestring

Parameter value


Parameter4.Namestring

Parameter name


Parameter4.Valuestring

Parameter value


Parameter5.Namestring

Parameter name


Parameter5.Valuestring

Parameter value


Parameter6.Namestring

Parameter name


Parameter6.Valuestring

Parameter value


Parameter7.Namestring

Parameter name


Parameter7.Valuestring

Parameter value


Parameter8.Namestring

Parameter name


Parameter8.Valuestring

Parameter value


Parameter9.Namestring

Parameter name


Parameter9.Valuestring

Parameter value


Parameter10.Namestring

Parameter name


Parameter10.Valuestring

Parameter value


Parameter11.Namestring

Parameter name


Parameter11.Valuestring

Parameter value


Parameter12.Namestring

Parameter name


Parameter12.Valuestring

Parameter value


Parameter13.Namestring

Parameter name


Parameter13.Valuestring

Parameter value


Parameter14.Namestring

Parameter name


Parameter14.Valuestring

Parameter value


Parameter15.Namestring

Parameter name


Parameter15.Valuestring

Parameter value


Parameter16.Namestring

Parameter name


Parameter16.Valuestring

Parameter value


Parameter17.Namestring

Parameter name


Parameter17.Valuestring

Parameter value


Parameter18.Namestring

Parameter name


Parameter18.Valuestring

Parameter value


Parameter19.Namestring

Parameter name


Parameter19.Valuestring

Parameter value


Parameter20.Namestring

Parameter name


Parameter20.Valuestring

Parameter value


Parameter21.Namestring

Parameter name


Parameter21.Valuestring

Parameter value


Parameter22.Namestring

Parameter name


Parameter22.Valuestring

Parameter value


Parameter23.Namestring

Parameter name


Parameter23.Valuestring

Parameter value


Parameter24.Namestring

Parameter name


Parameter24.Valuestring

Parameter value


Parameter25.Namestring

Parameter name


Parameter25.Valuestring

Parameter value


Parameter26.Namestring

Parameter name


Parameter26.Valuestring

Parameter value


Parameter27.Namestring

Parameter name


Parameter27.Valuestring

Parameter value


Parameter28.Namestring

Parameter name


Parameter28.Valuestring

Parameter value


Parameter29.Namestring

Parameter name


Parameter29.Valuestring

Parameter value


Parameter30.Namestring

Parameter name


Parameter30.Valuestring

Parameter value


Parameter31.Namestring

Parameter name


Parameter31.Valuestring

Parameter value


Parameter32.Namestring

Parameter name


Parameter32.Valuestring

Parameter value


Parameter33.Namestring

Parameter name


Parameter33.Valuestring

Parameter value


Parameter34.Namestring

Parameter name


Parameter34.Valuestring

Parameter value


Parameter35.Namestring

Parameter name


Parameter35.Valuestring

Parameter value


Parameter36.Namestring

Parameter name


Parameter36.Valuestring

Parameter value


Parameter37.Namestring

Parameter name


Parameter37.Valuestring

Parameter value


Parameter38.Namestring

Parameter name


Parameter38.Valuestring

Parameter value


Parameter39.Namestring

Parameter name


Parameter39.Valuestring

Parameter value


Parameter40.Namestring

Parameter name


Parameter40.Valuestring

Parameter value


Parameter41.Namestring

Parameter name


Parameter41.Valuestring

Parameter value


Parameter42.Namestring

Parameter name


Parameter42.Valuestring

Parameter value


Parameter43.Namestring

Parameter name


Parameter43.Valuestring

Parameter value


Parameter44.Namestring

Parameter name


Parameter44.Valuestring

Parameter value


Parameter45.Namestring

Parameter name


Parameter45.Valuestring

Parameter value


Parameter46.Namestring

Parameter name


Parameter46.Valuestring

Parameter value


Parameter47.Namestring

Parameter name


Parameter47.Valuestring

Parameter value


Parameter48.Namestring

Parameter name


Parameter48.Valuestring

Parameter value


Parameter49.Namestring

Parameter name


Parameter49.Valuestring

Parameter value


Parameter50.Namestring

Parameter name


Parameter50.Valuestring

Parameter value


Parameter51.Namestring

Parameter name


Parameter51.Valuestring

Parameter value


Parameter52.Namestring

Parameter name


Parameter52.Valuestring

Parameter value


Parameter53.Namestring

Parameter name


Parameter53.Valuestring

Parameter value


Parameter54.Namestring

Parameter name


Parameter54.Valuestring

Parameter value


Parameter55.Namestring

Parameter name


Parameter55.Valuestring

Parameter value


Parameter56.Namestring

Parameter name


Parameter56.Valuestring

Parameter value


Parameter57.Namestring

Parameter name


Parameter57.Valuestring

Parameter value


Parameter58.Namestring

Parameter name


Parameter58.Valuestring

Parameter value


Parameter59.Namestring

Parameter name


Parameter59.Valuestring

Parameter value


Parameter60.Namestring

Parameter name


Parameter60.Valuestring

Parameter value


Parameter61.Namestring

Parameter name


Parameter61.Valuestring

Parameter value


Parameter62.Namestring

Parameter name


Parameter62.Valuestring

Parameter value


Parameter63.Namestring

Parameter name


Parameter63.Valuestring

Parameter value


Parameter64.Namestring

Parameter name


Parameter64.Valuestring

Parameter value


Parameter65.Namestring

Parameter name


Parameter65.Valuestring

Parameter value


Parameter66.Namestring

Parameter name


Parameter66.Valuestring

Parameter value


Parameter67.Namestring

Parameter name


Parameter67.Valuestring

Parameter value


Parameter68.Namestring

Parameter name


Parameter68.Valuestring

Parameter value


Parameter69.Namestring

Parameter name


Parameter69.Valuestring

Parameter value


Parameter70.Namestring

Parameter name


Parameter70.Valuestring

Parameter value


Parameter71.Namestring

Parameter name


Parameter71.Valuestring

Parameter value


Parameter72.Namestring

Parameter name


Parameter72.Valuestring

Parameter value


Parameter73.Namestring

Parameter name


Parameter73.Valuestring

Parameter value


Parameter74.Namestring

Parameter name


Parameter74.Valuestring

Parameter value


Parameter75.Namestring

Parameter name


Parameter75.Valuestring

Parameter value


Parameter76.Namestring

Parameter name


Parameter76.Valuestring

Parameter value


Parameter77.Namestring

Parameter name


Parameter77.Valuestring

Parameter value


Parameter78.Namestring

Parameter name


Parameter78.Valuestring

Parameter value


Parameter79.Namestring

Parameter name


Parameter79.Valuestring

Parameter value


Parameter80.Namestring

Parameter name


Parameter80.Valuestring

Parameter value


Parameter81.Namestring

Parameter name


Parameter81.Valuestring

Parameter value


Parameter82.Namestring

Parameter name


Parameter82.Valuestring

Parameter value


Parameter83.Namestring

Parameter name


Parameter83.Valuestring

Parameter value


Parameter84.Namestring

Parameter name


Parameter84.Valuestring

Parameter value


Parameter85.Namestring

Parameter name


Parameter85.Valuestring

Parameter value


Parameter86.Namestring

Parameter name


Parameter86.Valuestring

Parameter value


Parameter87.Namestring

Parameter name


Parameter87.Valuestring

Parameter value


Parameter88.Namestring

Parameter name


Parameter88.Valuestring

Parameter value


Parameter89.Namestring

Parameter name


Parameter89.Valuestring

Parameter value


Parameter90.Namestring

Parameter name


Parameter90.Valuestring

Parameter value


Parameter91.Namestring

Parameter name


Parameter91.Valuestring

Parameter value


Parameter92.Namestring

Parameter name


Parameter92.Valuestring

Parameter value


Parameter93.Namestring

Parameter name


Parameter93.Valuestring

Parameter value


Parameter94.Namestring

Parameter name


Parameter94.Valuestring

Parameter value


Parameter95.Namestring

Parameter name


Parameter95.Valuestring

Parameter value


Parameter96.Namestring

Parameter name


Parameter96.Valuestring

Parameter value


Parameter97.Namestring

Parameter name


Parameter97.Valuestring

Parameter value


Parameter98.Namestring

Parameter name


Parameter98.Valuestring

Parameter value


Parameter99.Namestring

Parameter name


Parameter99.Valuestring

Parameter value

Create a Stream resource during a live call in order to start a new unidirectional Media Stream. Twilio sends the call's forked audio stream to the url specified in this request.

A sample request is shown below.

Start a unidirectional Media Stream on a live call

start-a-unidirectional-media-stream-on-a-live-call page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_14
.streams
_14
.create({
_14
name: 'My Media Stream',
_14
url: 'wss://example.com/a-websocket-server'
_14
})
_14
.then(stream => console.log(stream.sid));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"name": "My Media Stream",
_10
"status": "in-progress",
_10
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Streams/MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}

You can also create a unidirectional Media Stream with custom parameters.

Twilio sends these custom parameters to your WebSocket server in the start WebSocket message. Learn more on the WebSocket Messages page.

Use the parameter[x].name and parameter[x].value parameters to specify key-value pairs. For example, parameter1.name is the key and parameter1.value is the value of a key-value pair. You can provide up to 99 key-value pairs (parameter99.name and parameter99.value).

An example request is shown below.

Start a unidirectional Media Stream with custom parameters

start-a-unidirectional-media-stream-with-custom-parameters page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
_18
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18
const authToken = process.env.TWILIO_AUTH_TOKEN;
_18
const client = require('twilio')(accountSid, authToken);
_18
_18
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_18
.streams
_18
.create({
_18
name: 'My Media Stream',
_18
'parameter1.name': 'agent_name',
_18
'parameter1.value': 'Mary',
_18
'parameter2.name': 'Department',
_18
'parameter2.value': 'sales',
_18
url: 'wss://example.com/a-websocket-server'
_18
})
_18
.then(stream => console.log(stream.sid));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"name": "My Media Stream",
_10
"status": "in-progress",
_10
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Streams/MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}


Update a Stream resource

update-a-stream-resource page anchor
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Streams/{Sid}.json

To stop a live unidirectional Media Stream, update the Stream resource's status to stopped.

AccountSidSID<AC>required

The SID of the Account(link takes you to an external page) that created this Stream resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

CallSidSID<CA>required

The SID of the Call(link takes you to an external page) the Stream resource is associated with.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Sidstringrequired

The SID or the name of the Stream resource to be stopped

Statusenum<string>required

The status of the Stream you wish to stop. Only possible value is stopped.

Possible values:
stopped

An example request is shown below.

Stop a unidirectional Media Stream

stop-a-unidirectional-media-stream page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.streams('MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({status: 'stopped'})
_11
.then(stream => console.log(stream.name));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"name": null,
_10
"status": "stopped",
_10
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Streams/MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}

You can also use the Stream name (if provided when creating the Stream) to stop the Stream. The example below shows how to stop a Stream with a name of myStream.

Stop a unidirectional Media Stream by name

stop-a-unidirectional-media-stream-by-name page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.streams('myStream')
_11
.update({status: 'stopped'})
_11
.then(stream => console.log(stream.name));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"name": "myStream",
_10
"status": "stopped",
_10
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Streams/MZXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}


Rate this page: