Skip to contentSkip to navigationSkip to topbar
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
Property nameTypeRequiredDescriptionChild properties
sidSID<MZ>Optional
Not PII

The SID of the Stream resource.

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

account_sidSID<AC>Optional

The SID of the Account that created this Stream resource.

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

call_sidSID<CA>Optional

The SID of the Call the Stream resource is associated with.

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

namestringOptional

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>Optional

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

Possible values:
in-progressstopped

date_updatedstring<date-time-rfc-2822>Optional

uristringOptional

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
Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required

The SID of the Account 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 the Stream resource is associated with.

Pattern: ^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Urlstring<uri>required

Relative or absolute URL where WebSocket connection will be established.


NamestringOptional

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>Optional

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>Optional

Absolute URL to which Twilio sends status callback HTTP requests.


StatusCallbackMethodenum<http-method>Optional

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

Possible values:
GETPOST

Parameter1.NamestringOptional

Parameter name


Parameter1.ValuestringOptional

Parameter value


Parameter2.NamestringOptional

Parameter name


Parameter2.ValuestringOptional

Parameter value


Parameter3.NamestringOptional

Parameter name


Parameter3.ValuestringOptional

Parameter value


Parameter4.NamestringOptional

Parameter name


Parameter4.ValuestringOptional

Parameter value


Parameter5.NamestringOptional

Parameter name


Parameter5.ValuestringOptional

Parameter value


Parameter6.NamestringOptional

Parameter name


Parameter6.ValuestringOptional

Parameter value


Parameter7.NamestringOptional

Parameter name


Parameter7.ValuestringOptional

Parameter value


Parameter8.NamestringOptional

Parameter name


Parameter8.ValuestringOptional

Parameter value


Parameter9.NamestringOptional

Parameter name


Parameter9.ValuestringOptional

Parameter value


Parameter10.NamestringOptional

Parameter name


Parameter10.ValuestringOptional

Parameter value


Parameter11.NamestringOptional

Parameter name


Parameter11.ValuestringOptional

Parameter value


Parameter12.NamestringOptional

Parameter name


Parameter12.ValuestringOptional

Parameter value


Parameter13.NamestringOptional

Parameter name


Parameter13.ValuestringOptional

Parameter value


Parameter14.NamestringOptional

Parameter name


Parameter14.ValuestringOptional

Parameter value


Parameter15.NamestringOptional

Parameter name


Parameter15.ValuestringOptional

Parameter value


Parameter16.NamestringOptional

Parameter name


Parameter16.ValuestringOptional

Parameter value


Parameter17.NamestringOptional

Parameter name


Parameter17.ValuestringOptional

Parameter value


Parameter18.NamestringOptional

Parameter name


Parameter18.ValuestringOptional

Parameter value


Parameter19.NamestringOptional

Parameter name


Parameter19.ValuestringOptional

Parameter value


Parameter20.NamestringOptional

Parameter name


Parameter20.ValuestringOptional

Parameter value


Parameter21.NamestringOptional

Parameter name


Parameter21.ValuestringOptional

Parameter value


Parameter22.NamestringOptional

Parameter name


Parameter22.ValuestringOptional

Parameter value


Parameter23.NamestringOptional

Parameter name


Parameter23.ValuestringOptional

Parameter value


Parameter24.NamestringOptional

Parameter name


Parameter24.ValuestringOptional

Parameter value


Parameter25.NamestringOptional

Parameter name


Parameter25.ValuestringOptional

Parameter value


Parameter26.NamestringOptional

Parameter name


Parameter26.ValuestringOptional

Parameter value


Parameter27.NamestringOptional

Parameter name


Parameter27.ValuestringOptional

Parameter value


Parameter28.NamestringOptional

Parameter name


Parameter28.ValuestringOptional

Parameter value


Parameter29.NamestringOptional

Parameter name


Parameter29.ValuestringOptional

Parameter value


Parameter30.NamestringOptional

Parameter name


Parameter30.ValuestringOptional

Parameter value


Parameter31.NamestringOptional

Parameter name


Parameter31.ValuestringOptional

Parameter value


Parameter32.NamestringOptional

Parameter name


Parameter32.ValuestringOptional

Parameter value


Parameter33.NamestringOptional

Parameter name


Parameter33.ValuestringOptional

Parameter value


Parameter34.NamestringOptional

Parameter name


Parameter34.ValuestringOptional

Parameter value


Parameter35.NamestringOptional

Parameter name


Parameter35.ValuestringOptional

Parameter value


Parameter36.NamestringOptional

Parameter name


Parameter36.ValuestringOptional

Parameter value


Parameter37.NamestringOptional

Parameter name


Parameter37.ValuestringOptional

Parameter value


Parameter38.NamestringOptional

Parameter name


Parameter38.ValuestringOptional

Parameter value


Parameter39.NamestringOptional

Parameter name


Parameter39.ValuestringOptional

Parameter value


Parameter40.NamestringOptional

Parameter name


Parameter40.ValuestringOptional

Parameter value


Parameter41.NamestringOptional

Parameter name


Parameter41.ValuestringOptional

Parameter value


Parameter42.NamestringOptional

Parameter name


Parameter42.ValuestringOptional

Parameter value


Parameter43.NamestringOptional

Parameter name


Parameter43.ValuestringOptional

Parameter value


Parameter44.NamestringOptional

Parameter name


Parameter44.ValuestringOptional

Parameter value


Parameter45.NamestringOptional

Parameter name


Parameter45.ValuestringOptional

Parameter value


Parameter46.NamestringOptional

Parameter name


Parameter46.ValuestringOptional

Parameter value


Parameter47.NamestringOptional

Parameter name


Parameter47.ValuestringOptional

Parameter value


Parameter48.NamestringOptional

Parameter name


Parameter48.ValuestringOptional

Parameter value


Parameter49.NamestringOptional

Parameter name


Parameter49.ValuestringOptional

Parameter value


Parameter50.NamestringOptional

Parameter name


Parameter50.ValuestringOptional

Parameter value


Parameter51.NamestringOptional

Parameter name


Parameter51.ValuestringOptional

Parameter value


Parameter52.NamestringOptional

Parameter name


Parameter52.ValuestringOptional

Parameter value


Parameter53.NamestringOptional

Parameter name


Parameter53.ValuestringOptional

Parameter value


Parameter54.NamestringOptional

Parameter name


Parameter54.ValuestringOptional

Parameter value


Parameter55.NamestringOptional

Parameter name


Parameter55.ValuestringOptional

Parameter value


Parameter56.NamestringOptional

Parameter name


Parameter56.ValuestringOptional

Parameter value


Parameter57.NamestringOptional

Parameter name


Parameter57.ValuestringOptional

Parameter value


Parameter58.NamestringOptional

Parameter name


Parameter58.ValuestringOptional

Parameter value


Parameter59.NamestringOptional

Parameter name


Parameter59.ValuestringOptional

Parameter value


Parameter60.NamestringOptional

Parameter name


Parameter60.ValuestringOptional

Parameter value


Parameter61.NamestringOptional

Parameter name


Parameter61.ValuestringOptional

Parameter value


Parameter62.NamestringOptional

Parameter name


Parameter62.ValuestringOptional

Parameter value


Parameter63.NamestringOptional

Parameter name


Parameter63.ValuestringOptional

Parameter value


Parameter64.NamestringOptional

Parameter name


Parameter64.ValuestringOptional

Parameter value


Parameter65.NamestringOptional

Parameter name


Parameter65.ValuestringOptional

Parameter value


Parameter66.NamestringOptional

Parameter name


Parameter66.ValuestringOptional

Parameter value


Parameter67.NamestringOptional

Parameter name


Parameter67.ValuestringOptional

Parameter value


Parameter68.NamestringOptional

Parameter name


Parameter68.ValuestringOptional

Parameter value


Parameter69.NamestringOptional

Parameter name


Parameter69.ValuestringOptional

Parameter value


Parameter70.NamestringOptional

Parameter name


Parameter70.ValuestringOptional

Parameter value


Parameter71.NamestringOptional

Parameter name


Parameter71.ValuestringOptional

Parameter value


Parameter72.NamestringOptional

Parameter name


Parameter72.ValuestringOptional

Parameter value


Parameter73.NamestringOptional

Parameter name


Parameter73.ValuestringOptional

Parameter value


Parameter74.NamestringOptional

Parameter name


Parameter74.ValuestringOptional

Parameter value


Parameter75.NamestringOptional

Parameter name


Parameter75.ValuestringOptional

Parameter value


Parameter76.NamestringOptional

Parameter name


Parameter76.ValuestringOptional

Parameter value


Parameter77.NamestringOptional

Parameter name


Parameter77.ValuestringOptional

Parameter value


Parameter78.NamestringOptional

Parameter name


Parameter78.ValuestringOptional

Parameter value


Parameter79.NamestringOptional

Parameter name


Parameter79.ValuestringOptional

Parameter value


Parameter80.NamestringOptional

Parameter name


Parameter80.ValuestringOptional

Parameter value


Parameter81.NamestringOptional

Parameter name


Parameter81.ValuestringOptional

Parameter value


Parameter82.NamestringOptional

Parameter name


Parameter82.ValuestringOptional

Parameter value


Parameter83.NamestringOptional

Parameter name


Parameter83.ValuestringOptional

Parameter value


Parameter84.NamestringOptional

Parameter name


Parameter84.ValuestringOptional

Parameter value


Parameter85.NamestringOptional

Parameter name


Parameter85.ValuestringOptional

Parameter value


Parameter86.NamestringOptional

Parameter name


Parameter86.ValuestringOptional

Parameter value


Parameter87.NamestringOptional

Parameter name


Parameter87.ValuestringOptional

Parameter value


Parameter88.NamestringOptional

Parameter name


Parameter88.ValuestringOptional

Parameter value


Parameter89.NamestringOptional

Parameter name


Parameter89.ValuestringOptional

Parameter value


Parameter90.NamestringOptional

Parameter name


Parameter90.ValuestringOptional

Parameter value


Parameter91.NamestringOptional

Parameter name


Parameter91.ValuestringOptional

Parameter value


Parameter92.NamestringOptional

Parameter name


Parameter92.ValuestringOptional

Parameter value


Parameter93.NamestringOptional

Parameter name


Parameter93.ValuestringOptional

Parameter value


Parameter94.NamestringOptional

Parameter name


Parameter94.ValuestringOptional

Parameter value


Parameter95.NamestringOptional

Parameter name


Parameter95.ValuestringOptional

Parameter value


Parameter96.NamestringOptional

Parameter name


Parameter96.ValuestringOptional

Parameter value


Parameter97.NamestringOptional

Parameter name


Parameter97.ValuestringOptional

Parameter value


Parameter98.NamestringOptional

Parameter name


Parameter98.ValuestringOptional

Parameter value


Parameter99.NamestringOptional

Parameter name


Parameter99.ValuestringOptional

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 callLink to code sample: Start a unidirectional Media Stream on a live call
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createStream() {
11
const stream = await client
12
.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
.streams.create({
14
name: "My Media Stream",
15
url: "wss://example.com/a-websocket-server",
16
});
17
18
console.log(stream.sid);
19
}
20
21
createStream();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
"sid": "MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"name": "My Media Stream",
6
"status": "in-progress",
7
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
8
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
9
}

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 parametersLink to code sample: Start a unidirectional Media Stream with custom parameters
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createStream() {
11
const stream = await client
12
.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
13
.streams.create({
14
name: "My Media Stream",
15
"parameter1.name": "agent_name",
16
"parameter1.value": "Mary",
17
"parameter2.name": "Department",
18
"parameter2.value": "sales",
19
url: "wss://example.com/a-websocket-server",
20
});
21
22
console.log(stream.sid);
23
}
24
25
createStream();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
4
"sid": "MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"name": "My Media Stream",
6
"status": "in-progress",
7
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
8
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
9
}

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.

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required

The SID of the Account 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 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

Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
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.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function updateStream() {
11
const stream = await client
12
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.streams("Sid")
14
.update({ status: "stopped" });
15
16
console.log(stream.sid);
17
}
18
19
updateStream();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"sid": "Sid",
5
"name": null,
6
"status": "stopped",
7
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
8
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
9
}

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 nameLink to code sample: Stop a unidirectional Media Stream by name
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function updateStream() {
11
const stream = await client
12
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
.streams("myStream")
14
.update({ status: "stopped" });
15
16
console.log(stream.sid);
17
}
18
19
updateStream();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"sid": "myStream",
5
"name": "myStream",
6
"status": "stopped",
7
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
8
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
9
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.