Media Streams is now available in the Ireland (IE1) and Australia (AU1) Regions.
The <Stream> instruction allows you to receive raw audio streams from a live phone call over WebSockets in near real-time.
The most basic use of <Stream>:
_10<?xml version="1.0" encoding="UTF-8"?>_10<Response>_10 <Start>_10 <Stream url="wss://mystream.ngrok.io/audiostream" />_10 </Start>_10</Response>
This TwiML will instruct Twilio to fork the audio stream of the current call and send it in real-time over WebSocket to wss://mystream.ngrok.io/audiostream.
The <Start> verb starts the audio <Stream> asynchronously and immediately continues with the next TwiML instruction. If there is no instruction, the call will be disconnected. In order to avoid this, provide a TwiML instruction to continue the call.
If you'd prefer a synchronous bi-directional stream, you should use the <Connect> verb.
There is a one to one mapping of a stream to a WebSocket connection, therefore there will be at most one call being streamed over a single WebSocket connection. Metadata will be provided so that you can handle multiple inbound connections and manage the mappings between the unique stream identifier or StreamSid.
If communication issues are encountered with your WebSocket server, they will be reported in the Twilio Debugger with additional information about the failure.
There are a maximum of 4 forked streams allowed per call. Each track, inbound or outbound, is a forked stream.
<Stream> supports the following attributes:
| Attribute Name | Allowed Values | Default Value |
|---|---|---|
| url | relative or absolute URL | none |
| name | Optional. Unique name for the Stream | none |
| track | Optional. inbound_track, outbound_track, both_tracks | inbound_track |
| statusCallback | Optional. Relative or absolute URL | none |
| statusCallbackMethod | Optional. GET or POST | POST |
The url attribute accepts a relative or absolute url. On successful execution, a WebSocket connection to the url will be established and audio will start streaming.wss is the only supported protocol.
The url does not support query string parameters. To pass custom key value pairs to the WebSocket, make use of Custom Parameters instead.
Providing a name will allow you to reference the stream directly. This name must be unique per Call. For instance, stopping a Stream by name.
The track attribute allows you to optionally request to receive a specific track of a call. On any given active call, there are inbound and outbound tracks. Inbound represents the audio Twilio receives from the call and outbound represents the audio generated by Twilio to the call.
By default, Twilio always streams the inbound track of a call. When a Stream is started using the synchronous bi-directional <Connect> verb, this is your only option.
However, if you are using an asynchronous Stream by using the <Start> verb, you can request the audio it generates by choosing outbound_track. To receive both tracks of a call use both_tracks. If both_tracks is used, you will receive media messages for both tracks (media.track values of outbound and inbound).
The statusCallback attribute takes an absolute or relative URL as value. Whenever a stream is started or stopped, Twilio will make a request to this URL with the following parameters:
| Parameter | Description |
|---|---|
| AccountSid | The unique identifier of the Account responsible for this Stream. |
| CallSid | The unique identifier of the Call |
| StreamSid | The unique identifier for this Stream |
| StreamName | If defined, this is the unique name of the Stream. Defaults to the StreamSid |
| StreamEvent | One of stream-started, stream-stopped, or stream-error (see StreamError for the message) |
| StreamError | If an error has occurred, this will contain a detailed error message. |
| Timestamp | The time of the event in ISO 8601 format |
The HTTP method to use when requesting the statusCallback URL. Default is POST.
It is possible to include additional key value pairs that will passed along with your stream. You can do this by using the nested <Parameter> TwiML noun.
_10<?xml version="1.0" encoding="UTF-8"?>_10<Response>_10 <Start>_10 <Stream url="wss://mystream.ngrok.io/example" >_10 <Parameter name="FirstName" value ="Jane"/>_10 <Parameter name="LastName" value ="Doe" />_10 <Parameter name="RemoteParty" value ="Bob" />_10 </Stream>_10 </Start>_10</Response>
These values will be sent along with the start WebSocket message.
There is a currently a size limitation in the amount of data that can be sent from custom parameters. Aim to keep the total characters of your parameters (both name and value) under 500 characters.
It is possible to stop an asynchronous stream by name. For instance by naming the Stream my_first_stream.
_10<Start>_10 <Stream name="my_first_stream" url="wss://mystream.ngrok.io/audiostream" />_10</Start>
You can later use the unique name of my_first_stream to stop the stream.
_10<Stop>_10 <Stream name="my_first_stream" />_10</Stop>
Start a new asynchronous MediaStream named "Example Audio Stream". The stream will begin sending messages to the url specified over a WebSocket connection.
You can send additional custom information by using the <Parameter> TwiML noun. These values will be delivered in the start WebSocket message in the customParameters section.
If you want to send media back to the call, the Stream *must* be bi-directional. To do this initialize the stream using the <Connect> TwiML verb as opposed to the <Start> verb. The <Stream> noun's url attribute must be set to a secure websocket server (wss).
The <Connect> verb sets up a synchronous bi-directional stream
Media Streams must communicate with Twilio's cloud in order to function. Listed below are the IP address ranges used to communicate with Twilio's cloud. If necessary, use this information to configure your firewall to enable communication with Twilio.
| Edge | Location | Server IP Address Range |
|---|---|---|
| ashburn | US East Coast (Virginia) | 34.203.254.0/24 3.235.111.128/25 |
Traffic is secure web socket over TCP