Skip to contentSkip to navigationSkip to topbar
Twilio Docs
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

Property nameTypePIIDescription
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>
Not PII

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>
Not PII

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

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

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>
Not PII

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

Possible values:
in-progressstopped
date_updatedstring<date-time-rfc-2822>
Not PII

The date and time in GMT that this resource was last updated, specified in RFC 2822 format.

uristring
Not PII

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

Create a Stream resource

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Streams.json

Path parameters

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required
Not PII

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
Not PII

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

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

Request body parameters

Property nameTypeRequiredPIIDescription
Urlstring<uri>required
Not PII

Relative or absolute URL where WebSocket connection will be established.

NamestringOptional
Not PII

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
Not PII

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
Not PII

Absolute URL to which Twilio sends status callback HTTP requests.

StatusCallbackMethodenum<http-method>Optional
Not PII

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

Possible values:
GETPOST
Parameter1.NamestringOptional
Not PII

Parameter name

Parameter1.ValuestringOptional
Not PII

Parameter value

Parameter2.NamestringOptional
Not PII

Parameter name

Parameter2.ValuestringOptional
Not PII

Parameter value

Parameter3.NamestringOptional
Not PII

Parameter name

Parameter3.ValuestringOptional
Not PII

Parameter value

Parameter4.NamestringOptional
Not PII

Parameter name

Parameter4.ValuestringOptional
Not PII

Parameter value

Parameter5.NamestringOptional
Not PII

Parameter name

Parameter5.ValuestringOptional
Not PII

Parameter value

Parameter6.NamestringOptional
Not PII

Parameter name

Parameter6.ValuestringOptional
Not PII

Parameter value

Parameter7.NamestringOptional
Not PII

Parameter name

Parameter7.ValuestringOptional
Not PII

Parameter value

Parameter8.NamestringOptional
Not PII

Parameter name

Parameter8.ValuestringOptional
Not PII

Parameter value

Parameter9.NamestringOptional
Not PII

Parameter name

Parameter9.ValuestringOptional
Not PII

Parameter value

Parameter10.NamestringOptional
Not PII

Parameter name

Parameter10.ValuestringOptional
Not PII

Parameter value

Parameter11.NamestringOptional
Not PII

Parameter name

Parameter11.ValuestringOptional
Not PII

Parameter value

Parameter12.NamestringOptional
Not PII

Parameter name

Parameter12.ValuestringOptional
Not PII

Parameter value

Parameter13.NamestringOptional
Not PII

Parameter name

Parameter13.ValuestringOptional
Not PII

Parameter value

Parameter14.NamestringOptional
Not PII

Parameter name

Parameter14.ValuestringOptional
Not PII

Parameter value

Parameter15.NamestringOptional
Not PII

Parameter name

Parameter15.ValuestringOptional
Not PII

Parameter value

Parameter16.NamestringOptional
Not PII

Parameter name

Parameter16.ValuestringOptional
Not PII

Parameter value

Parameter17.NamestringOptional
Not PII

Parameter name

Parameter17.ValuestringOptional
Not PII

Parameter value

Parameter18.NamestringOptional
Not PII

Parameter name

Parameter18.ValuestringOptional
Not PII

Parameter value

Parameter19.NamestringOptional
Not PII

Parameter name

Parameter19.ValuestringOptional
Not PII

Parameter value

Parameter20.NamestringOptional
Not PII

Parameter name

Parameter20.ValuestringOptional
Not PII

Parameter value

Parameter21.NamestringOptional
Not PII

Parameter name

Parameter21.ValuestringOptional
Not PII

Parameter value

Parameter22.NamestringOptional
Not PII

Parameter name

Parameter22.ValuestringOptional
Not PII

Parameter value

Parameter23.NamestringOptional
Not PII

Parameter name

Parameter23.ValuestringOptional
Not PII

Parameter value

Parameter24.NamestringOptional
Not PII

Parameter name

Parameter24.ValuestringOptional
Not PII

Parameter value

Parameter25.NamestringOptional
Not PII

Parameter name

Parameter25.ValuestringOptional
Not PII

Parameter value

Parameter26.NamestringOptional
Not PII

Parameter name

Parameter26.ValuestringOptional
Not PII

Parameter value

Parameter27.NamestringOptional
Not PII

Parameter name

Parameter27.ValuestringOptional
Not PII

Parameter value

Parameter28.NamestringOptional
Not PII

Parameter name

Parameter28.ValuestringOptional
Not PII

Parameter value

Parameter29.NamestringOptional
Not PII

Parameter name

Parameter29.ValuestringOptional
Not PII

Parameter value

Parameter30.NamestringOptional
Not PII

Parameter name

Parameter30.ValuestringOptional
Not PII

Parameter value

Parameter31.NamestringOptional
Not PII

Parameter name

Parameter31.ValuestringOptional
Not PII

Parameter value

Parameter32.NamestringOptional
Not PII

Parameter name

Parameter32.ValuestringOptional
Not PII

Parameter value

Parameter33.NamestringOptional
Not PII

Parameter name

Parameter33.ValuestringOptional
Not PII

Parameter value

Parameter34.NamestringOptional
Not PII

Parameter name

Parameter34.ValuestringOptional
Not PII

Parameter value

Parameter35.NamestringOptional
Not PII

Parameter name

Parameter35.ValuestringOptional
Not PII

Parameter value

Parameter36.NamestringOptional
Not PII

Parameter name

Parameter36.ValuestringOptional
Not PII

Parameter value

Parameter37.NamestringOptional
Not PII

Parameter name

Parameter37.ValuestringOptional
Not PII

Parameter value

Parameter38.NamestringOptional
Not PII

Parameter name

Parameter38.ValuestringOptional
Not PII

Parameter value

Parameter39.NamestringOptional
Not PII

Parameter name

Parameter39.ValuestringOptional
Not PII

Parameter value

Parameter40.NamestringOptional
Not PII

Parameter name

Parameter40.ValuestringOptional
Not PII

Parameter value

Parameter41.NamestringOptional
Not PII

Parameter name

Parameter41.ValuestringOptional
Not PII

Parameter value

Parameter42.NamestringOptional
Not PII

Parameter name

Parameter42.ValuestringOptional
Not PII

Parameter value

Parameter43.NamestringOptional
Not PII

Parameter name

Parameter43.ValuestringOptional
Not PII

Parameter value

Parameter44.NamestringOptional
Not PII

Parameter name

Parameter44.ValuestringOptional
Not PII

Parameter value

Parameter45.NamestringOptional
Not PII

Parameter name

Parameter45.ValuestringOptional
Not PII

Parameter value

Parameter46.NamestringOptional
Not PII

Parameter name

Parameter46.ValuestringOptional
Not PII

Parameter value

Parameter47.NamestringOptional
Not PII

Parameter name

Parameter47.ValuestringOptional
Not PII

Parameter value

Parameter48.NamestringOptional
Not PII

Parameter name

Parameter48.ValuestringOptional
Not PII

Parameter value

Parameter49.NamestringOptional
Not PII

Parameter name

Parameter49.ValuestringOptional
Not PII

Parameter value

Parameter50.NamestringOptional
Not PII

Parameter name

Parameter50.ValuestringOptional
Not PII

Parameter value

Parameter51.NamestringOptional
Not PII

Parameter name

Parameter51.ValuestringOptional
Not PII

Parameter value

Parameter52.NamestringOptional
Not PII

Parameter name

Parameter52.ValuestringOptional
Not PII

Parameter value

Parameter53.NamestringOptional
Not PII

Parameter name

Parameter53.ValuestringOptional
Not PII

Parameter value

Parameter54.NamestringOptional
Not PII

Parameter name

Parameter54.ValuestringOptional
Not PII

Parameter value

Parameter55.NamestringOptional
Not PII

Parameter name

Parameter55.ValuestringOptional
Not PII

Parameter value

Parameter56.NamestringOptional
Not PII

Parameter name

Parameter56.ValuestringOptional
Not PII

Parameter value

Parameter57.NamestringOptional
Not PII

Parameter name

Parameter57.ValuestringOptional
Not PII

Parameter value

Parameter58.NamestringOptional
Not PII

Parameter name

Parameter58.ValuestringOptional
Not PII

Parameter value

Parameter59.NamestringOptional
Not PII

Parameter name

Parameter59.ValuestringOptional
Not PII

Parameter value

Parameter60.NamestringOptional
Not PII

Parameter name

Parameter60.ValuestringOptional
Not PII

Parameter value

Parameter61.NamestringOptional
Not PII

Parameter name

Parameter61.ValuestringOptional
Not PII

Parameter value

Parameter62.NamestringOptional
Not PII

Parameter name

Parameter62.ValuestringOptional
Not PII

Parameter value

Parameter63.NamestringOptional
Not PII

Parameter name

Parameter63.ValuestringOptional
Not PII

Parameter value

Parameter64.NamestringOptional
Not PII

Parameter name

Parameter64.ValuestringOptional
Not PII

Parameter value

Parameter65.NamestringOptional
Not PII

Parameter name

Parameter65.ValuestringOptional
Not PII

Parameter value

Parameter66.NamestringOptional
Not PII

Parameter name

Parameter66.ValuestringOptional
Not PII

Parameter value

Parameter67.NamestringOptional
Not PII

Parameter name

Parameter67.ValuestringOptional
Not PII

Parameter value

Parameter68.NamestringOptional
Not PII

Parameter name

Parameter68.ValuestringOptional
Not PII

Parameter value

Parameter69.NamestringOptional
Not PII

Parameter name

Parameter69.ValuestringOptional
Not PII

Parameter value

Parameter70.NamestringOptional
Not PII

Parameter name

Parameter70.ValuestringOptional
Not PII

Parameter value

Parameter71.NamestringOptional
Not PII

Parameter name

Parameter71.ValuestringOptional
Not PII

Parameter value

Parameter72.NamestringOptional
Not PII

Parameter name

Parameter72.ValuestringOptional
Not PII

Parameter value

Parameter73.NamestringOptional
Not PII

Parameter name

Parameter73.ValuestringOptional
Not PII

Parameter value

Parameter74.NamestringOptional
Not PII

Parameter name

Parameter74.ValuestringOptional
Not PII

Parameter value

Parameter75.NamestringOptional
Not PII

Parameter name

Parameter75.ValuestringOptional
Not PII

Parameter value

Parameter76.NamestringOptional
Not PII

Parameter name

Parameter76.ValuestringOptional
Not PII

Parameter value

Parameter77.NamestringOptional
Not PII

Parameter name

Parameter77.ValuestringOptional
Not PII

Parameter value

Parameter78.NamestringOptional
Not PII

Parameter name

Parameter78.ValuestringOptional
Not PII

Parameter value

Parameter79.NamestringOptional
Not PII

Parameter name

Parameter79.ValuestringOptional
Not PII

Parameter value

Parameter80.NamestringOptional
Not PII

Parameter name

Parameter80.ValuestringOptional
Not PII

Parameter value

Parameter81.NamestringOptional
Not PII

Parameter name

Parameter81.ValuestringOptional
Not PII

Parameter value

Parameter82.NamestringOptional
Not PII

Parameter name

Parameter82.ValuestringOptional
Not PII

Parameter value

Parameter83.NamestringOptional
Not PII

Parameter name

Parameter83.ValuestringOptional
Not PII

Parameter value

Parameter84.NamestringOptional
Not PII

Parameter name

Parameter84.ValuestringOptional
Not PII

Parameter value

Parameter85.NamestringOptional
Not PII

Parameter name

Parameter85.ValuestringOptional
Not PII

Parameter value

Parameter86.NamestringOptional
Not PII

Parameter name

Parameter86.ValuestringOptional
Not PII

Parameter value

Parameter87.NamestringOptional
Not PII

Parameter name

Parameter87.ValuestringOptional
Not PII

Parameter value

Parameter88.NamestringOptional
Not PII

Parameter name

Parameter88.ValuestringOptional
Not PII

Parameter value

Parameter89.NamestringOptional
Not PII

Parameter name

Parameter89.ValuestringOptional
Not PII

Parameter value

Parameter90.NamestringOptional
Not PII

Parameter name

Parameter90.ValuestringOptional
Not PII

Parameter value

Parameter91.NamestringOptional
Not PII

Parameter name

Parameter91.ValuestringOptional
Not PII

Parameter value

Parameter92.NamestringOptional
Not PII

Parameter name

Parameter92.ValuestringOptional
Not PII

Parameter value

Parameter93.NamestringOptional
Not PII

Parameter name

Parameter93.ValuestringOptional
Not PII

Parameter value

Parameter94.NamestringOptional
Not PII

Parameter name

Parameter94.ValuestringOptional
Not PII

Parameter value

Parameter95.NamestringOptional
Not PII

Parameter name

Parameter95.ValuestringOptional
Not PII

Parameter value

Parameter96.NamestringOptional
Not PII

Parameter name

Parameter96.ValuestringOptional
Not PII

Parameter value

Parameter97.NamestringOptional
Not PII

Parameter name

Parameter97.ValuestringOptional
Not PII

Parameter value

Parameter98.NamestringOptional
Not PII

Parameter name

Parameter98.ValuestringOptional
Not PII

Parameter value

Parameter99.NamestringOptional
Not PII

Parameter name

Parameter99.ValuestringOptional
Not PII

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_10
{
_10
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_10
}

Custom parameters

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

Output

_10
{
_10
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"sid": "MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_10
}

Update a Stream resource

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.

Path parameters

Property nameTypeRequiredPIIDescription
AccountSidSID<AC>required
Not PII

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
Not PII

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

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

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

Request body parameters

Property nameTypeRequiredPIIDescription
Statusenum<string>required
Not PII

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function updateStream() {
_19
const stream = await client
_19
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19
.streams("Sid")
_19
.update({ status: "stopped" });
_19
_19
console.log(stream.sid);
_19
}
_19
_19
updateStream();

Output

_10
{
_10
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10
"call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_10
"sid": "Sid",
_10
"name": null,
_10
"status": "stopped",
_10
"date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
_10
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Streams/MZaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
_19
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19
const authToken = process.env.TWILIO_AUTH_TOKEN;
_19
const client = twilio(accountSid, authToken);
_19
_19
async function updateStream() {
_19
const stream = await client
_19
.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_19
.streams("myStream")
_19
.update({ status: "stopped" });
_19
_19
console.log(stream.sid);
_19
}
_19
_19
updateStream();

Output

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

Rate this page: