Stream Resource
Support for Twilio Regions
You can use Media Streams in the Ireland (IE1) and Australia (AU1) Regions. To set up Media Streams with these regions, follow the guides for non-US outbound and inbound calls. The default region remains US1.
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).
The SID of the Stream resource.
^MZ[0-9a-fA-F]{32}$Min length: 34Max length: 34The SID of the Account that created this Stream resource.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34The SID of the Call the Stream resource is associated with.
^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34The user-specified name of this Stream, if one was given when the Stream was created. This can be used to stop the Stream.
The status of the Stream. Possible values are stopped and in-progress.
in-progressstoppedThe date and time in GMT that this resource was last updated, specified in RFC 2822 format.
The URI of the resource, relative to https://api.twilio.com.
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Streams.json
The SID of the Account that created this Stream resource.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34application/x-www-form-urlencodedRelative or absolute URL where WebSocket connection will be established.
The user-specified name of this Stream, if one was given when the Stream was created. This can be used to stop the Stream.
Absolute URL to which Twilio sends status callback HTTP requests.
The HTTP method Twilio uses when sending status_callback requests. Possible values are GET and POST. Default is POST.
GETPOSTParameter 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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createStream() {11const stream = await client12.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.streams.create({14name: "My Media Stream",15url: "wss://example.com/a-websocket-server",16});1718console.log(stream.sid);19}2021createStream();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createStream() {11const stream = await client12.calls("CAXXXXXXXXXXXXXXXXXXXXXXXXXXXX")13.streams.create({14name: "My Media Stream",15"parameter1.name": "agent_name",16"parameter1.value": "Mary",17"parameter2.name": "Department",18"parameter2.value": "sales",19url: "wss://example.com/a-websocket-server",20});2122console.log(stream.sid);23}2425createStream();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.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}
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.
The SID of the Account that created this Stream resource.
^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34The SID of the Call the Stream resource is associated with.
^CA[0-9a-fA-F]{32}$Min length: 34Max length: 34The SID or the name of the Stream resource to be stopped
application/x-www-form-urlencodedstoppedAn example request is shown below.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateStream() {11const stream = await client12.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.streams("Sid")14.update({ status: "stopped" });1516console.log(stream.sid);17}1819updateStream();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.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.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateStream() {11const stream = await client12.calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.streams("myStream")14.update({ status: "stopped" });1516console.log(stream.sid);17}1819updateStream();
Response
Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.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}